@better-i18n/next 0.1.3 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-i18n/next",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Better-i18n Next.js integration",
   "license": "MIT",
   "repository": {

package/src/client.ts

@@ -1,15 +1,11 @@
 "use client";
 
 import { useEffect, useMemo, useState } from "react";
+import { createI18nCore } from "@better-i18n/core";
+import type { LanguageOption } from "@better-i18n/core";
 
-import { getProjectBaseUrl, normalizeConfig } from "./config";
-import { createLogger } from "./logger";
-import { extractLanguages } from "./manifest";
-import type {
-  I18nConfig,
-  LanguageOption,
-  ManifestResponse,
-} from "./types";
+import { normalizeConfig } from "./config";
+import type { I18nConfig } from "./types";
 
 export type UseManifestLanguagesResult = {
   languages: LanguageOption[];
@@ -23,116 +19,111 @@ type ClientCacheEntry = {
   promise?: Promise<LanguageOption[]>;
 };
 
+// Client-side request deduplication cache
 const clientCache = new Map<string, ClientCacheEntry>();
 
-const getCacheKey = (config: I18nConfig) =>
-  `${config.cdnBaseUrl || "https://cdn.better-i18n.com"}|${config.project}`;
-
-const fetchManifestLanguages = async (
-  config: I18nConfig,
-  logger: ReturnType<typeof createLogger>,
-  signal?: AbortSignal,
-): Promise<LanguageOption[]> => {
-  const normalized = normalizeConfig(config);
-  const url = `${getProjectBaseUrl(normalized)}/manifest.json`;
-  logger.debug("fetch", url);
-
-  const response = await (normalized.fetch ?? fetch)(url, {
-    cache: "no-store",
-    signal,
-  });
-
-  if (!response.ok) {
-    throw new Error(`[better-i18n] Manifest fetch failed (${response.status})`);
-  }
-
-  const data = (await response.json()) as ManifestResponse;
-  const languages = extractLanguages(data);
-
-  if (languages.length === 0) {
-    throw new Error("[better-i18n] No languages found in manifest");
-  }
-
-  return languages;
-};
-
-export const useManifestLanguages = (
-  config: I18nConfig,
-): UseManifestLanguagesResult => {
+const getCacheKey = (project: string, cdnBaseUrl?: string) =>
+  `${cdnBaseUrl || "https://cdn.better-i18n.com"}|${project}`;
+
+/**
+ * React hook to fetch manifest languages on the client
+ *
+ * Uses `createI18nCore` from `@better-i18n/core` internally with
+ * request deduplication to prevent duplicate fetches.
+ *
+ * @example
+ * ```tsx
+ * const { languages, isLoading, error } = useManifestLanguages({
+ *   project: 'acme/dashboard',
+ *   defaultLocale: 'en',
+ * })
+ *
+ * if (isLoading) return <Spinner />
+ * if (error) return <Error message={error.message} />
+ *
+ * return (
+ *   <select>
+ *     {languages.map(lang => (
+ *       <option key={lang.code} value={lang.code}>
+ *         {lang.nativeName || lang.name || lang.code}
+ *       </option>
+ *     ))}
+ *   </select>
+ * )
+ * ```
+ */
+export const useManifestLanguages = (config: I18nConfig): UseManifestLanguagesResult => {
   const normalized = useMemo(
     () => normalizeConfig(config),
     [
       config.project,
       config.defaultLocale,
       config.cdnBaseUrl,
-      config.localePrefix,
       config.debug,
       config.logLevel,
-      config.manifestCacheTtlMs,
-      config.manifestRevalidateSeconds,
-      config.messagesRevalidateSeconds,
-      config.fetch,
     ],
   );
-  const logger = useMemo(() => createLogger(normalized, "client"), [
-    normalized,
-  ]);
 
-  const cacheKey = getCacheKey(normalized);
+  const i18nCore = useMemo(
+    () =>
+      createI18nCore({
+        project: normalized.project,
+        defaultLocale: normalized.defaultLocale,
+        cdnBaseUrl: normalized.cdnBaseUrl,
+        debug: normalized.debug,
+        logLevel: normalized.logLevel,
+      }),
+    [normalized],
+  );
+
+  const cacheKey = getCacheKey(normalized.project, normalized.cdnBaseUrl);
   const cached = clientCache.get(cacheKey);
 
-  const [languages, setLanguages] = useState<LanguageOption[]>(
-    cached?.data ?? [],
-  );
+  const [languages, setLanguages] = useState<LanguageOption[]>(cached?.data ?? []);
   const [isLoading, setIsLoading] = useState(!cached?.data);
   const [error, setError] = useState<Error | null>(cached?.error ?? null);
 
   useEffect(() => {
     let isMounted = true;
-    const controller = new AbortController();
 
     const run = async () => {
-      try {
-        const entry = clientCache.get(cacheKey) ?? {};
-
-        if (entry.data) {
-          if (isMounted) {
-            setLanguages(entry.data);
-            setError(entry.error ?? null);
-            setIsLoading(false);
-          }
-          return;
-        }
+      const entry = clientCache.get(cacheKey) ?? {};
 
-        if (!entry.promise) {
-          entry.promise = fetchManifestLanguages(
-            normalized,
-            logger,
-            controller.signal,
-          )
-            .then((nextLanguages) => {
-              clientCache.set(cacheKey, { data: nextLanguages });
-              return nextLanguages;
-            })
-            .catch((err) => {
-              const nextError = err instanceof Error ? err : new Error(String(err));
-              clientCache.set(cacheKey, { error: nextError });
-              throw nextError;
-            });
-          clientCache.set(cacheKey, entry);
+      // Return cached data if available
+      if (entry.data) {
+        if (isMounted) {
+          setLanguages(entry.data);
+          setIsLoading(false);
         }
+        return;
+      }
 
-        const nextLanguages = await entry.promise;
+      // Deduplicate in-flight requests
+      if (!entry.promise) {
+        entry.promise = i18nCore
+          .getLanguages()
+          .then((langs) => {
+            clientCache.set(cacheKey, { data: langs });
+            return langs;
+          })
+          .catch((err) => {
+            const error = err instanceof Error ? err : new Error(String(err));
+            clientCache.set(cacheKey, { error });
+            throw error;
+          });
+        clientCache.set(cacheKey, entry);
+      }
 
+      try {
+        const langs = await entry.promise;
         if (isMounted) {
-          setLanguages(nextLanguages);
+          setLanguages(langs);
           setError(null);
         }
       } catch (err) {
-        if (!isMounted) return;
-        const nextError = err instanceof Error ? err : new Error(String(err));
-        logger.error(nextError);
-        setError(nextError);
+        if (isMounted) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+        }
       } finally {
         if (isMounted) {
           setIsLoading(false);
@@ -144,9 +135,8 @@ export const useManifestLanguages = (
 
     return () => {
       isMounted = false;
-      controller.abort();
     };
-  }, [cacheKey, logger, normalized]);
+  }, [cacheKey, i18nCore]);
 
   return { languages, isLoading, error };
 };

package/src/index.ts

@@ -1,28 +1,61 @@
 import type { I18nConfig } from "./types";
 import { normalizeConfig } from "./config";
 import {
+  createNextI18nCore,
   createNextIntlRequestConfig,
-  getLocales,
-  getManifest,
-  getMessages,
 } from "./server";
-import { createI18nMiddleware, createI18nProxy } from "./middleware";
+import {
+  createI18nMiddleware,
+  createI18nProxy,
+  createBetterI18nMiddleware,
+  composeMiddleware,
+} from "./middleware";
 
+/**
+ * Create a complete i18n setup for Next.js
+ *
+ * @example
+ * ```ts
+ * // i18n/config.ts
+ * import { createI18n } from '@better-i18n/next'
+ *
+ * export const i18n = createI18n({
+ *   project: 'acme/dashboard',
+ *   defaultLocale: 'en',
+ * })
+ *
+ * // i18n/request.ts
+ * export default i18n.requestConfig
+ *
+ * // middleware.ts
+ * export default i18n.middleware
+ * ```
+ */
 export const createI18n = (config: I18nConfig) => {
   const normalized = normalizeConfig(config);
+  const i18n = createNextI18nCore(normalized);
 
   return {
     config: normalized,
     requestConfig: createNextIntlRequestConfig(normalized),
     middleware: createI18nMiddleware(normalized),
     proxy: createI18nProxy(normalized),
-    getManifest: (options?: { forceRefresh?: boolean }) =>
-      getManifest(normalized, options),
-    getLocales: () => getLocales(normalized),
-    getMessages: (locale: string) => getMessages(normalized, locale),
+    getManifest: i18n.getManifest,
+    getLocales: i18n.getLocales,
+    getMessages: i18n.getMessages,
   };
 };
 
+// Modern standalone middleware exports
+export { createBetterI18nMiddleware, composeMiddleware };
+
+// Core instance factory
+export { createNextI18nCore } from "./server";
+
+// Client hook
+export { useManifestLanguages } from "./client";
+
+// Re-export types
 export type {
   I18nConfig,
   LanguageOption,
@@ -33,3 +66,5 @@ export type {
   ManifestResponse,
   Messages,
 } from "./types";
+
+export type { I18nMiddlewareConfig } from "@better-i18n/core";

package/src/middleware.ts

@@ -1,13 +1,10 @@
 import createMiddleware from "next-intl/middleware";
 import { NextRequest, NextResponse } from "next/server";
-// @ts-ignore - internal workspace dependency
-import { detectLocale, getLocales as getCDNLocales } from "@better-i18n/core";
-// @ts-ignore - internal workspace dependency
+import { createI18nCore, createLogger, detectLocale } from "@better-i18n/core";
 import type { I18nMiddlewareConfig } from "@better-i18n/core";
 
 import { normalizeConfig } from "./config";
-import { createLogger } from "./logger";
-import { getLocales } from "./core";
+import { getLocales } from "./server";
 import type { I18nConfig } from "./types";
 
 /**
@@ -46,9 +43,12 @@ export function createBetterI18nMiddleware(config: I18nMiddlewareConfig) {
     cookieMaxAge = 31536000,
   } = detection;
 
+  // Create i18n core instance for CDN operations
+  const i18nCore = createI18nCore({ project, defaultLocale });
+
   return async (request: NextRequest): Promise<NextResponse> => {
     // 1. Fetch available locales from CDN
-    const availableLocales = await getCDNLocales({ project });
+    const availableLocales = await i18nCore.getLocales();
 
     // 2. Extract locale indicators
     const pathLocale = request.nextUrl.pathname.split("/")[1];
@@ -67,8 +67,12 @@ export function createBetterI18nMiddleware(config: I18nMiddlewareConfig) {
       availableLocales,
     });
 
-    // 4. Create response
-    const response = NextResponse.next();
+    // 4. Create response with locale header for Server Components
+    const response = NextResponse.next({
+      headers: {
+        "x-locale": result.locale,
+      },
+    });
 
     // 5. Set cookie if needed
     if (cookie && result.shouldSetCookie) {

package/src/server.ts

@@ -1,23 +1,146 @@
 import { getRequestConfig } from "next-intl/server";
+import { createI18nCore } from "@better-i18n/core";
+import type { I18nCore, Messages } from "@better-i18n/core";
 
-import { normalizeConfig } from "./config";
-import { getLocales, getMessages } from "./core";
-import type { I18nConfig } from "./types";
+import { normalizeConfig, getProjectBaseUrl } from "./config";
+import type { I18nConfig, NextFetchRequestInit } from "./types";
 
+/**
+ * Next.js i18n core instance with ISR support
+ */
+export interface NextI18nCore extends I18nCore {
+  /**
+   * Get messages for a locale with Next.js ISR revalidation
+   */
+  getMessages: (locale: string) => Promise<Messages>;
+}
+
+/**
+ * Create a fetch function with Next.js ISR revalidation
+ */
+const createIsrFetch = (revalidateSeconds: number): typeof fetch => {
+  return (input: RequestInfo | URL, init?: RequestInit) => {
+    const nextInit: NextFetchRequestInit = {
+      ...init,
+      next: { revalidate: revalidateSeconds },
+    };
+    return fetch(input, nextInit);
+  };
+};
+
+/**
+ * Create a Next.js i18n core instance with ISR support
+ *
+ * This wraps the framework-agnostic `createI18nCore` from `@better-i18n/core`
+ * and adds Next.js-specific ISR revalidation for optimal caching.
+ *
+ * @example
+ * ```ts
+ * const i18n = createNextI18nCore({
+ *   project: 'acme/dashboard',
+ *   defaultLocale: 'en',
+ * })
+ *
+ * // Manifest cached for 1 hour (ISR)
+ * const locales = await i18n.getLocales()
+ *
+ * // Messages revalidated every 30s (ISR)
+ * const messages = await i18n.getMessages('en')
+ * ```
+ */
+export const createNextI18nCore = (config: I18nConfig): NextI18nCore => {
+  const normalized = normalizeConfig(config);
+
+  // Core instance uses ISR fetch for manifest (default 3600s)
+  const manifestFetch = createIsrFetch(normalized.manifestRevalidateSeconds);
+  const i18nCore = createI18nCore({
+    project: normalized.project,
+    defaultLocale: normalized.defaultLocale,
+    cdnBaseUrl: normalized.cdnBaseUrl,
+    manifestCacheTtlMs: normalized.manifestCacheTtlMs,
+    debug: normalized.debug,
+    logLevel: normalized.logLevel,
+    fetch: manifestFetch,
+  });
+
+  // Messages use separate ISR fetch with shorter revalidation (default 30s)
+  const messagesFetch = createIsrFetch(normalized.messagesRevalidateSeconds);
+
+  return {
+    ...i18nCore,
+    getMessages: async (locale: string): Promise<Messages> => {
+      const url = `${getProjectBaseUrl(normalized)}/${locale}/translations.json`;
+      const response = await messagesFetch(url);
+      if (!response.ok) {
+        throw new Error(`[better-i18n] Messages fetch failed for locale "${locale}" (${response.status})`);
+      }
+      return response.json();
+    },
+  };
+};
+
+/**
+ * Create next-intl request config for App Router
+ *
+ * @example
+ * ```ts
+ * // i18n/request.ts
+ * import { createNextIntlRequestConfig } from '@better-i18n/next/server'
+ *
+ * export default createNextIntlRequestConfig({
+ *   project: 'acme/dashboard',
+ *   defaultLocale: 'en',
+ * })
+ * ```
+ */
 export const createNextIntlRequestConfig = (config: I18nConfig) =>
   getRequestConfig(async ({ requestLocale }) => {
-    const locales = await getLocales(config);
+    const i18n = createNextI18nCore(config);
+    const normalized = normalizeConfig(config);
+    const locales = await i18n.getLocales();
     let locale = await requestLocale;
 
     if (!locale || !locales.includes(locale)) {
-      locale = normalizeConfig(config).defaultLocale;
+      locale = normalized.defaultLocale;
     }
 
     return {
       locale,
-      messages: await getMessages(config, locale),
+      messages: await i18n.getMessages(locale),
     };
   });
 
-export { fetchManifest, getLocales, getManifest, getManifestLanguages, getMessages } from "./core";
-export type { LanguageOption, ManifestLanguage, ManifestResponse, Messages } from "./types";
+// Convenience exports for backwards compatibility
+
+/**
+ * Fetch manifest from CDN
+ */
+export const fetchManifest = (config: I18nConfig) =>
+  createNextI18nCore(config).getManifest();
+
+/**
+ * Get manifest with caching
+ */
+export const getManifest = (config: I18nConfig, options?: { forceRefresh?: boolean }) =>
+  createNextI18nCore(config).getManifest(options);
+
+/**
+ * Get available locale codes
+ */
+export const getLocales = (config: I18nConfig) =>
+  createNextI18nCore(config).getLocales();
+
+/**
+ * Get messages for a locale
+ */
+export const getMessages = (config: I18nConfig, locale: string) =>
+  createNextI18nCore(config).getMessages(locale);
+
+/**
+ * Get language options with metadata
+ */
+export const getManifestLanguages = (config: I18nConfig) =>
+  createNextI18nCore(config).getLanguages();
+
+// Re-export types from core
+export type { LanguageOption, ManifestLanguage, ManifestResponse, Messages } from "@better-i18n/core";

package/src/core.ts

@@ -1,147 +0,0 @@
-import { getProjectBaseUrl, normalizeConfig } from "./config";
-import { createLogger } from "./logger";
-import { extractLanguages } from "./manifest";
-import type {
-  I18nConfig,
-  LanguageOption,
-  ManifestResponse,
-  Messages,
-  NextFetchRequestInit,
-  NormalizedConfig,
-} from "./types";
-
-type ManifestCacheEntry = {
-  value: ManifestResponse;
-  expiresAt: number;
-};
-
-const manifestCache = new Map<string, ManifestCacheEntry>();
-
-const buildCacheKey = (config: NormalizedConfig) =>
-  `${config.cdnBaseUrl}|${config.project}`;
-
-const withRevalidate = (
-  init: NextFetchRequestInit,
-  revalidateSeconds?: number,
-): NextFetchRequestInit => {
-  if (!revalidateSeconds || revalidateSeconds <= 0) {
-    return init;
-  }
-
-  const { cache, ...rest } = init;
-
-  return {
-    ...rest,
-    next: {
-      ...init.next,
-      revalidate: revalidateSeconds,
-    },
-  };
-};
-
-export const fetchManifest = async (
-  config: I18nConfig,
-  init: NextFetchRequestInit = {},
-): Promise<ManifestResponse> => {
-  const normalized = normalizeConfig(config);
-  const logger = createLogger(normalized, "manifest");
-  const url = `${getProjectBaseUrl(normalized)}/manifest.json`;
-  const requestInit = withRevalidate(
-    {
-      ...init,
-    },
-    normalized.manifestRevalidateSeconds,
-  );
-
-  logger.debug("fetch", url);
-
-  const fetchFn = normalized.fetch ?? fetch;
-  const response = await fetchFn(url, requestInit);
-
-  if (!response.ok) {
-    const message = `[better-i18n] Manifest fetch failed (${response.status})`;
-    logger.error(message);
-    throw new Error(message);
-  }
-
-  const data = (await response.json()) as ManifestResponse;
-  if (!Array.isArray(data.languages)) {
-    throw new Error("[better-i18n] Manifest payload missing languages array");
-  }
-
-  logger.debug("fetched", { languages: data.languages.length });
-  return data;
-};
-
-export const getManifest = async (
-  config: I18nConfig,
-  options: { forceRefresh?: boolean } = {},
-): Promise<ManifestResponse> => {
-  const normalized = normalizeConfig(config);
-  const cacheKey = buildCacheKey(normalized);
-  const now = Date.now();
-  const cached = manifestCache.get(cacheKey);
-
-  if (!options.forceRefresh && cached && cached.expiresAt > now) {
-    return cached.value;
-  }
-
-  const manifest = await fetchManifest(normalized);
-  manifestCache.set(cacheKey, {
-    value: manifest,
-    expiresAt: now + (normalized.manifestCacheTtlMs ?? 0),
-  });
-
-  return manifest;
-};
-
-export const getLocales = async (config: I18nConfig): Promise<string[]> => {
-  const manifest = await getManifest(config);
-  const languages = extractLanguages(manifest);
-
-  if (languages.length === 0) {
-    throw new Error("[better-i18n] No locales found in manifest");
-  }
-
-  return languages.map((language) => language.code);
-};
-
-export const getMessages = async (
-  config: I18nConfig,
-  locale: string,
-): Promise<Messages> => {
-  const normalized = normalizeConfig(config);
-  const logger = createLogger(normalized, "messages");
-  const url = `${getProjectBaseUrl(normalized)}/${locale}/translations.json`;
-
-  const requestInit = withRevalidate(
-    {},
-    normalized.messagesRevalidateSeconds,
-  );
-
-  logger.debug("fetch", url);
-
-  const fetchFn = normalized.fetch ?? fetch;
-  const response = await fetchFn(url, requestInit);
-
-  if (!response.ok) {
-    const message = `[better-i18n] Messages fetch failed (${response.status})`;
-    logger.error(message);
-    throw new Error(message);
-  }
-
-  return (await response.json()) as Messages;
-};
-
-export const getManifestLanguages = async (
-  config: I18nConfig,
-): Promise<LanguageOption[]> => {
-  const manifest = await getManifest(config);
-  const languages = extractLanguages(manifest);
-
-  if (languages.length === 0) {
-    throw new Error("[better-i18n] No languages found in manifest");
-  }
-
-  return languages;
-};

package/src/logger.ts

@@ -1,68 +0,0 @@
-import type { Logger, LogLevel } from "@better-i18n/core";
-import type { I18nConfig } from "./types";
-
-const LEVEL_RANK: Record<LogLevel, number> = {
-  debug: 0,
-  info: 1,
-  warn: 2,
-  error: 3,
-  silent: 4,
-};
-
-const getEnv = (key: string): string | undefined => {
-  if (typeof process === "undefined" || !process.env) {
-    return undefined;
-  }
-  return process.env[key];
-};
-
-const normalizeLevel = (level?: string): LogLevel | undefined => {
-  if (!level) return undefined;
-  const normalized = level.toLowerCase();
-  if (normalized in LEVEL_RANK) {
-    return normalized as LogLevel;
-  }
-  return undefined;
-};
-
-const resolveLevel = (config: I18nConfig): LogLevel => {
-  const envDebug = getEnv("BETTER_I18N_DEBUG");
-  if (envDebug && envDebug !== "0" && envDebug.toLowerCase() !== "false") {
-    return "debug";
-  }
-
-  const envLevel = normalizeLevel(getEnv("BETTER_I18N_LOG_LEVEL"));
-  if (envLevel) return envLevel;
-
-  if (config.logLevel) return config.logLevel;
-  if (config.debug) return "debug";
-
-  return "warn";
-};
-
-const shouldLog = (current: LogLevel, target: LogLevel) =>
-  LEVEL_RANK[target] >= LEVEL_RANK[current];
-
-export const createLogger = (config: I18nConfig, scope = "core"): Logger => {
-  const level = resolveLevel(config);
-  const prefix = `[better-i18n:${scope}]`;
-
-  return {
-    debug: (...args: unknown[]) => {
-      if (!shouldLog(level, "debug")) return;
-      console.debug(prefix, ...args);
-    },
-    info: (...args: unknown[]) => {
-      if (!shouldLog(level, "info")) return;
-      console.info(prefix, ...args);
-    },
-    warn: (...args: unknown[]) => {
-      if (!shouldLog(level, "warn")) return;
-      console.warn(prefix, ...args);
-    },
-    error: (...args: unknown[]) => {
-      if (!shouldLog(level, "error")) return;
-      console.error(prefix, ...args);
-    },
-  };
-};

package/src/manifest.ts

@@ -1,2 +0,0 @@
-// Re-export from i18n-core
-export { extractLanguages } from "@better-i18n/core";