@akinon/next 2.0.99-beta.0 → 2.0.99-rc.0

package/hooks/use-client-env.ts

@@ -0,0 +1,265 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+/**
+ * Runtime access to public (`NEXT_PUBLIC_*`) environment variables from Client
+ * Components.
+ *
+ * `process.env.NEXT_PUBLIC_*` is inlined at *build* time, so on platforms where
+ * the build has no environment (e.g. Akinon Cloud Commerce) it resolves to
+ * `undefined` in the browser. These helpers read the value from the server
+ * runtime through the `/api/client-env` route handler instead
+ * (`@akinon/next/api/client-env`).
+ *
+ * Always pass the full variable name, including the `NEXT_PUBLIC_` prefix:
+ *
+ * ```tsx
+ * // inside a Client Component
+ * const { value, isLoading } = useClientEnv('NEXT_PUBLIC_MAP_API_KEY');
+ *
+ * // imperative (event handlers, third-party init, ...)
+ * const key = await getClientEnv('NEXT_PUBLIC_MAP_API_KEY');
+ * ```
+ *
+ * Server Components do not need this — read the value with computed access
+ * (`process.env['NEXT_PUBLIC_MAP_API_KEY']`) so it is not build-time inlined.
+ */
+
+const ENDPOINT = '/api/client-env';
+
+// Shared across every caller so each variable is fetched at most once per page
+// load, no matter how many components ask for it.
+const cache = new Map<string, string | null>();
+const inflight = new Map<string, Promise<string | null>>();
+
+function request(names: string[]): void {
+  const pending = names.filter(
+    (name) => !cache.has(name) && !inflight.has(name)
+  );
+
+  if (pending.length === 0) return;
+
+  const query = pending
+    .map((name) => `env=${encodeURIComponent(name)}`)
+    .join('&');
+
+  const response = fetch(`${ENDPOINT}?${query}`, {
+    headers: { Accept: 'application/json' }
+  })
+    .then((res) => {
+      if (!res.ok) {
+        throw new Error(`Failed to load client env (status ${res.status}).`);
+      }
+      return res.json() as Promise<Record<string, string | null>>;
+    })
+    .then((data) => {
+      pending.forEach((name) => cache.set(name, data?.[name] ?? null));
+    });
+
+  // One in-flight entry per name so concurrent callers dedupe. On failure the
+  // entry is cleared (not cached) so a later render can retry.
+  pending.forEach((name) => {
+    inflight.set(
+      name,
+      response
+        .then(() => cache.get(name) ?? null)
+        .finally(() => inflight.delete(name))
+    );
+  });
+}
+
+function resolve(name: string): Promise<string | null> {
+  if (cache.has(name)) return Promise.resolve(cache.get(name) ?? null);
+  return inflight.get(name) ?? Promise.resolve(null);
+}
+
+/**
+ * Read a single public (`NEXT_PUBLIC_*`) environment variable at runtime,
+ * outside React (event handlers, third-party SDK init, …). Cached and
+ * deduplicated across callers.
+ *
+ * @param name - Full variable name, including the `NEXT_PUBLIC_` prefix.
+ * @returns The runtime value, or `null` when the variable is unset. Rejects if
+ * the request fails, so wrap direct calls in `try`/`catch`. A failed request is
+ * not cached — a later call retries.
+ *
+ * @example
+ * ```tsx
+ * import { getClientEnv } from '@akinon/next/hooks'
+ *
+ * const handleShare = async () => {
+ *   const baseUrl = await getClientEnv('NEXT_PUBLIC_URL')
+ *   navigator.clipboard.writeText(`${baseUrl}/product/123`)
+ * }
+ * ```
+ */
+export async function getClientEnv(name: string): Promise<string | null> {
+  request([name]);
+  return resolve(name);
+}
+
+/**
+ * Read several public (`NEXT_PUBLIC_*`) environment variables at runtime in a
+ * single request, outside React.
+ *
+ * @param names - Full variable names, each including the `NEXT_PUBLIC_` prefix.
+ * @returns A `{ [name]: value | null }` map. Rejects if the request fails.
+ *
+ * @example
+ * ```ts
+ * import { getClientEnvs } from '@akinon/next/hooks'
+ *
+ * const env = await getClientEnvs(['NEXT_PUBLIC_GTM_KEY', 'NEXT_PUBLIC_URL'])
+ * // env['NEXT_PUBLIC_URL']
+ * ```
+ */
+export async function getClientEnvs(
+  names: string[]
+): Promise<Record<string, string | null>> {
+  request(names);
+  const values = await Promise.all(names.map((name) => resolve(name)));
+  return names.reduce<Record<string, string | null>>((acc, name, index) => {
+    acc[name] = values[index];
+    return acc;
+  }, {});
+}
+
+/**
+ * Read a single public (`NEXT_PUBLIC_*`) environment variable at runtime from a
+ * Client Component.
+ *
+ * @param name - Full variable name, including the `NEXT_PUBLIC_` prefix.
+ * @returns `{ value, isLoading, error }`. `value` is `null` while loading, when
+ * the variable is unset, or on failure.
+ *
+ * @example
+ * ```tsx
+ * 'use client'
+ * import { useClientEnv } from '@akinon/next/hooks'
+ *
+ * export const StoreMap = () => {
+ *   const { value: mapApiKey, isLoading } = useClientEnv('NEXT_PUBLIC_MAP_API_KEY')
+ *
+ *   if (isLoading) return <Spinner />
+ *   if (!mapApiKey) return null
+ *
+ *   return <GoogleMap apiKey={mapApiKey} />
+ * }
+ * ```
+ */
+export function useClientEnv(name: string) {
+  const [value, setValue] = useState<string | null>(
+    () => cache.get(name) ?? null
+  );
+  const [isLoading, setIsLoading] = useState(() => !cache.has(name));
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    let active = true;
+
+    if (cache.has(name)) {
+      setValue(cache.get(name) ?? null);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    getClientEnv(name)
+      .then((resolved) => {
+        if (!active) return;
+        setValue(resolved);
+        setIsLoading(false);
+      })
+      .catch((err) => {
+        if (!active) return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setIsLoading(false);
+      });
+
+    return () => {
+      active = false;
+    };
+  }, [name]);
+
+  return { value, isLoading, error };
+}
+
+/**
+ * Read several public (`NEXT_PUBLIC_*`) environment variables at runtime in a
+ * single request from a Client Component.
+ *
+ * @param names - Full variable names, each including the `NEXT_PUBLIC_` prefix.
+ * @returns `{ values, isLoading, error }` where `values` is a
+ * `{ [name]: value | null }` map.
+ *
+ * @example
+ * ```tsx
+ * 'use client'
+ * import { useClientEnvs } from '@akinon/next/hooks'
+ *
+ * const { values, isLoading } = useClientEnvs([
+ *   'NEXT_PUBLIC_GTM_KEY',
+ *   'NEXT_PUBLIC_URL'
+ * ])
+ *
+ * const gtmKey = values['NEXT_PUBLIC_GTM_KEY']
+ * ```
+ */
+export function useClientEnvs(names: string[]) {
+  // Stable serialization so the effect re-runs only when the set changes, not
+  // on every render (a new array identity would otherwise loop it forever).
+  const key = names.join(',');
+
+  const [values, setValues] = useState<Record<string, string | null>>(() => {
+    const initial: Record<string, string | null> = {};
+    names.forEach((name) => {
+      if (cache.has(name)) initial[name] = cache.get(name) ?? null;
+    });
+    return initial;
+  });
+  const [isLoading, setIsLoading] = useState(
+    () => !names.every((name) => cache.has(name))
+  );
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    let active = true;
+    const list = key ? key.split(',') : [];
+
+    if (list.every((name) => cache.has(name))) {
+      const resolved: Record<string, string | null> = {};
+      list.forEach((name) => (resolved[name] = cache.get(name) ?? null));
+      setValues(resolved);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    getClientEnvs(list)
+      .then((resolved) => {
+        if (!active) return;
+        setValues(resolved);
+        setIsLoading(false);
+      })
+      .catch((err) => {
+        if (!active) return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setIsLoading(false);
+      });
+
+    return () => {
+      active = false;
+    };
+    // `key` is the stable serialization of `names`.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+
+  return { values, isLoading, error };
+}