feat: Add localeCookie option for middleware (amannn#1414)

Author: amannn

.size-limit.ts

@@ -60,7 +60,7 @@ const config: SizeLimitConfig = [
   {
     name: 'import createMiddleware from \'next-intl/middleware\'',
     path: 'dist/production/middleware.js',
-    limit: '9.63 KB'
+    limit: '9.675 KB'
   },
   {
     name: 'import * from \'next-intl/routing\'',
@@ -71,7 +71,7 @@ const config: SizeLimitConfig = [
     name: 'import * from \'next-intl\' (react-client, ESM)',
     path: 'dist/esm/index.react-client.js',
     import: '*',
-    limit: '14.265 kB'
+    limit: '14.245 kB'
   },
   {
     name: 'import {NextIntlProvider} from \'next-intl\' (react-client, ESM)',

src/middleware/config.tsx

@@ -1,8 +1,38 @@
+import {NextResponse} from 'next/server';
+
+type ResponseCookieOptions = Pick<
+  NonNullable<Parameters<typeof NextResponse.prototype.cookies.set>['2']>,
+  | 'maxAge'
+  | 'domain'
+  | 'expires'
+  | 'partitioned'
+  | 'path'
+  | 'priority'
+  | 'sameSite'
+  | 'secure'
+  // Not:
+  // - 'httpOnly' (the client side needs to read the cookie)
+  // - 'name' (the client side needs to know this as well)
+  // - 'value' (only the middleware knows this)
+>;
+
 export type MiddlewareOptions = {
-  /** Sets the `Link` response header to notify search engines about content in other languages (defaults to `true`). See https://developers.google.com/search/docs/specialty/international/localized-versions#http */
+  /**
+   * Sets the `Link` response header to notify search engines about content in other languages (defaults to `true`). See https://developers.google.com/search/docs/specialty/international/localized-versions#http
+   * @see https://next-intl-docs.vercel.app/docs/routing/middleware#alternate-links
+   **/
   alternateLinks?: boolean;
 
-  /** By setting this to `false`, the cookie as well as the `accept-language` header will no longer be used for locale detection. */
+  /**
+   * Can be used to disable the locale cookie or to customize it.
+   * @see https://next-intl-docs.vercel.app/docs/routing/middleware#locale-cookie
+   */
+  localeCookie?: boolean | ResponseCookieOptions;
+
+  /**
+   * By setting this to `false`, the cookie as well as the `accept-language` header will no longer be used for locale detection.
+   * @see https://next-intl-docs.vercel.app/docs/routing/middleware#locale-detection
+   **/
   localeDetection?: boolean;
 };
 

src/middleware/middleware.test.tsx

@@ -294,6 +294,24 @@ describe('prefix-based routing', () => {
       });
     });
 
+    it('can turn off the cookie', () => {
+      const response = createMiddleware(routing, {localeCookie: false})(
+        createMockRequest('/')
+      );
+      expect(response.cookies.get('NEXT_LOCALE')).toBeUndefined();
+    });
+
+    it('restricts which options of the cookie can be customized', () => {
+      createMiddleware(routing, {
+        localeCookie: {
+          // @ts-expect-error
+          httpOnly: true,
+          name: 'custom',
+          value: 'custom'
+        }
+      });
+    });
+
     it('retains request headers for the default locale', () => {
       middleware(
         createMockRequest('/', 'en', 'http://localhost:3000', undefined, {

src/middleware/middleware.tsx

@@ -49,7 +49,8 @@ export default function createMiddleware<
   const resolvedOptions = {
     alternateLinks: options?.alternateLinks ?? routing.alternateLinks ?? true,
     localeDetection:
-      options?.localeDetection ?? routing?.localeDetection ?? true
+      options?.localeDetection ?? routing?.localeDetection ?? true,
+    localeCookie: options?.localeCookie ?? routing?.localeCookie ?? true
   };
 
   return function middleware(request: NextRequest) {
@@ -311,8 +312,8 @@ export default function createMiddleware<
       }
     }
 
-    if (resolvedOptions.localeDetection) {
-      syncCookie(request, response, locale);
+    if (resolvedOptions.localeDetection && resolvedOptions.localeCookie) {
+      syncCookie(request, response, locale, resolvedOptions.localeCookie);
     }
 
     if (

src/middleware/syncCookie.tsx

@@ -4,19 +4,23 @@ import {
   COOKIE_MAX_AGE,
   COOKIE_SAME_SITE
 } from '../shared/constants';
+import {MiddlewareOptions} from './config';
 
 export default function syncCookie(
   request: NextRequest,
   response: NextResponse,
-  locale: string
+  locale: string,
+  localeCookie: MiddlewareOptions['localeCookie']
 ) {
   const hasOutdatedCookie =
     request.cookies.get(COOKIE_LOCALE_NAME)?.value !== locale;
+
   if (hasOutdatedCookie) {
     response.cookies.set(COOKIE_LOCALE_NAME, locale, {
       path: request.nextUrl.basePath || undefined,
       sameSite: COOKIE_SAME_SITE,
-      maxAge: COOKIE_MAX_AGE
+      maxAge: COOKIE_MAX_AGE,
+      ...(typeof localeCookie === 'object' && localeCookie)
     });
   }
 }