fix: load locale files that use Nuxt app composables in the app (#4102)

Author: BobbieGoede

docs/content/docs/02.guide/07.lazy-load-translations.md

@@ -75,6 +75,12 @@ About `defineI18nLocale()`{lang="ts"} details, see the [here](/docs/composables/
 This is decided per locale, by reading the locale file at build time: message functions are found through variables, spreads and loader `return`s **within that file**. Ones the file cannot reveal - imported from another module, or built from runtime values - are not detected. Those are reported with a warning in development and while prerendering.
 ::
 
+::callout{icon="i-heroicons-light-bulb"}
+The server runs loader functions outside the Nuxt app, so they can only use APIs that exist in the browser and in Nitro, such as `$fetch()`{lang="ts"} and `useRuntimeConfig()`{lang="ts"}. A locale file calling a Nuxt app composable (`useNuxtApp()`{lang="ts"}, `useState()`{lang="ts"}, `useCookie()`{lang="ts"}, ...) is loaded inside the Nuxt app instead, on both server and client, and is not served from the messages endpoint.
+
+See [where a loader runs](/docs/composables/define-i18n-locale#where-the-loader-runs) for what that costs and what stays undetected.
+::
+
 If the function returns an Object available in nuxt i18n module, you can configure the dynamic locale messages, like the API (including external API) or back-end, via fetch:
 
 ```ts

docs/content/docs/06.composables/11.define-i18n-locale.md

@@ -37,4 +37,22 @@ An example of a loader function using a fetch request to load locale messages:
 export default defineI18nLocale(locale => {
   return $fetch(`https://your-company-product/api/${locale}`)
 })
-```
+```
+
+## Where the loader runs
+
+A loader runs on the server as well as in the browser. In a production build the server runs it outside the Nuxt app - that is what lets its messages be served from the [messages endpoint](/docs/guide/lazy-load-translations) - so it can only use APIs that exist in both places, such as `$fetch()`{lang="ts"} and `useRuntimeConfig()`{lang="ts"}. Nitro-only APIs (the h3 utilities, `useStorage()`{lang="ts"}) are not available in the browser, or in development where loaders always run in the Nuxt app.
+
+Nuxt app composables (`useNuxtApp()`{lang="ts"}, `useState()`{lang="ts"}, `useCookie()`{lang="ts"}, `useRequestHeaders()`{lang="ts"}, ...) are the exception: a locale file calling one keeps its loader inside the Nuxt app instead, and is loaded there on both server and client. That is decided at build time, by reading the calls the locale file makes itself. A composable reached through an imported helper is not visible, and fails when the server loads that locale - call it in the locale file to make it detectable.
+
+```ts [i18n/locales/en.ts]
+export default defineI18nLocale(async locale => {
+  // loaded in the Nuxt app, not through the messages endpoint
+  const { $tenant } = useNuxtApp()
+  return $fetch(`/api/messages/${$tenant.id}/${locale}`)
+})
+```
+
+::callout{icon="i-heroicons-light-bulb"}
+Messages for such a locale are produced per request during SSR and again in the browser, and the locale file ships in the client bundle. A loader that reads server-only resources (a database, an internal service) must not use these composables - keep it loadable by the server.
+::

specs/fixtures/lazy/i18n/lang/app-context-translation.ts

@@ -0,0 +1,7 @@
+export default defineI18nLocale(() => {
+  // reading the config through the Nuxt app, which a nitro-side load has no way to reach (#3940)
+  const nuxt = useNuxtApp()
+  return {
+    runtimeConfigKey: `app-context-only:${nuxt.$config.public.myKey}`
+  }
+})

specs/lazy_load/app_context_locale.spec.ts

@@ -0,0 +1,36 @@
+import { fileURLToPath } from 'node:url'
+import { describe, expect, test } from 'vitest'
+
+import { setup, $fetch } from '../utils'
+
+await setup({
+  rootDir: fileURLToPath(new URL(`../fixtures/lazy`, import.meta.url)),
+  nuxtConfig: {
+    i18n: {
+      locales: [
+        {
+          code: 'ap',
+          language: 'en-AU',
+          name: 'App context',
+          files: ['lazy-locale-en.json', 'app-context-translation.ts']
+        }
+      ]
+    }
+  }
+})
+
+describe('(#3940) a locale file that needs the Nuxt app', () => {
+  test('produces its messages during SSR instead of failing in nitro', async () => {
+    const html = await $fetch('/ap')
+    expect(html).toContain('app-context-only:runtime-config-value')
+  })
+
+  test('is not among the loaders the messages endpoint runs', async () => {
+    // the handler resolves the locale from the route, any `:hash` segment reaches it
+    const messages = await $fetch<Record<string, Record<string, unknown>>>('/_i18n/test/ap/messages.json')
+
+    // the locale's other file is still served from there, the one needing the app is left out
+    expect(messages.ap).toHaveProperty('home', 'Homepage')
+    expect(messages.ap).not.toHaveProperty('runtimeConfigKey')
+  })
+})

src/bundler.ts

@@ -89,7 +89,7 @@ export function getDefineConfig(
   server = false,
   nuxt = useNuxt(),
 ) {
-  const { options, rawOptions, dynamicLocales, unserializableLocales, localeFileMetas, localeHashes } = ctx
+  const { options, rawOptions, dynamicLocales, undeliverableLocales, localeFileMetas, localeHashes } = ctx
   // every cache site is guarded per loader (`cache`) or per locale (`isLocaleCacheable`), so this
   // only decides whether the mechanism exists at all
   const cacheLifetime = options.experimental.cacheLifetime
@@ -118,7 +118,7 @@ export function getDefineConfig(
     __I18N_CACHE_LIFETIME__: JSON.stringify(cacheLifetime),
     __I18N_HTTP_CACHE_DURATION__: JSON.stringify(options.experimental.httpCacheDuration ?? 10),
     __I18N_DYNAMIC_LOCALES__: JSON.stringify(dynamicLocales),
-    __I18N_UNSERIALIZABLE_LOCALES__: JSON.stringify(unserializableLocales),
+    __I18N_UNDELIVERABLE_LOCALES__: JSON.stringify(undeliverableLocales),
     __I18N_STRIP_UNUSED__: JSON.stringify(stripMessagesPayload),
     __I18N_PRELOAD__: JSON.stringify(!!options.experimental.preload),
 

src/context.ts

@@ -40,8 +40,8 @@ export interface ResolvedI18nContext extends I18nNuxtContext {
   localeHashes: Record<string, string>
   /** Locales whose messages can only be produced by running their loaders */
   dynamicLocales: string[]
-  /** Locales the messages endpoint cannot deliver, because JSON would drop message functions */
-  unserializableLocales: string[]
+  /** Locales the messages endpoint has no response for - see `DeliveryConfig.undeliverable` */
+  undeliverableLocales: string[]
   /**
    * Whether the build is deployed without a server. Only accurate once `nitro:init` has run:
    * `nuxi generate` sets `nuxt.options.nitro.static`, a static preset (`github-pages`, ...) does not.
@@ -56,15 +56,16 @@ const isDynamicMeta = (meta: FileMeta) => meta.type !== 'static' && meta.cache =
 export function resolveDeliveryLocales(localeInfo: LocaleInfo[]) {
   return {
     dynamicLocales: localeInfo.filter(x => x.meta.some(isDynamicMeta)).map(x => x.code),
-    unserializableLocales: localeInfo.filter(x => x.meta.some(meta => !meta.serializable)).map(x => x.code),
+    // one list, because nothing downstream cares which of the two reasons applies
+    undeliverableLocales: localeInfo.filter(x => x.meta.some(m => !m.serializable || m.appContext)).map(x => x.code),
   }
 }
 
 /** Shares its rule with the runtime `isPrerenderable` rather than restating it - they must agree */
 export const prerenderableLocales = (ctx: ResolvedI18nContext) =>
   ctx.localeCodes.filter(createPrerenderablePredicate({
     dynamic: ctx.dynamicLocales,
-    unserializable: ctx.unserializableLocales,
+    undeliverable: ctx.undeliverableLocales,
   }))
 
 type LayerWithI18n = { config: NuxtConfigLayer, i18n: Partial<NuxtI18nOptions>, i18nDir: string, i18nDetector?: string }
@@ -118,7 +119,7 @@ export async function resolveContext(ctx: I18nNuxtContext, nuxt: Nuxt): Promise<
     }
   }
 
-  const { dynamicLocales, unserializableLocales } = resolveDeliveryLocales(localeInfo)
+  const { dynamicLocales, undeliverableLocales } = resolveDeliveryLocales(localeInfo)
 
   const resolved = assign(ctx as ResolvedI18nContext, {
     normalizedLocales,
@@ -135,7 +136,7 @@ export async function resolveContext(ctx: I18nNuxtContext, nuxt: Nuxt): Promise<
      */
     localeHashes: computeLocaleHashes(localeInfo, vueI18nConfigPaths),
     dynamicLocales,
-    unserializableLocales,
+    undeliverableLocales,
     staticDeploy: !!nuxt.options.nitro.static,
   })
   // registered before the `nitro:init` hooks that read it - hooks run in registration order

src/env.d.ts

@@ -23,8 +23,8 @@ declare let __I18N_CACHE_LIFETIME__: number
 declare let __I18N_HTTP_CACHE_DURATION__: number
 /** Locales whose messages can only be produced by running their loaders at runtime */
 declare let __I18N_DYNAMIC_LOCALES__: string[]
-/** Locales the messages endpoint cannot deliver, because JSON would drop their message functions */
-declare let __I18N_UNSERIALIZABLE_LOCALES__: string[]
+/** Locales the messages endpoint has no response for - see `DeliveryConfig.undeliverable` */
+declare let __I18N_UNDELIVERABLE_LOCALES__: string[]
 declare let __I18N_STRIP_UNUSED__: boolean
 declare let __I18N_PRELOAD__: boolean
 /** Project has pages and strategy is not `no_prefix` */

src/gen.ts

@@ -31,6 +31,9 @@ type LocaleLoaderData = {
   cache: boolean
 }
 
+/** A loader that resolves to no messages, for the graph a locale file is kept out of */
+export const STUB_LOADER = '() => Promise.resolve({})'
+
 export function generateLoaderOptions(
   ctx: Pick<ResolvedI18nContext, 'options' | 'vueI18nConfigPaths' | 'localeInfo' | 'normalizedLocales' | 'runtimeDir'>,
 ) {
@@ -48,21 +51,25 @@ export function generateLoaderOptions(
         const key = genString(identifier)
         const virtualId = asI18nVirtual(meta.hash)
 
-        // resources with an `assetKey` ship as nitro server assets, read lazily instead of
-        // imported eagerly - the message data stays out of the server bundle (see `setupNitro`)
-        if (meta.assetKey) {
-          importStatements.add(genImport(resolve(ctx.runtimeDir, 'server/utils/assets'), [{ name: 'readI18nAsset' }]))
-        } else {
-          importStatements.add(genImport(virtualId, identifier))
+        // a file reaching for the Nuxt app has nothing to run in nitro, and dragging app-only
+        // modules into that bundle is what breaks its build (#3940)
+        if (!meta.appContext) {
+          // resources with an `assetKey` ship as nitro server assets, read lazily instead of
+          // imported eagerly - the message data stays out of the server bundle (see `setupNitro`)
+          importStatements.add(meta.assetKey
+            ? genImport(resolve(ctx.runtimeDir, 'server/utils/assets'), [{ name: 'readI18nAsset' }])
+            : genImport(virtualId, identifier))
         }
         importMapper.set(meta.path, {
           key,
           virtualId,
           cache: meta.cache ?? true,
           load: genDynamicImport(virtualId, { comment: `webpackChunkName: ${key}` }),
-          loadServer: meta.assetKey
-            ? `() => readI18nAsset(${genString(meta.assetKey)})`
-            : `() => Promise.resolve(${identifier})`,
+          loadServer: meta.appContext
+            ? STUB_LOADER
+            : meta.assetKey
+              ? `() => readI18nAsset(${genString(meta.assetKey)})`
+              : `() => Promise.resolve(${identifier})`,
         })
       }
       localeLoaders[locale.code]!.push(importMapper.get(meta.path)!)

src/runtime/context.ts

@@ -96,7 +96,7 @@ type MessageStore = Pick<Composer, 'getLocaleMessage' | 'setLocaleMessage' | 'me
 
 export const isPrerenderable = createPrerenderablePredicate({
   dynamic: __I18N_DYNAMIC_LOCALES__,
-  unserializable: __I18N_UNSERIALIZABLE_LOCALES__,
+  undeliverable: __I18N_UNDELIVERABLE_LOCALES__,
 })
 
 /**
@@ -175,7 +175,7 @@ export function createNuxtI18nContext(nuxt: NuxtApp, vueI18n: I18n, defaultLocal
     ssg: __IS_SSG__,
     prerender: !!import.meta.prerender,
     dynamic: __I18N_DYNAMIC_LOCALES__,
-    unserializable: __I18N_UNSERIALIZABLE_LOCALES__,
+    undeliverable: __I18N_UNDELIVERABLE_LOCALES__,
   })
 
   // only prerendered responses reach the CDN - a dynamic locale in a hybrid build still fetches the

src/runtime/plugins/preload.ts

@@ -32,7 +32,7 @@ export default defineNuxtPlugin({
         for (const k in msg) {
           // the client loads these from their own chunk and discards the payload copy, which
           // `devalue` could not carry anyway - one message function fails the whole payload
-          serverI18n.messages[k] = __I18N_UNSERIALIZABLE_LOCALES__.includes(k) ? {} : msg[k]!
+          serverI18n.messages[k] = __I18N_UNDELIVERABLE_LOCALES__.includes(k) ? {} : msg[k]!
         }
       }
     }