@better-i18n/next 0.2.4 → 0.4.0

package/package.json

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

package/src/index.ts

@@ -9,6 +9,7 @@ import {
   createI18nProxy,
   createBetterI18nMiddleware,
   composeMiddleware,
+  type MiddlewareCallback,
 } from "./middleware";
 
 /**
@@ -22,13 +23,21 @@ import {
  * export const i18n = createI18n({
  *   project: 'acme/dashboard',
  *   defaultLocale: 'en',
+ *   localePrefix: 'always',
  * })
  *
  * // i18n/request.ts
  * export default i18n.requestConfig
  *
- * // middleware.ts
+ * // middleware.ts (simple)
  * export default i18n.middleware
+ *
+ * // middleware.ts (with auth - Clerk-style)
+ * export default i18n.betterMiddleware(async (request, { locale }) => {
+ *   if (needsLogin) {
+ *     return NextResponse.redirect(new URL(`/${locale}/login`, request.url));
+ *   }
+ * });
  * ```
  */
 export const createI18n = (config: I18nConfig) => {
@@ -38,16 +47,51 @@ export const createI18n = (config: I18nConfig) => {
   return {
     config: normalized,
     requestConfig: createNextIntlRequestConfig(normalized),
+    /** @deprecated Use betterMiddleware() for Clerk-style callback support */
     middleware: createI18nMiddleware(normalized),
     proxy: createI18nProxy(normalized),
     getManifest: i18n.getManifest,
     getLocales: i18n.getLocales,
     getMessages: i18n.getMessages,
+
+    /**
+     * Create middleware with optional Clerk-style callback for auth integration
+     *
+     * @example Simple usage
+     * ```ts
+     * export default i18n.betterMiddleware();
+     * ```
+     *
+     * @example With auth callback
+     * ```ts
+     * export default i18n.betterMiddleware(async (request, { locale, response }) => {
+     *   if (needsLogin) {
+     *     return NextResponse.redirect(new URL(`/${locale}/login`, request.url));
+     *   }
+     *   // Return nothing = i18n response is used (headers preserved!)
+     * });
+     * ```
+     */
+    betterMiddleware: (callback?: MiddlewareCallback) => {
+      return createBetterI18nMiddleware(
+        {
+          project: normalized.project,
+          defaultLocale: normalized.defaultLocale,
+          localePrefix: normalized.localePrefix,
+          detection: {
+            cookie: true,
+            browserLanguage: true,
+          },
+        },
+        callback
+      );
+    },
   };
 };
 
 // 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,13 +53,40 @@ 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) {
+export function createBetterI18nMiddleware(
+  config: I18nMiddlewareConfig,
+  callback?: MiddlewareCallback
+) {
   const { project, defaultLocale, localePrefix = "as-needed", detection = {} } = config;
 
   const {
@@ -88,40 +137,95 @@ export function createBetterI18nMiddleware(config: I18nMiddlewareConfig) {
     // 4. Call next-intl middleware (sets x-middleware-request-x-next-intl-locale header)
     const response = cachedMiddleware(request);
 
-    // 5. Add x-locale header for backwards compatibility
-    response.headers.set("x-locale", result.locale);
+    // 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. Set our custom cookie if needed
+    // 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;
   };
 }