@bleedingdev/modern-js-plugin-tanstack 3.9.0-ultramodern.2 → 3.9.0-ultramodern.20

package/src/cli/artifacts.ts

@@ -5,6 +5,12 @@ import type { AppToolsContext } from '@modern-js/app-tools';
 import type { NestedRouteForCli, PageRoute } from '@modern-js/types';
 import { fs } from '@modern-js/utils';
 
+import {
+  findRouteMetaFiles,
+  ROUTE_METADATA_MANIFEST_FILE_NAME,
+  ROUTE_METADATA_MANIFEST_HEADER,
+  renderRouteMetadataManifest,
+} from './routeMetadata';
 import {
   collectCanonicalRoutesForEntry,
   generateTanstackRouterTypesSourceForEntry,
@@ -193,16 +199,52 @@ export async function writeTanstackRouterTypesForEntries(opts: {
 }
 
 /**
- * Headless regeneration of `router.gen.ts` / `register.gen.d.ts` for a generated
- * app, without running a full dev/build. Drives the app-tools analyze `onPrepare`
- * (which fires `generateEntryCode`) and returns before any bundling — the app's
- * own registered plugin-tanstack writes the artifacts via its `generateEntryCode`
- * subscriber. Reuses the exact hook dev/build use, so there is no scanning drift.
+ * Writes `src/routes/ultramodern-route-metadata.ts` from the `route.meta.ts`
+ * files below `src/routes`. Reads only the file system, never the app config.
+ */
+export async function writeRouteMetadataManifest(opts: {
+  appDirectory: string;
+}): Promise<void> {
+  const routesDirectory = path.join(opts.appDirectory, 'src', 'routes');
+  const manifestPath = path.join(
+    routesDirectory,
+    ROUTE_METADATA_MANIFEST_FILE_NAME,
+  );
+  const manifest = renderRouteMetadataManifest(
+    await findRouteMetaFiles(routesDirectory),
+  );
+  if (manifest !== null) {
+    await writeFileIfChanged(manifestPath, manifest);
+    return;
+  }
+  const previous = (await fs.pathExists(manifestPath))
+    ? await fs.readFile(manifestPath, 'utf-8')
+    : null;
+  // No valid manifest exists without routes (its namespace comes from them),
+  // and the app config imports it, so the app cannot load in this state.
+  if (previous?.startsWith(`${ROUTE_METADATA_MANIFEST_HEADER}\n`)) {
+    throw new Error(
+      `[plugin-tanstack] ${manifestPath} is generated from route.meta.ts files, but none remain below ${routesDirectory}. ` +
+        'Restore at least one route.meta.ts that exports routeMeta, or delete the manifest together with its imports.',
+    );
+  }
+}
+
+/**
+ * Headless regeneration of the route metadata manifest and of `router.gen.ts` /
+ * `register.gen.d.ts` for a generated app, without running a full dev/build.
+ * Drives the app-tools analyze `onPrepare` (which fires `generateEntryCode`)
+ * and returns before any bundling — the app's own registered plugin-tanstack
+ * writes the router artifacts via its `generateEntryCode` subscriber. Reuses
+ * the exact hook dev/build use, so there is no scanning drift.
  */
 export async function generateTanstackRouteArtifacts(opts: {
   appDirectory: string;
   version?: string;
 }): Promise<void> {
+  // The app config imports the manifest. Writing it first means a manifest
+  // that still imports a deleted route.meta.ts cannot fail the config load.
+  await writeRouteMetadataManifest(opts);
   const [{ createRunOptions }, { cli }, utils] = await Promise.all([
     import('@modern-js/app-tools/cli/run'),
     import('@modern-js/plugin/cli'),
@@ -251,5 +293,10 @@ export async function generateTanstackRouteArtifacts(opts: {
     internalPlugins: (utils as { INTERNAL_RUNTIME_PLUGINS: unknown })
       .INTERNAL_RUNTIME_PLUGINS as never,
   });
-  await cli.init({ ...runOptions, command: 'build' });
+  const { appContext } = await cli.init({ ...runOptions, command: 'build' });
+  // Preparation owns the artifact writes; there is no dev server or bundler
+  // phase after it. Release plugin resources before the headless caller exits.
+  // Failed initialization propagates unchanged: it has not returned a context
+  // whose lifecycle this caller can close.
+  await appContext.hooks.onBeforeExit.call();
 }

package/src/cli/index.ts

@@ -3,7 +3,6 @@ import path from 'node:path';
 import type {
   AppNormalizedConfig,
   AppTools,
-  AppToolsContext,
   CliPlugin,
 } from '@modern-js/app-tools';
 import type { CLIPluginAPI } from '@modern-js/plugin';
@@ -15,7 +14,6 @@ import type {
 } from '@modern-js/types';
 import {
   filterRoutesForServer,
-  fs,
   NESTED_ROUTE_SPEC_FILE,
 } from '@modern-js/utils';
 import { writeTanstackRouterTypesForEntries } from './artifacts';
@@ -26,6 +24,7 @@ import {
 
 export {
   generateTanstackRouteArtifacts,
+  writeRouteMetadataManifest,
   writeTanstackRegisterFile,
   writeTanstackRouterTypesForEntries,
 } from './artifacts';
@@ -132,6 +131,16 @@ export function tanstackRouterPlugin(
     name: '@modern-js/plugin-tanstack',
     required: ['@modern-js/runtime'],
     setup: api => {
+      const { srcDirectory, serverCompileExcludedFiles = [] } =
+        api.getAppContext();
+      api.updateAppContext({
+        serverCompileExcludedFiles: [
+          ...new Set([
+            ...serverCompileExcludedFiles,
+            path.join(srcDirectory, generatedDirName, 'register.gen.d.ts'),
+          ]),
+        ],
+      });
       const nestedRoutesForServer: Record<string, unknown> = {};
 
       const isTanstackEntrypoint = (entrypoint: Entrypoint) => {

package/src/cli/routeMetadata.ts

@@ -0,0 +1,121 @@
+// @effect-diagnostics asyncFunction:off nodeBuiltinImport:off
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+
+export const ROUTE_META_FILE_NAME = 'route.meta.ts';
+export const ROUTE_METADATA_MANIFEST_FILE_NAME =
+  'ultramodern-route-metadata.ts';
+
+export const ROUTE_METADATA_MANIFEST_HEADER = `// @generated by @modern-js/plugin-tanstack from ${ROUTE_META_FILE_NAME} files. Run routes-generate; do not edit.`;
+
+// The manifest is emitted formatted (oxfmt/Prettier style: print width 120,
+// single quotes, trailing commas) and is generated output, so formatters
+// ignore it like router.gen.ts; no formatter pass is needed to keep it stable.
+const PRINT_WIDTH = 120;
+
+const MANIFEST_BODY = `export const ultramodernLocalisedUrls = Object.fromEntries(
+  ultramodernRouteMetadata
+    .filter((route) => route.canonicalPath !== '/')
+    .map((route) => [route.canonicalPath, route.localisedPaths]),
+);
+export const ultramodernPublicRoutes = ultramodernRouteMetadata
+  .filter((route) => route.public && route.indexable)
+  .map((route) => ({
+    canonicalPath: route.canonicalPath,
+    descriptionKey: route.descriptionKey,
+    id: route.id,
+    localisedPaths: route.localisedPaths,
+    namespace: route.namespace,
+    ownerAppId: route.ownerAppId,
+    titleKey: route.titleKey,
+    ...('jsonLd' in route ? { jsonLd: route.jsonLd } : {}),
+  }));
+export const ultramodernRouteConfig = {
+  authoring: 'colocated-route-meta',
+  generatedManifest: true,
+  localisedUrls: ultramodernLocalisedUrls,
+  namespace: ultramodernRouteNamespace,
+  publicRoutes: ultramodernPublicRoutes,
+  routes: ultramodernRouteMetadata,
+  source: 'route-owned',
+} as const;
+`;
+
+const compareCodeUnits = (left: string, right: string) =>
+  left < right ? -1 : left > right ? 1 : 0;
+
+const quoteSpecifier = (specifier: string) =>
+  specifier.includes("'") ? JSON.stringify(specifier) : `'${specifier}'`;
+
+/**
+ * Renders the route metadata manifest for the `route.meta.ts` files of one
+ * routes directory. Each path is relative to that directory (either separator).
+ * Every `route.meta.ts` must export `routeMeta`; the manifest imports it
+ * statically, so the metadata is never evaluated while generating. Returns
+ * `null` when there are no route metadata files. Output depends only on the
+ * set of paths, never on their order or on the file system.
+ */
+export function renderRouteMetadataManifest(
+  routeMetaFiles: readonly string[],
+): string | null {
+  const specifiers = routeMetaFiles
+    .map(file => `./${file.replaceAll('\\', '/').replace(/\.ts$/u, '')}`)
+    .sort(compareCodeUnits);
+  if (specifiers.length === 0) {
+    return null;
+  }
+  const bindings = specifiers.map((_, index) => `route${index}`);
+  const imports = specifiers.map(
+    (specifier, index) =>
+      `import { routeMeta as ${bindings[index]} } from ${quoteSpecifier(specifier)};`,
+  );
+  const inlineRoutes = `export const ultramodernRouteMetadata = [${bindings.join(', ')}] as const;`;
+  const routes =
+    inlineRoutes.length <= PRINT_WIDTH
+      ? inlineRoutes
+      : `export const ultramodernRouteMetadata = [\n${bindings
+          .map(binding => `  ${binding},\n`)
+          .join('')}] as const;`;
+
+  return `${ROUTE_METADATA_MANIFEST_HEADER}
+${imports.join('\n')}
+
+export const ultramodernRouteNamespace = route0.namespace;
+${routes}
+${MANIFEST_BODY}`;
+}
+
+/**
+ * Lists the `route.meta.ts` files below `routesDirectory`, relative to it.
+ * Symbolic links are not followed: linked metadata belongs to the tree it
+ * lives in. A missing directory has no route metadata.
+ */
+export async function findRouteMetaFiles(
+  routesDirectory: string,
+): Promise<string[]> {
+  const files: string[] = [];
+  const visit = async (relativeDirectory: string): Promise<void> => {
+    const entries = await readdir(
+      path.join(routesDirectory, relativeDirectory),
+      { withFileTypes: true },
+    );
+    for (const entry of entries) {
+      const relativePath = path.join(relativeDirectory, entry.name);
+      if (entry.isDirectory()) {
+        await visit(relativePath);
+      } else if (entry.isFile() && entry.name === ROUTE_META_FILE_NAME) {
+        files.push(relativePath);
+      }
+    }
+  };
+  try {
+    await visit('');
+  } catch (error) {
+    const { code, path: missingPath } = error as NodeJS.ErrnoException;
+    if (code === 'ENOENT' && missingPath === routesDirectory) {
+      return [];
+    }
+    throw error;
+  }
+  return files;
+}

package/src/cli/tanstackTypes/canonicalRoutes.ts

@@ -1,7 +1,10 @@
 // @effect-diagnostics asyncFunction:off strictBooleanExpressions:off
 
 import type { NestedRouteForCli, PageRoute } from '@modern-js/types';
-import { MAIN_ENTRY_NAME } from '@modern-js/utils';
+import {
+  describeRouteTree,
+  type RouteDescriptor,
+} from '../../shared/routeDescriptor';
 
 import { toTanstackPath } from './shared';
 
@@ -16,6 +19,7 @@ const LOCALE_PARAM_SEGMENTS = new Set([
 
 type CanonicalAwareRoute = (NestedRouteForCli | PageRoute) & {
   modernCanonicalPath?: string;
+  modernLocalisedRoute?: { canonicalPath: string };
   index?: boolean;
   isRoot?: boolean;
   children?: CanonicalAwareRoute[];
@@ -101,12 +105,18 @@ export function collectCanonicalRoutesForEntry(
     }
   };
 
-  const visit = (route: CanonicalAwareRoute, parentPath: string) => {
+  const visit = (
+    descriptor: RouteDescriptor<CanonicalAwareRoute>,
+    parentPath: string,
+  ) => {
+    const { source: route, children } = descriptor;
     let currentPath = parentPath;
 
-    if (typeof route.modernCanonicalPath === 'string') {
+    const canonicalPath =
+      route.modernLocalisedRoute?.canonicalPath ?? route.modernCanonicalPath;
+    if (typeof canonicalPath === 'string') {
       hasI18nSurface = true;
-      currentPath = normalizeJoined(route.modernCanonicalPath);
+      currentPath = canonicalPath ? normalizeJoined(canonicalPath) : '';
     } else if (typeof route.path === 'string' && route.path.length > 0) {
       const segments = route.path
         .replace(/\[(.+?)\]/g, ':$1')
@@ -125,7 +135,6 @@ export function collectCanonicalRoutesForEntry(
         : parentPath;
     }
 
-    const children = route.children;
     if (children && children.length > 0) {
       for (const child of children) {
         visit(child, currentPath);
@@ -137,13 +146,9 @@ export function collectCanonicalRoutesForEntry(
     record(currentPath || '/');
   };
 
-  const rootModern = routes.find(
-    route => (route as CanonicalAwareRoute).isRoot,
-  ) as CanonicalAwareRoute | undefined;
-  const topLevel = rootModern ? (rootModern.children ?? []) : routes;
-
-  for (const route of topLevel) {
-    visit(route as CanonicalAwareRoute, '');
+  for (const route of describeRouteTree(routes as CanonicalAwareRoute[])
+    .children) {
+    visit(route, '');
   }
 
   if (!hasI18nSurface || canonicalParams.size === 0) {

package/src/cli/tanstackTypes/shared.ts

@@ -71,20 +71,6 @@ export function pickRouteSearchContractModules(
   };
 }
 
-export function isPathlessLayout(route: NestedRouteForCli | PageRoute) {
-  const extras = route as RouteExtras;
-  return (
-    extras.type === 'nested' &&
-    typeof extras.index !== 'boolean' &&
-    typeof extras.path === 'undefined'
-  );
-}
-
-export function isIndexRoute(route: NestedRouteForCli | PageRoute) {
-  const extras = route as RouteExtras;
-  return extras.type === 'nested' && Boolean(extras.index);
-}
-
 export function createRouteStaticDataSnippet(opts: {
   modernRouteId?: string;
   loaderName?: string | null;

package/src/cli/tanstackTypes/source.ts

@@ -1,24 +1,22 @@
 // @effect-diagnostics asyncFunction:off strictBooleanExpressions:off
 
-import type {
-  AppNormalizedConfig,
-  AppTools,
-  AppToolsContext,
-} from '@modern-js/app-tools';
+import type { AppToolsContext } from '@modern-js/app-tools';
 import { makeLegalIdentifier } from '@modern-js/runtime/cli';
 import type { NestedRouteForCli, PageRoute } from '@modern-js/types';
 import { upath as path } from '@modern-js/utils';
 
+import {
+  describeRouteTree,
+  type RouteDescriptor,
+} from '../../shared/routeDescriptor';
+
 import {
   createRouteStaticDataSnippet,
-  isIndexRoute,
-  isPathlessLayout,
   normalizeRelativeImport,
   pickModernLoaderModule,
   pickRouteSearchContractModules,
   quote,
   resolveFileNoExt,
-  toTanstackPath,
 } from './shared';
 
 type RouteForCli = NestedRouteForCli | PageRoute;
@@ -53,13 +51,7 @@ export async function generateTanstackRouterTypesSourceForEntry(opts: {
     entryName,
   );
 
-  const rootModern = routes.find(r => {
-    const extras = r as RouteExtras;
-    return r && extras.type === 'nested' && extras.isRoot;
-  }) as NestedRouteForCli | undefined;
-
-  const rootExtras = rootModern as RouteExtras | undefined;
-  const topLevel = rootModern ? rootExtras?.children || [] : routes;
+  const { root: rootModern, children: topLevel } = describeRouteTree(routes);
 
   const imports: string[] = [];
   const statements: string[] = [];
@@ -90,15 +82,11 @@ export async function generateTanstackRouterTypesSourceForEntry(opts: {
         // value carries the internal `@_modern_js_src` alias, which the app's
         // tsconfig does not map — the generated file must use relative
         // imports.
-        const resolvedNoExt = await resolveRouteModuleNoExt(componentPath);
-        if (!resolvedNoExt) {
+        const relImport = await resolveRouteImport(componentPath);
+        if (!relImport) {
           return null;
         }
 
-        const relImport = normalizeRelativeImport(
-          path.relative(outDir, resolvedNoExt),
-        );
-
         const componentName = `component_${componentIndex++}`;
         imports.push(`import ${componentName} from ${quote(relImport)};`);
         return componentName;
@@ -109,7 +97,7 @@ export async function generateTanstackRouterTypesSourceForEntry(opts: {
     return pendingImportName;
   };
 
-  const resolveRouteModuleNoExt = async (aliasedNoExtPath: string) => {
+  const resolveRouteImport = async (aliasedNoExtPath: string) => {
     const prefix = `${appContext.internalSrcAlias}/`;
     let absNoExt: string;
     if (aliasedNoExtPath.startsWith(prefix)) {
@@ -122,7 +110,10 @@ export async function generateTanstackRouterTypesSourceForEntry(opts: {
       absNoExt = path.join(appContext.srcDirectory, aliasedNoExtPath);
     }
 
-    return resolveFileNoExt(absNoExt);
+    const resolvedNoExt = await resolveFileNoExt(absNoExt);
+    return resolvedNoExt
+      ? normalizeRelativeImport(path.relative(outDir, resolvedNoExt))
+      : null;
   };
 
   const getImportNamesForLoader = async (
@@ -141,15 +132,11 @@ export async function generateTanstackRouterTypesSourceForEntry(opts: {
       };
     }
 
-    const resolvedNoExt = await resolveRouteModuleNoExt(aliasedNoExtPath);
-    if (!resolvedNoExt) {
+    const relImport = await resolveRouteImport(aliasedNoExtPath);
+    if (!relImport) {
       return null;
     }
 
-    const relImport = normalizeRelativeImport(
-      path.relative(outDir, resolvedNoExt),
-    );
-
     const importName = `loader_${loaderIndex++}`;
     const actionName = hasAction
       ? importName.replace(/^loader_/, 'action_')
@@ -180,14 +167,10 @@ export async function generateTanstackRouterTypesSourceForEntry(opts: {
       return existing;
     }
 
-    const resolvedNoExt = await resolveRouteModuleNoExt(aliasedNoExtPath);
-    if (!resolvedNoExt) {
+    const relImport = await resolveRouteImport(aliasedNoExtPath);
+    if (!relImport) {
       return null;
     }
-
-    const relImport = normalizeRelativeImport(
-      path.relative(outDir, resolvedNoExt),
-    );
     const importName =
       exportName === 'validateSearch'
         ? `validateSearch_${validateSearchIndex++}`
@@ -215,15 +198,8 @@ export async function generateTanstackRouterTypesSourceForEntry(opts: {
     return reserveRouteVarName(`route_${base}`);
   };
 
-  const buildRoute = async (opts: {
-    parentVar: string;
-    route: NestedRouteForCli | PageRoute;
-  }): Promise<string> => {
-    const { parentVar, route } = opts;
-
-    const varName = createRouteVarName(route);
+  const createRouteOptions = async (route: RouteForCli, hasSplat: boolean) => {
     const routeExtras = route as RouteExtras;
-
     const loaderInfo = pickModernLoaderModule(route);
     const routeAction = routeExtras.action;
     const loaderImports = loaderInfo
@@ -249,10 +225,7 @@ export async function generateTanstackRouterTypesSourceForEntry(opts: {
         )
       : null;
 
-    const rawPath = routeExtras.path;
-    const hasSplat = typeof rawPath === 'string' && rawPath.includes('*');
-
-    const routeOpts: string[] = [`getParentRoute: () => ${parentVar},`];
+    const routeOpts: string[] = [];
 
     const componentName = await getImportNameForComponent(
       routeExtras._component,
@@ -261,14 +234,6 @@ export async function generateTanstackRouterTypesSourceForEntry(opts: {
       routeOpts.push(`component: ${componentName},`);
     }
 
-    if (isPathlessLayout(route)) {
-      const id = routeExtras.id;
-      routeOpts.push(`id: ${quote(id || 'pathless')},`);
-    } else {
-      const p = isIndexRoute(route) ? '/' : toTanstackPath(rawPath || '');
-      routeOpts.push(`path: ${quote(p)},`);
-    }
-
     if (loaderName) {
       routeOpts.push(
         `loader: modernLoaderToTanstack({ hasSplat: ${hasSplat} }, ${loaderName}),`,
@@ -290,7 +255,22 @@ export async function generateTanstackRouterTypesSourceForEntry(opts: {
       routeOpts.push(staticDataSnippet);
     }
 
-    const children = routeExtras.children;
+    return routeOpts;
+  };
+
+  const buildRoute = async (
+    descriptor: RouteDescriptor<RouteForCli>,
+    parentVar: string,
+  ): Promise<string> => {
+    const { source: route, location, hasSplat, children } = descriptor;
+    const varName = createRouteVarName(route);
+    const routeOpts = [
+      `getParentRoute: () => ${parentVar},`,
+      ...Object.entries(location).map(
+        ([key, value]) => `${key}: ${quote(value)},`,
+      ),
+      ...(await createRouteOptions(route, hasSplat)),
+    ];
     const hasChildren = Boolean(children && children.length > 0);
     const routeCtorVarName = hasChildren
       ? reserveRouteVarName(`${varName}__base`)
@@ -303,9 +283,7 @@ export async function generateTanstackRouterTypesSourceForEntry(opts: {
     if (children && children.length > 0) {
       const childVars: string[] = [];
       for (const child of children) {
-        childVars.push(
-          await buildRoute({ parentVar: routeCtorVarName, route: child }),
-        );
+        childVars.push(await buildRoute(child, routeCtorVarName));
       }
       statements.push(
         `const ${varName} = ${routeCtorVarName}.addChildren([${childVars.join(', ')}]);`,
@@ -315,60 +293,14 @@ export async function generateTanstackRouterTypesSourceForEntry(opts: {
     return varName;
   };
 
-  const rootLoaderInfo = rootModern ? pickModernLoaderModule(rootModern) : null;
-  const rootAction = rootExtras?.action;
-  const rootLoaderImports = rootLoaderInfo?.loaderPath
-    ? await getImportNamesForLoader(
-        rootLoaderInfo.loaderPath,
-        rootLoaderInfo.inline,
-        Boolean(
-          rootLoaderInfo.inline && rootAction === rootLoaderInfo.loaderPath,
-        ),
-      )
-    : null;
-  const rootLoaderName = rootLoaderImports?.loaderName || null;
-  const rootActionName = rootLoaderImports?.actionName || null;
-  const rootSearchContractInfo = rootModern
-    ? pickRouteSearchContractModules(rootModern)
-    : null;
-  const rootValidateSearchName = rootSearchContractInfo?.validateSearchPath
-    ? await getImportNameForSearchContract(
-        rootSearchContractInfo.validateSearchPath,
-        'validateSearch',
-      )
-    : null;
-  const rootLoaderDepsName = rootSearchContractInfo?.loaderDepsPath
-    ? await getImportNameForSearchContract(
-        rootSearchContractInfo.loaderDepsPath,
-        'loaderDeps',
-      )
-    : null;
-
   const topLevelVars: string[] = [];
   for (const route of topLevel) {
-    topLevelVars.push(await buildRoute({ parentVar: 'rootRoute', route }));
+    topLevelVars.push(await buildRoute(route, 'rootRoute'));
   }
 
-  const rootOpts: string[] = [];
-
-  const rootComponentName = await getImportNameForComponent(
-    rootExtras?._component,
-  );
-  if (rootComponentName) {
-    rootOpts.push(`component: ${rootComponentName},`);
-  }
-
-  if (rootLoaderName) {
-    rootOpts.push(
-      `loader: modernLoaderToTanstack({ hasSplat: false }, ${rootLoaderName}),`,
-    );
-  }
-  if (rootValidateSearchName) {
-    rootOpts.push(`validateSearch: ${rootValidateSearchName},`);
-  }
-  if (rootLoaderDepsName) {
-    rootOpts.push(`loaderDeps: ${rootLoaderDepsName},`);
-  }
+  const rootOpts = rootModern
+    ? await createRouteOptions(rootModern, false)
+    : [];
 
   const routerGenTs = `// This file is auto-generated by Modern.js. Do not edit manually.
 
@@ -386,13 +318,7 @@ ${imports.join('\n')}
 
 export const rootRoute = createRootRouteWithContext<ModernRouterContext>()({
   ${rootOpts.join('\n  ')}
-  ${
-    createRouteStaticDataSnippet({
-      modernRouteId: rootExtras?.id,
-      loaderName: rootLoaderName,
-      actionName: rootActionName,
-    }) || ''
-  }
+
 });
 
 ${statements.join('\n\n')}

package/src/runtime/basepathRewrite.ts

@@ -1,4 +1,8 @@
 // @effect-diagnostics strictBooleanExpressions:off
+import { createLocalisedRouteRewrite } from '@modern-js/i18n-runtime-extensions';
+import type { RouteObject } from '@modern-js/runtime-utils/router';
+import { composeRewrites } from '@tanstack/react-router';
+
 function normalizeBasepath(basepath: string): string {
   if (!basepath) {
     return '/';
@@ -15,10 +19,12 @@ function normalizeBasepath(basepath: string): string {
 export function createModernBasepathRewrite(
   basepath: string,
   caseSensitive = false,
+  routes: RouteObject[] = [],
 ) {
+  const localisedRewrite = createLocalisedRouteRewrite(routes);
   const normalizedBasepath = normalizeBasepath(basepath);
   if (normalizedBasepath === '/') {
-    return undefined;
+    return localisedRewrite;
   }
 
   const normalizedBasepathWithSlash = `${normalizedBasepath}/`;
@@ -29,7 +35,7 @@ export function createModernBasepathRewrite(
     ? normalizedBasepathWithSlash
     : normalizedBasepathWithSlash.toLowerCase();
 
-  return {
+  const basepathRewrite = {
     input: ({ url }: { url: URL }) => {
       const pathname = caseSensitive
         ? url.pathname
@@ -57,4 +63,7 @@ export function createModernBasepathRewrite(
       return url;
     },
   };
+  return localisedRewrite
+    ? composeRewrites([basepathRewrite, localisedRewrite])
+    : basepathRewrite;
 }

package/src/runtime/lifecycle.ts

@@ -1,16 +1,26 @@
 /**
- * The router runtime state helpers are owned by @modern-js/runtime (the same
+ * The router runtime state helpers are owned by @modern-js/runtime-extensions (the same
  * implementation backs the built-in react-router provider and the SSR
  * pipeline). This module only re-exports them so every router provider
  * writes to the exact same runtime-context extension slot.
  */
+
+import type { RouterLifecycleContext as NativeRouterLifecycleContext } from '@modern-js/runtime/context';
+import type {
+  InternalRouterServerSnapshot,
+  RouterRouteMatchSnapshot,
+} from '@modern-js/runtime-extensions/router-state';
+
+export type RouterLifecycleContext = NativeRouterLifecycleContext & {
+  matches?: RouterRouteMatchSnapshot[];
+  cleanup?: () => void | Promise<void>;
+  serverSnapshot?: InternalRouterServerSnapshot;
+};
 export {
   applyRouterRuntimeState,
   applyRouterServerPrepareResult,
-  createRouterRuntimeState,
   createRouterServerSnapshot,
   getRouterRuntimeState,
   getRouterServerSnapshot,
-  type RouterLifecycleContext,
   type RouterLifecyclePhase,
-} from '@modern-js/runtime/context';
+} from '@modern-js/runtime-extensions/router-state';