How to async-load locale and inject it into <html lang>? #2166

YanAnghelp · 2026-06-25T14:20:52Z

YanAnghelp
Jun 25, 2026

Context

I need the lang attribute on <html> to reflect the authenticated user's locale preference (stored in Redis/DB), resolved per-request during SSR. This is extremely important to me.

What I've considered

1. Middleware

createMiddleware runs for every request — including API routes and potentially static assets depending on the deployment target. Running a Redis/DB lookup unconditionally on non-page requests is not acceptable.

Path-based filtering (skip /api/*, skip paths with file extensions) works but relies on conventions that feel fragile rather than architecturally guaranteed.

2. Cookie (current approach)

Reading a locale cookie synchronously in the document function works and has zero overhead. The limitation: cookies can be stale across devices. If the user changes their locale on Device A, Device B's cookie won't update until the next login or an explicit refresh.

For <html lang> this may be acceptable — but I'd like to understand if there's a better option.

3. `createAsync` inside the `document` function

The document prop in <StartServer> is a SolidJS component rendered during SSR, so it should be able to use createAsync / cache:

export default createHandler(() => (
  <StartServer
    document={({ assets, children, scripts }) => {
      const lang = createAsync(() => getUserLocale())
      return <html lang={lang() ?? 'en'}>...</html>
    }}
  />
))

Questions:

Does createAsync inside document suspend correctly and resolve before the HTML stream begins?
The element is the outermost node — is wrapping it in safe, or does it break streaming semantics?

What I'm looking for

Is there an officially supported pattern for resolving async server data in entry-server.tsx's document shell, with the guarantee that it only runs for HTML page renders (not API routes, not static assets)?

Or is the intended pattern to pre-populate event.locals from the route load function and read it synchronously in document?

Answered by agrovr

Jul 15, 2026

You can resolve this before rendering without putting createAsync inside the document shell. createHandler accepts an async options callback as its second argument. In the current server implementation, SolidStart handles server functions and API routes first, then awaits that callback, and only afterward calls renderToStream/renderToString.

That gives you a page-render-only prepass:

import { createHandler, StartServer } from "@solidjs/start/server";

export default createHandler(
  (event) => (
    <StartServer
      document={({ assets, children, scripts }) => (
        <html lang={event.locals.locale ?? "en"}>
          <head>
            <meta charset="utf-8" />
            <meta name="…

View full answer

agrovr · 2026-07-15T19:34:57Z

agrovr
Jul 15, 2026

You can resolve this before rendering without putting createAsync inside the document shell. createHandler accepts an async options callback as its second argument. In the current server implementation, SolidStart handles server functions and API routes first, then awaits that callback, and only afterward calls renderToStream/renderToString.

That gives you a page-render-only prepass:

import { createHandler, StartServer } from "@solidjs/start/server";

export default createHandler(
  (event) => (
    <StartServer
      document={({ assets, children, scripts }) => (
        <html lang={event.locals.locale ?? "en"}>
          <head>
            <meta charset="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1" />
            {assets}
          </head>
          <body>
            <div id="app">{children}</div>
            {scripts}
          </body>
        </html>
      )}
    />
  ),
  async (event) => {
    event.locals.locale = await getUserLocale(event);
    return { mode: "stream" };
  },
);

Declare the local once in your app types:

declare global {
  namespace App {
    interface RequestEventLocals {
      locale?: string;
    }
  }
}

This keeps streaming enabled, but the locale lookup completes before the outer HTML shell is created. Within SolidStart's handler, API/server-function responses return before this callback. Static assets are normally served by the adapter/server before the application handler as well.

I would not suspend the outer <html> with createAsync for this. The document is the stream shell itself, so it is cleaner to finish request metadata before rendering and then read it synchronously. A cookie can still be used as a fallback when the authenticated lookup returns no preference.

Relevant implementation order:
https://github.com/solidjs/solid-start/blob/main/packages/start/src/server/handler.ts

PageEvent/locals types:
https://github.com/solidjs/solid-start/blob/main/packages/start/src/server/types.ts

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

How to async-load locale and inject it into <html lang>? #2166

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

How to async-load locale and inject it into <html lang>? #2166

Uh oh!

Uh oh!

YanAnghelp Jun 25, 2026

Context

What I've considered

1. Middleware

2. Cookie (current approach)

3. createAsync inside the document function

Replies: 1 comment

Uh oh!

agrovr Jul 15, 2026

YanAnghelp
Jun 25, 2026

3. `createAsync` inside the `document` function

agrovr
Jul 15, 2026