Public API for building and selecting client variants

[samuelstroschein]

This feature request was drafted by Codex (GPT-5.6) and reviewed by @samuelstroschein.

Problem

Plugins sometimes need multiple specialized versions of a TanStack Start client build.

Paraglide JS's experimentalPerLocaleBuild, for example, builds one client graph per locale. Each graph receives a compile-time locale value, allowing Vite/Rolldown to tree-shake translations for every other locale.

The Vite-native implementation is available in opral/paraglide-js#728. It generates independent locale environments without rewriting emitted chunks.

TanStack Start is already close because it uses Vite environments and owns builder.buildApp. However, Start currently creates one client environment, captures one client build, serializes one Start manifest, and caches one production base manifest. Paraglide cannot safely compose with that without depending on private build and manifest internals.

Proposed solution

Register client variants

Expose a public integration API that lets plugins request variants of Start's normal client environment. The names below are illustrative:

registerClientVariants({
  namespace: 'paraglide',
  variants: [
    { id: 'en', environment: { define: { STATIC_LOCALE: '"en"' } } },
    { id: 'de', environment: { define: { STATIC_LOCALE: '"de"' } } }
  ]
});

Start should clone its normal client inputs, route splitting, compiler transforms, and import protection for each variant. Start would retain ownership of output directories and manifests; plugins would never inspect or rewrite emitted chunks.

Build a manifest for each variant

Start's build orchestration would:

1. Build every registered client variant.
2. Capture each native Vite/Rolldown graph.
3. Generate one Start manifest per variant.
4. Build the server once with the complete manifest map.

const manifests = {
  'paraglide:en': englishManifest,
  'paraglide:de': germanManifest
};

Select a variant per request

Add a selector to createStartHandler, or an equivalent request option:

const fetch = createStartHandler({
  handler: defaultStreamHandler,
  clientVariant: ({ request }) =>
    `paraglide:${getLocale(request)}`
});

The selected manifest should control <Scripts />, route chunks, CSS and inline CSS, module preloads, early hints, and asset URL transforms. Production manifest caches must include the variant ID.

The same selection should be honored while prerendering, allowing /en/about and /de/about to reference different client graphs.

Bundle-size impact

Without per-locale builds:

bundle = application + runtime + English + German + French + …

With per-locale builds:

English graph = application + runtime + English
German graph  = application + runtime + German

For similarly sized catalogs, the translation portion approaches 1 / numberOfLocales of the unsplit translation payload. The tradeoff is increased build time and deployment storage because shared application code may be emitted once per locale. The optimization targets bytes transferred to each visitor.

The prototype verifies that other locales' translations are absent from executable JavaScript and source maps.

Expected behavior

• Every variant is a native Vite/Rolldown build.
• Route splitting, dynamic imports, CSS, inline CSS, source maps, minification, custom bases, and asset transforms continue to work.
• Existing applications remain unchanged.
• Unknown variants produce actionable errors.
• Changing variants may require a full-document navigation.
• A single SPA fallback can initially remain unsupported with a clear error.

This API could also support white-label builds, regional configuration, and build-time product editions.

[samuelstroschein]

This would resolve the longstanding opral/paraglide-js#88 issue. Some benchmarking

With L similarly sized locales, the approximate reduction in client-side translation code is:

2 locales: ~50%
4 locales: ~75%
7 locales: ~86%
10 locales: ~90%

[schiller-manuel]

interesting proposal! is there any prior art in any other framework?

how does SSR work with multiple locales? does the server build have all translations available all the time?