@better-i18n/next 0.2.3 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-i18n/next",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Better-i18n Next.js integration",
   "license": "MIT",
   "repository": {
@@ -57,7 +57,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@better-i18n/core": "0.1.4"
+    "@better-i18n/core": "0.1.6"
   },
   "peerDependencies": {
     "next": ">=15.0.0",

package/src/index.ts

@@ -48,6 +48,7 @@ export const createI18n = (config: I18nConfig) => {
 
 // Modern standalone middleware exports
 export { createBetterI18nMiddleware, composeMiddleware };
+export type { MiddlewareContext, MiddlewareCallback } from "./middleware";
 
 // Core instance factory
 export { createNextI18nCore } from "./server";

package/src/middleware.ts

@@ -7,6 +7,28 @@ import { normalizeConfig } from "./config";
 import { getLocales } from "./server";
 import type { I18nConfig } from "./types";
 
+/**
+ * Context passed to the middleware callback (Clerk-style pattern)
+ */
+export interface MiddlewareContext {
+  /** Detected locale from the request */
+  locale: string;
+  /** The i18n response with headers already set - can be modified */
+  response: NextResponse;
+}
+
+/**
+ * Callback function for Clerk-style middleware composition
+ *
+ * @param request - The incoming Next.js request
+ * @param context - Contains locale and response from i18n middleware
+ * @returns NextResponse to short-circuit (e.g., redirect), or void to continue with i18n response
+ */
+export type MiddlewareCallback = (
+  request: NextRequest,
+  context: MiddlewareContext
+) => Promise<NextResponse | void> | NextResponse | void;
+
 /**
  * Legacy Next-intl based middleware
  */
@@ -31,10 +53,41 @@ export const createI18nMiddleware = (config: I18nConfig) => {
 export const createI18nProxy = createI18nMiddleware;
 
 /**
- * Modern composable middleware for Better i18n
+ * Modern composable middleware for Better i18n (Clerk-style pattern)
+ *
+ * Delegates to next-intl's middleware internally to ensure full compatibility
+ * with `getRequestConfig({ requestLocale })` while keeping our compose-friendly
+ * API and custom locale detection options.
+ *
+ * @example Simple usage (no callback)
+ * ```ts
+ * export default createBetterI18nMiddleware({
+ *   project: "acme/dashboard",
+ *   defaultLocale: "en",
+ *   localePrefix: "always",
+ * });
+ * ```
+ *
+ * @example With callback (Clerk-style - recommended for auth)
+ * ```ts
+ * export default createBetterI18nMiddleware({
+ *   project: "acme/dashboard",
+ *   defaultLocale: "en",
+ *   localePrefix: "always",
+ * }, async (request, { locale, response }) => {
+ *   // Auth logic here - locale and response are available
+ *   if (needsLogin) {
+ *     return NextResponse.redirect(new URL(`/${locale}/login`, request.url));
+ *   }
+ *   // Return nothing = i18n response is used (headers preserved!)
+ * });
+ * ```
  */
-export function createBetterI18nMiddleware(config: I18nMiddlewareConfig) {
-  const { project, defaultLocale, detection = {} } = config;
+export function createBetterI18nMiddleware(
+  config: I18nMiddlewareConfig,
+  callback?: MiddlewareCallback
+) {
+  const { project, defaultLocale, localePrefix = "as-needed", detection = {} } = config;
 
   const {
     cookie = true,
@@ -46,18 +99,32 @@ export function createBetterI18nMiddleware(config: I18nMiddlewareConfig) {
   // Create i18n core instance for CDN operations
   const i18nCore = createI18nCore({ project, defaultLocale });
 
+  // Cache for next-intl middleware instance (recreate only when locales change)
+  let cachedMiddleware: ReturnType<typeof createMiddleware> | null = null;
+  let cachedLocalesKey: string | null = null;
+
   return async (request: NextRequest): Promise<NextResponse> => {
     // 1. Fetch available locales from CDN
     const availableLocales = await i18nCore.getLocales();
 
-    // 2. Extract locale indicators
+    // 2. Create/reuse next-intl middleware (only recreate if locales changed)
+    const localesKey = availableLocales.join(",");
+    if (!cachedMiddleware || cachedLocalesKey !== localesKey) {
+      cachedMiddleware = createMiddleware({
+        locales: availableLocales,
+        defaultLocale,
+        localePrefix,
+      });
+      cachedLocalesKey = localesKey;
+    }
+
+    // 3. Our custom locale detection (for cookie logic)
     const pathLocale = request.nextUrl.pathname.split("/")[1];
     const cookieLocale = cookie ? request.cookies.get(cookieName)?.value : null;
     const headerLocale = browserLanguage
       ? request.headers.get("accept-language")?.split(",")[0]?.split("-")[0]
       : null;
 
-    // 3. Detect locale using core logic
     const result = detectLocale({
       project,
       defaultLocale,
@@ -67,44 +134,98 @@ export function createBetterI18nMiddleware(config: I18nMiddlewareConfig) {
       availableLocales,
     });
 
-    // 4. Create response with locale header for Server Components
-    const response = NextResponse.next({
-      headers: {
-        "x-locale": result.locale,
-      },
-    });
+    // 4. Call next-intl middleware (sets x-middleware-request-x-next-intl-locale header)
+    const response = cachedMiddleware(request);
 
-    // 5. Set cookie if needed
+    // 5. Get detected locale from next-intl header (more accurate than our detection)
+    const detectedLocale =
+      response.headers.get("x-middleware-request-x-next-intl-locale") ||
+      result.locale;
+
+    // 6. Add x-locale header for backwards compatibility
+    response.headers.set("x-locale", detectedLocale);
+
+    // 7. Set our custom cookie if needed
     if (cookie && result.shouldSetCookie) {
-      response.cookies.set(cookieName, result.locale, {
+      response.cookies.set(cookieName, detectedLocale, {
         path: "/",
         maxAge: cookieMaxAge,
         sameSite: "lax",
       });
     }
 
+    // 8. If callback provided, execute it (Clerk-style)
+    if (callback) {
+      const callbackResult = await callback(request, {
+        locale: detectedLocale,
+        response,
+      });
+
+      // If callback returns a response (e.g., redirect), use it
+      if (callbackResult) {
+        return callbackResult;
+      }
+    }
+
+    // 9. Return the i18n response (with all headers preserved)
     return response;
   };
 }
 
 /**
  * Helper to compose multiple Next.js middleware
+ *
+ * @deprecated Use `createBetterI18nMiddleware` with a callback instead (Clerk-style pattern).
+ * The callback approach is more reliable and gives you access to the detected locale.
+ *
+ * @example Migration
+ * ```ts
+ * // Before (deprecated):
+ * export default composeMiddleware(i18nMiddleware, authMiddleware);
+ *
+ * // After (recommended):
+ * export default createBetterI18nMiddleware(config, async (req, { locale, response }) => {
+ *   // Auth logic here
+ * });
+ * ```
+ *
+ * @see https://github.com/better-i18n/better-i18n#middleware-composition
  */
 export function composeMiddleware(
   ...middlewares: Array<(req: NextRequest) => Promise<NextResponse>>
 ) {
+  if (process.env.NODE_ENV === "development") {
+    console.warn(
+      "[@better-i18n/next] composeMiddleware is deprecated. " +
+        "Use createBetterI18nMiddleware with a callback instead. " +
+        "See: https://github.com/better-i18n/better-i18n#middleware-composition"
+    );
+  }
+
   return async (request: NextRequest): Promise<NextResponse> => {
-    let response = NextResponse.next();
+    const finalResponse = NextResponse.next();
 
     for (const middleware of middlewares) {
-      response = await middleware(request);
+      const response = await middleware(request);
 
       // Short-circuit on redirect/rewrite (status >= 300)
       if (response.status >= 300) {
-        break;
+        return response;
       }
+
+      // Merge headers from this middleware into the final response
+      response.headers.forEach((value, key) => {
+        finalResponse.headers.set(key, value);
+      });
+
+      // Merge cookies from this middleware into the final response
+      response.cookies.getAll().forEach((cookie) => {
+        finalResponse.cookies.set(cookie.name, cookie.value, {
+          ...cookie,
+        });
+      });
     }
 
-    return response;
+    return finalResponse;
   };
 }