feat(core): use AsyncLocalStorage for locale

Co-Authored-By: Jerry_wu <[email protected]>

Author: wmertens

.changeset/pretty-parents-draw.md

@@ -0,0 +1,6 @@
+---
+'@qwik.dev/router': patch
+'@qwik.dev/core': patch
+---
+
+FEAT: withLocale() uses AsyncLocalStorage for server-side requests when available. This allows async operations to retain the correct locale context.

packages/docs/src/repl/bundler/rollup-plugins.ts

@@ -63,6 +63,10 @@ export const replResolver = (
       if (id.startsWith('/qwik/')) {
         return id;
       }
+      // Replace node: with modules that throw on import
+      if (id.startsWith('node:')) {
+        return id;
+      }
       const match = id.match(/(@builder\.io\/qwik|@qwik\.dev\/core)(.*)/);
       if (match) {
         const pkgName = match[2];
@@ -114,6 +118,9 @@ export const replResolver = (
       if (input && typeof input.code === 'string') {
         return input.code;
       }
+      if (id.startsWith('node:')) {
+        return `throw new Error('Module "${id}" is not available in the REPL environment.');`;
+      }
       if (id.startsWith('/qwik/')) {
         const path = id.slice('/qwik'.length);
         if (path === '/build') {

packages/qwik/src/core/use/use-locale.ts

@@ -1,7 +1,21 @@
 import { tryGetInvokeContext } from './use-core';
+import { isServer } from '@qwik.dev/core/build';
+import type { AsyncLocalStorage } from 'node:async_hooks';
 
 let _locale: string | undefined = undefined;
 
+let localAsyncStore: AsyncLocalStorage<string> | undefined;
+
+if (isServer) {
+  import('node:async_hooks')
+    .then((module) => {
+      localAsyncStore = new module.AsyncLocalStorage();
+    })
+    .catch(() => {
+      // ignore if AsyncLocalStorage is not available
+    });
+}
+
 /**
  * Retrieve the current locale.
  *
@@ -11,6 +25,14 @@ let _locale: string | undefined = undefined;
  * @public
  */
 export function getLocale(defaultLocale?: string): string {
+  // Prefer per-request locale from local AsyncLocalStorage if available (server-side)
+  if (localAsyncStore) {
+    const locale = localAsyncStore.getStore();
+    if (locale) {
+      return locale;
+    }
+  }
+
   if (_locale === undefined) {
     const ctx = tryGetInvokeContext();
     if (ctx && ctx.$locale$) {
@@ -30,6 +52,10 @@ export function getLocale(defaultLocale?: string): string {
  * @public
  */
 export function withLocale<T>(locale: string, fn: () => T): T {
+  if (localAsyncStore) {
+    return localAsyncStore.run(locale, fn);
+  }
+
   const previousLang = _locale;
   try {
     _locale = locale;
@@ -48,5 +74,9 @@ export function withLocale<T>(locale: string, fn: () => T): T {
  * @public
  */
 export function setLocale(locale: string): void {
+  if (localAsyncStore) {
+    localAsyncStore.enterWith(locale);
+    return;
+  }
   _locale = locale;
 }

packages/qwik/src/optimizer/src/plugins/vite.ts

@@ -265,6 +265,7 @@ export function qwikVite(qwikViteOpts: QwikVitePluginOptions = {}): any {
             exclude: [/./],
           },
           rollupOptions: {
+            external: ['node:async_hooks'],
             /**
              * This is a workaround to have predictable chunk hashes between builds. It doesn't seem
              * to impact the build time.

starters/apps/qwikrouter-test/src/routes/locale-concurrent/index.tsx

@@ -0,0 +1,88 @@
+import {
+  component$,
+  Resource,
+  getLocale,
+  withLocale,
+  useSignal,
+  useVisibleTask$,
+} from "@qwik.dev/core";
+import type { RequestHandler } from "@qwik.dev/router";
+import { routeLoader$, server$ } from "@qwik.dev/router";
+
+// Simple in-memory barrier to coordinate two concurrent requests in tests.
+type Barrier = {
+  waiters: Set<string>;
+  promise?: Promise<void>;
+  resolve?: () => void;
+};
+
+const barriers = new Map<string, Barrier>();
+
+function getBarrier(group: string): Barrier {
+  let b = barriers.get(group);
+  if (!b) {
+    b = { waiters: new Set() };
+    barriers.set(group, b);
+  }
+  return b;
+}
+
+function waitForBoth(group: string, id: string) {
+  const barrier = getBarrier(group);
+  if (!barrier.promise) {
+    barrier.promise = new Promise<void>(
+      (resolve) => (barrier.resolve = resolve),
+    );
+  }
+  barrier.waiters.add(id);
+  if (barrier.waiters.size >= 2) {
+    barrier.resolve?.();
+  }
+  return barrier.promise!;
+}
+
+export const onRequest: RequestHandler = ({ url, locale }) => {
+  const qpLocale = url.searchParams.get("locale");
+  if (qpLocale) {
+    locale(qpLocale);
+  }
+};
+
+export const getAsyncLocale = server$((locale: string) => {
+  return withLocale(locale, async () => {
+    await waitForBoth("locale-server", locale);
+    return getLocale();
+  });
+});
+
+export const useBarrier = routeLoader$(({ url }) => {
+  const group = url.searchParams.get("group") || "default";
+  const id = url.searchParams.get("id") || Math.random().toString(36).slice(2);
+  return waitForBoth(group, id).then(() => ({ done: true }));
+});
+
+export default component$(() => {
+  const serverLocale = useSignal("unknown");
+  const barrier = useBarrier();
+  useVisibleTask$(async () => {
+    serverLocale.value = await getAsyncLocale(getLocale());
+  });
+  return (
+    <section>
+      <p>
+        Before barrier locale: <span class="locale-before">{getLocale()}</span>
+      </p>
+      <Resource
+        value={barrier}
+        onResolved={() => (
+          <p>
+            After barrier locale: <span class="locale">{getLocale()}</span>
+          </p>
+        )}
+      />
+      <p>
+        Server locale: <span class="locale-server">{serverLocale.value}</span>
+      </p>
+    </section>
+  );
+});

starters/e2e/qwikrouter/locale-concurrent.e2e.ts

@@ -0,0 +1,35 @@
+import { expect, test } from "@playwright/test";
+
+// This test ensures asyncRequestStore locale isolation across concurrent requests.
+// It triggers two concurrent server renders to the same route with different locales,
+// and uses a server-side barrier so the page reveals the locale only after both renders started.
+
+test.describe("Qwik Router concurrent locale", () => {
+  test("should isolate locale per concurrent request", async ({ browser }) => {
+    const ctx1 = await browser.newContext();
+    const ctx2 = await browser.newContext();
+
+    const page1 = await ctx1.newPage();
+    const page2 = await ctx2.newPage();
+
+    const url1 =
+      "/qwikrouter-test/locale-concurrent?group=g&id=one&locale=en-US";
+    const url2 =
+      "/qwikrouter-test/locale-concurrent?group=g&id=two&locale=fr-FR";
+
+    // Visit both pages concurrently
+    const nav1 = page1.goto(url1);
+    const nav2 = page2.goto(url2);
+    await Promise.all([nav1, nav2]);
+
+    await expect(page1.locator(".locale-before")).toHaveText("en-US");
+    await expect(page2.locator(".locale-before")).toHaveText("fr-FR");
+    await expect(page1.locator(".locale")).toHaveText("en-US");
+    await expect(page2.locator(".locale")).toHaveText("fr-FR");
+    await expect(page1.locator(".locale-server")).toHaveText("en-US");
+    await expect(page2.locator(".locale-server")).toHaveText("fr-FR");
+
+    await ctx1.close();
+    await ctx2.close();
+  });
+});