@bleedingdev/modern-js-plugin-tanstack 3.2.0-ultramodern.12 → 3.2.0-ultramodern.121

package/src/cli/index.ts

@@ -19,13 +19,26 @@ import {
   NESTED_ROUTE_SPEC_FILE,
 } from '@modern-js/utils';
 import {
+  createTanstackRsbuildRouteSplittingProfile,
+  type TanstackRouteCodeSplittingOption,
+} from './routeSplitting';
+import {
+  collectCanonicalRoutesForEntry,
   generateTanstackRouterTypesSourceForEntry,
-  isTanstackRouterFrameworkEnabled,
 } from './tanstackTypes';
 
+export type {
+  TanstackRouteCodeSplittingOption,
+  TanstackRsbuildRouteSplittingProfile,
+} from './routeSplitting';
+export {
+  createTanstackRsbuildRouteSplittingProfile,
+  resolveTanstackRouteCodeSplittingEnabled,
+} from './routeSplitting';
 export {
+  type CollectCanonicalRoutesOptions,
+  collectCanonicalRoutesForEntry,
   generateTanstackRouterTypesSourceForEntry,
-  isTanstackRouterFrameworkEnabled,
 } from './tanstackTypes';
 
 const DEFAULT_ROUTES_DIR = 'routes';
@@ -35,10 +48,12 @@ const ENTRYPOINTS_KEY = '@modern-js/plugin-tanstack';
 export type TanstackRouterPluginOptions = {
   routesDir?: string;
   generatedDirName?: string;
+  routeCodeSplitting?: TanstackRouteCodeSplittingOption;
 };
 
 type RuntimeRouterCliHelpers = {
   getEntrypointRoutesDir: (entrypoint: Entrypoint) => string | null;
+  getEntrypointRoutesOwner: (entrypoint: Entrypoint) => string | null;
   handleFileChange: (
     api: CLIPluginAPI<AppTools>,
     event: unknown,
@@ -58,9 +73,6 @@ type RuntimeRouterCliHelpers = {
     entrypoints: Entrypoint[],
     options?: {
       entrypointsKey?: string;
-      generateCodeOptions?: {
-        enableTanstackTypes?: boolean;
-      };
     },
   ) => Promise<Record<string, (NestedRouteForCli | PageRoute)[]>>;
   handleModifyEntrypoints: (
@@ -82,7 +94,11 @@ function getRuntimeRouterCli(): RuntimeRouterCliHelpers {
 
   const cli =
     require('@modern-js/runtime/cli') as Partial<RuntimeRouterCliHelpers>;
-  if (cli.handleGeneratorEntryCode && cli.getEntrypointRoutesDir) {
+  if (
+    cli.handleGeneratorEntryCode &&
+    cli.getEntrypointRoutesDir &&
+    cli.getEntrypointRoutesOwner
+  ) {
     runtimeRouterCli = cli as RuntimeRouterCliHelpers;
     return runtimeRouterCli;
   }
@@ -110,6 +126,8 @@ async function writeFileIfChanged(filePath: string, content: string) {
 function createRegisterDtsContent(opts: {
   entries: string[];
   runtimeModule: string;
+  canonicalRoutes?: Record<string, string> | null;
+  i18nRuntimeModule?: string;
 }) {
   const importStatements = opts.entries
     .map(
@@ -121,6 +139,20 @@ function createRegisterDtsContent(opts: {
     .map((_, index) => `typeof router${index}`)
     .join(' | ');
 
+  const canonicalEntries = Object.entries(opts.canonicalRoutes ?? {});
+  const canonicalRoutesAugmentation =
+    canonicalEntries.length > 0
+      ? `
+declare module '${opts.i18nRuntimeModule || '@modern-js/plugin-i18n/runtime'}' {
+  interface UltramodernCanonicalRoutes {
+${canonicalEntries
+  .map(([routePath, paramsType]) => `    '${routePath}': ${paramsType};`)
+  .join('\n')}
+  }
+}
+`
+      : '';
+
   return `// This file is auto-generated by Modern.js. Do not edit manually.
 
 ${importStatements}
@@ -130,7 +162,7 @@ declare module '${opts.runtimeModule}' {
     router: ${routerUnionType};
   }
 }
-`;
+${canonicalRoutesAugmentation}`;
 }
 
 export async function writeTanstackRegisterFile(opts: {
@@ -138,12 +170,16 @@ export async function writeTanstackRegisterFile(opts: {
   generatedDirName?: string;
   runtimeModule?: string;
   srcDirectory: string;
+  canonicalRoutes?: Record<string, string> | null;
+  i18nRuntimeModule?: string;
 }) {
   const {
     entries,
     generatedDirName = DEFAULT_GENERATED_DIR_NAME,
     runtimeModule = '@modern-js/plugin-tanstack/runtime',
     srcDirectory,
+    canonicalRoutes,
+    i18nRuntimeModule,
   } = opts;
 
   if (entries.length === 0) {
@@ -158,7 +194,12 @@ export async function writeTanstackRegisterFile(opts: {
 
   await writeFileIfChanged(
     registerDtsPath,
-    createRegisterDtsContent({ entries, runtimeModule }),
+    createRegisterDtsContent({
+      entries,
+      runtimeModule,
+      canonicalRoutes,
+      i18nRuntimeModule,
+    }),
   );
 }
 
@@ -166,11 +207,19 @@ export async function writeTanstackRouterTypesForEntries(opts: {
   appContext: AppToolsContext;
   generatedDirName?: string;
   routesByEntry: Record<string, (NestedRouteForCli | PageRoute)[]>;
+  /**
+   * Whether `@modern-js/plugin-i18n` is actually installed in the app. The
+   * `register.gen.d.ts` augmentation of '@modern-js/plugin-i18n/runtime' is
+   * only emitted when this is true — otherwise apps with a hand-rolled
+   * `/:lang/` param would fail typechecking on an unresolvable module.
+   */
+  i18nPluginInstalled?: boolean;
 }) {
   const {
     appContext,
     generatedDirName = DEFAULT_GENERATED_DIR_NAME,
     routesByEntry,
+    i18nPluginInstalled = false,
   } = opts;
 
   const entryNames = Object.keys(routesByEntry);
@@ -211,10 +260,31 @@ export async function writeTanstackRouterTypesForEntries(opts: {
     return a.localeCompare(b);
   });
 
+  // Merge the canonical (language-agnostic) route maps of every entry so the
+  // typed i18n Link covers all routes the app can navigate to. Only relevant
+  // when plugin-i18n is actually installed — without it the emitted module
+  // augmentation would reference an unresolvable module.
+  let canonicalRoutes: Record<string, string> | null = null;
+  if (i18nPluginInstalled) {
+    for (const entryName of registerEntries) {
+      const entryCanonicalRoutes = collectCanonicalRoutesForEntry(
+        routesByEntry[entryName],
+        { localeParamHeuristic: true },
+      );
+      if (entryCanonicalRoutes) {
+        canonicalRoutes = {
+          ...entryCanonicalRoutes,
+          ...(canonicalRoutes ?? {}),
+        };
+      }
+    }
+  }
+
   await writeTanstackRegisterFile({
     entries: registerEntries,
     generatedDirName,
     srcDirectory: appContext.srcDirectory,
+    canonicalRoutes,
   });
 }
 
@@ -224,6 +294,8 @@ export function tanstackRouterPlugin(
   const routesDir = options.routesDir || DEFAULT_ROUTES_DIR;
   const generatedDirName =
     options.generatedDirName || DEFAULT_GENERATED_DIR_NAME;
+  const routeSplittingProfile =
+    createTanstackRsbuildRouteSplittingProfile(options);
 
   return {
     name: '@modern-js/plugin-tanstack',
@@ -236,11 +308,38 @@ export function tanstackRouterPlugin(
         return getEntrypointRoutesDir(entrypoint) === routesDir;
       };
 
-      api._internalRuntimePlugins(({ entrypoint, plugins }) => {
-        if (!isTanstackEntrypoint(entrypoint as Entrypoint)) {
-          return { entrypoint, plugins };
+      // Entrypoints claimed by another file-route convention — the built-in
+      // pages/ or routes/ entries of @modern-js/runtime's router plugin, or
+      // an entry tagged by a different routes-owner plugin. Their router
+      // runtime plugin must be left untouched: redirecting it through our
+      // wrapper would value-import the TanStack runtime into bundles that
+      // never use it, and pushing a second `router` plugin can install two
+      // routers for one entry.
+      const isForeignRouteEntrypoint = (entrypoint: Entrypoint) => {
+        const { getEntrypointRoutesDir, getEntrypointRoutesOwner } =
+          getRuntimeRouterCli();
+        if (getEntrypointRoutesOwner(entrypoint)) {
+          // Owned by some routes-owner plugin. TanStack-owned entries were
+          // already claimed by the isTanstackEntrypoint branch, so any owner
+          // seen here is foreign.
+          return true;
+        }
+        if (entrypoint.pageRoutesEntry) {
+          return true;
         }
+        return getEntrypointRoutesDir(entrypoint) !== null;
+      };
 
+      const isI18nPluginInstalled = () => {
+        const { plugins } = api.getAppContext() as {
+          plugins?: Array<{ name?: string }>;
+        };
+        return Boolean(
+          plugins?.some(plugin => plugin?.name === '@modern-js/plugin-i18n'),
+        );
+      };
+
+      api._internalRuntimePlugins(({ entrypoint, plugins }) => {
         const { metaName, serverRoutes } = api.getAppContext();
         const serverBase = serverRoutes
           .filter(
@@ -249,11 +348,44 @@ export function tanstackRouterPlugin(
           .map(route => route.urlPath)
           .sort((a, b) => (a.length - b.length > 0 ? -1 : 1));
 
-        plugins.push({
-          name: 'tanstackRouter',
-          path: `@${metaName}/plugin-tanstack/runtime`,
-          config: { serverBase },
-        });
+        if (isTanstackEntrypoint(entrypoint as Entrypoint)) {
+          plugins.push({
+            name: 'tanstackRouter',
+            path: `@${metaName}/plugin-tanstack/runtime`,
+            config: { serverBase },
+          });
+
+          return { entrypoint, plugins };
+        }
+
+        // Entries owned by the built-in router (classic routes/ or pages/
+        // conventions) or by another routes-owner plugin keep their own
+        // router runtime plugin untouched.
+        if (isForeignRouteEntrypoint(entrypoint as Entrypoint)) {
+          return { entrypoint, plugins };
+        }
+
+        // True custom entry without any file-route convention (`createRoutes`
+        // apps, hand-rolled App entries, ...): having this plugin installed
+        // is the explicit signal that the app routes through the
+        // router-provider registry — no source sniffing of modern.runtime.ts.
+        // Inject the framework-resolving router plugin of @modern-js/runtime
+        // through our own runtime/router module, so the TanStack provider
+        // registration is value-imported together with it and can never be
+        // tree-shaken away from the entry.
+        const routerWrapperPath = `@${metaName}/plugin-tanstack/runtime/router`;
+        const existingRouterPlugin = plugins.find(
+          plugin => plugin.name === 'router',
+        );
+        if (existingRouterPlugin) {
+          existingRouterPlugin.path = routerWrapperPath;
+        } else {
+          plugins.push({
+            name: 'router',
+            path: routerWrapperPath,
+            config: { serverBase },
+          });
+        }
 
         return { entrypoint, plugins };
       });
@@ -265,10 +397,21 @@ export function tanstackRouterPlugin(
       }));
 
       api.config(() => ({
+        ...routeSplittingProfile.defaultConfig,
         source: {
           include: [
+            // TanStack Router and its runtime deps ship modern syntax and
+            // must be down-leveled for the app's browser targets.
             /[\\/]node_modules[\\/]@tanstack[\\/]react-router[\\/]/,
-            path.resolve(__dirname, '../runtime').replace('cjs', 'esm'),
+            /[\\/]node_modules[\\/]@tanstack[\\/]router-core[\\/]/,
+            /[\\/]node_modules[\\/]@tanstack[\\/]react-store[\\/]/,
+            // This package's own dist runtime, too. `__dirname` is
+            // dist/{cjs,esm-node}/cli (or src/cli in tests), so the package
+            // dist root is two levels up. Resolution-based — no string
+            // surgery: the old `.replace('cjs', 'esm')` corrupted workspace
+            // paths containing 'cjs' and, under the ESM CLI condition, never
+            // matched the dist/esm runtime that browsers actually bundle.
+            path.resolve(__dirname, '..', '..'),
           ],
         },
       }));
@@ -295,9 +438,6 @@ export function tanstackRouterPlugin(
           tanstackEntrypoints,
           {
             entrypointsKey: ENTRYPOINTS_KEY,
-            generateCodeOptions: {
-              enableTanstackTypes: false,
-            },
           },
         );
 
@@ -305,6 +445,7 @@ export function tanstackRouterPlugin(
           appContext: api.getAppContext(),
           generatedDirName,
           routesByEntry,
+          i18nPluginInstalled: isI18nPluginInstalled(),
         });
       });
 
@@ -323,9 +464,6 @@ export function tanstackRouterPlugin(
               entrypoints,
               {
                 entrypointsKey: ENTRYPOINTS_KEY,
-                generateCodeOptions: {
-                  enableTanstackTypes: false,
-                },
               },
             );
 
@@ -333,6 +471,7 @@ export function tanstackRouterPlugin(
               appContext: api.getAppContext(),
               generatedDirName,
               routesByEntry,
+              i18nPluginInstalled: isI18nPluginInstalled(),
             });
           },
         });

package/src/cli/routeSplitting.ts

@@ -0,0 +1,43 @@
+export type TanstackRouteCodeSplittingOption =
+  | boolean
+  | {
+      enabled?: boolean;
+    };
+
+export type TanstackRsbuildRouteSplittingProfile = {
+  defaultConfig: {
+    output: {
+      splitRouteChunks: boolean;
+    };
+  };
+};
+
+export function resolveTanstackRouteCodeSplittingEnabled(
+  option?: TanstackRouteCodeSplittingOption,
+) {
+  if (typeof option === 'boolean') {
+    return option;
+  }
+
+  return option?.enabled ?? true;
+}
+
+/**
+ * Route chunking for TanStack entries is owned by Modern's
+ * `output.splitRouteChunks`; the TanStack Start Rspack splitter does not
+ * apply because Modern generates TanStack route trees from Modern route
+ * metadata rather than TanStack file-route factory modules.
+ */
+export function createTanstackRsbuildRouteSplittingProfile(opts: {
+  routeCodeSplitting?: TanstackRouteCodeSplittingOption;
+}): TanstackRsbuildRouteSplittingProfile {
+  return {
+    defaultConfig: {
+      output: {
+        splitRouteChunks: resolveTanstackRouteCodeSplittingEnabled(
+          opts.routeCodeSplitting,
+        ),
+      },
+    },
+  };
+}