Share: How to Fix Service Worker Precache Causing Incorrect Locale Cookie Setting with next-intl

[bolechen]

Context:

• Framework: Next.js 16 with next-intl
• Service Worker: Serwist (Workbox successor)
• i18n Mode: localePrefix: "as-needed" (default locale zh has no prefix, other locales like /en/ have prefix)
• Problem: Service Worker pre-caching was causing incorrect locale cookie setting

The Problem

When using next-intl with localePrefix: "as-needed" mode alongside Serwist Service Worker:

1. Service Worker's precache mechanism requests all pages during installation, including locale-prefixed routes (e.g.,
   /en/all, /en/chat)
2. These precache requests go through the middleware
3. The middleware detects the locale from the path and sets NEXT_LOCALE=en cookie
4. This overwrites the user's actual language preference, even if they were browsing in Chinese (the default locale)

Root Cause

The issue occurs because:

• Service Worker runs at browser layer (caching static resources)
• Middleware runs at server layer (locale routing and authentication)
• When SW precaches /en/* routes, it triggers middleware to set locale cookies
• This incorrectly persists the non-default language preference

The Solution

We implemented a two-layer fix:

1. Service Worker Layer (src/sw/index.ts)

Exclude locale-prefixed routes from precaching:

  import { routing } from "../i18n/routing";

  function shouldExcludeLocalePrefixedRoutes(url: string): boolean {
    const urlPath = url.split("?")[0].replace(/^https?:\/\/[^/]+/, "");

    // Dynamically generate regex to match all supported locale prefixes
    const locales = routing.locales as readonly string[];
    const localePattern = `^\\/(${locales.join("|")})(\\/|$)`;
    const localeRegex = new RegExp(localePattern);

    return localeRegex.test(urlPath);
  }

  const filterPrecacheEntries = (entry: PrecacheEntry) => {
    const url = entry.url;

    // Exclude locale-prefixed routes from precaching
    if (shouldExcludeLocalePrefixedRoutes(url)) {
      return false;
    }

    return true;
  };

Why this works:

• Only caches default locale versions (e.g., /all, /chat)
• Non-default locale pages (e.g., /en/all) are handled by runtime cache strategies
• Prevents SW from triggering middleware during precache

2. Middleware Layer (src/proxy.ts)

Explicitly set cookies for default locale, skip prefetch requests:

  function processInternationalization(
    request: NextRequest,
    shouldSkipIntl: boolean,
    hasLocalePrefix: boolean
  ): NextResponse | null {
    const response = intlMiddleware(request);

    // Skip prefetch requests to avoid overwriting cookies
    const isPrefetchRequest =
      request.headers.get("x-middleware-prefetch") === "1";

    if (response && !hasLocalePrefix && !isPrefetchRequest) {
      const cookieName = getLocaleCookieName();
      const defaultLocale = getDefaultLocale();

      // Check if cookie already exists
      const requestCookie = request.cookies.get(cookieName);
      const responseCookie = response.cookies.get(cookieName);
      const hasCookie = requestCookie !== undefined || responseCookie !== undefined;

      // Explicitly set cookie for default locale
      if (!hasCookie) {
        const detectedLocale =
          response.headers.get("x-next-intl-locale") ?? defaultLocale;

        if (detectedLocale === defaultLocale) {
          response.cookies.set(cookieName, defaultLocale, {
            maxAge: 60 * 60 * 24 * 365, // 1 year
            sameSite: "lax",
            path: "/",
          });
        }
      }
    }

    return response;
  }

Why this works:

• Ensures default locale preference is persisted
• Skips cookie setting during prefetch to prevent overwriting
• Aligns with next-intl's philosophy of "remembering user's locale preference"

Key Takeaways

1. Service Worker and middleware operate at different layers - they don't conflict, but SW can trigger middleware during
   precache
2. Exclude locale-prefixed routes from precaching - only cache default locale versions
3. Detect and skip prefetch requests - use x-middleware-prefetch header to identify them
4. Maintain single source of truth - import routing config directly to ensure consistency

This fix ensures that Service Worker precaching doesn't interfere with user language preferences, providing a consistent i18n
experience across all locales.