@bleedingdev/modern-js-plugin-tanstack 3.5.0-ultramodern.30 → 3.5.0-ultramodern.31

package/src/cli/artifacts.ts

@@ -0,0 +1,255 @@
+// @effect-diagnostics asyncFunction:off nodeBuiltinImport:off strictBooleanExpressions:off processEnv:off processEnvInEffect:off
+
+import path from 'node:path';
+import type { AppToolsContext } from '@modern-js/app-tools';
+import type { NestedRouteForCli, PageRoute } from '@modern-js/types';
+import { fs } from '@modern-js/utils';
+
+import {
+  collectCanonicalRoutesForEntry,
+  generateTanstackRouterTypesSourceForEntry,
+} from './tanstackTypes';
+
+const DEFAULT_GENERATED_DIR_NAME = 'modern-tanstack';
+
+async function writeFileIfChanged(filePath: string, content: string) {
+  try {
+    const previous = (await fs.pathExists(filePath))
+      ? await fs.readFile(filePath, 'utf-8')
+      : null;
+    if (previous === content) {
+      return;
+    }
+  } catch {
+    // Fall through and rewrite the generated file.
+  }
+
+  await fs.outputFile(filePath, content, 'utf-8');
+}
+
+function createRegisterDtsContent(opts: {
+  entries: string[];
+  runtimeModule: string;
+  canonicalRoutes?: Record<string, string> | null;
+  i18nRuntimeModule?: string;
+}) {
+  const importStatements = opts.entries
+    .map(
+      (entryName, index) =>
+        `import type { router as router${index} } from './${entryName}/router.gen';`,
+    )
+    .join('\n');
+  const routerUnionType = opts.entries
+    .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}
+
+declare module '${opts.runtimeModule}' {
+  interface Register {
+    router: ${routerUnionType};
+  }
+}
+${canonicalRoutesAugmentation}`;
+}
+
+export async function writeTanstackRegisterFile(opts: {
+  entries: string[];
+  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) {
+    return;
+  }
+
+  const registerDtsPath = path.join(
+    srcDirectory,
+    generatedDirName,
+    'register.gen.d.ts',
+  );
+
+  await writeFileIfChanged(
+    registerDtsPath,
+    createRegisterDtsContent({
+      entries,
+      runtimeModule,
+      canonicalRoutes,
+      i18nRuntimeModule,
+    }),
+  );
+}
+
+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);
+
+  await Promise.all(
+    entryNames.map(async entryName => {
+      const { routerGenTs } = await generateTanstackRouterTypesSourceForEntry({
+        appContext,
+        entryName,
+        generatedDirName,
+        routes: routesByEntry[entryName],
+      });
+
+      await writeFileIfChanged(
+        path.join(
+          appContext.srcDirectory,
+          generatedDirName,
+          entryName,
+          'router.gen.ts',
+        ),
+        routerGenTs,
+      );
+    }),
+  );
+
+  const mainEntryName = appContext.entrypoints?.find(
+    entrypoint => entrypoint.isMainEntry,
+  )?.entryName;
+  const registerEntries = entryNames.sort((a, b) => {
+    if (mainEntryName && a === mainEntryName) {
+      return -1;
+    }
+
+    if (mainEntryName && b === mainEntryName) {
+      return 1;
+    }
+
+    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,
+  });
+}
+
+/**
+ * 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.
+ */
+export async function generateTanstackRouteArtifacts(opts: {
+  appDirectory: string;
+  version?: string;
+}): Promise<void> {
+  const [{ createRunOptions }, { cli }, utils] = await Promise.all([
+    import('@modern-js/app-tools/cli/run'),
+    import('@modern-js/plugin/cli'),
+    import('@modern-js/utils'),
+  ]);
+  // Load-bearing, not decoration: app-tools' analyze.onPrepare only fires
+  // generateEntryCode (the hook that writes the route artifacts) when
+  // checkIsBuildCommands() is true, and getCommand() resolves the command
+  // from MODERN_ARGV before process.argv — cli.init's `command` option does
+  // not feed that check.
+  process.env.MODERN_ARGV = 'node modern build';
+  process.env.NODE_ENV = process.env.NODE_ENV || 'production';
+
+  // Resolve the app's Modern.js config file ourselves and pass it as an
+  // absolute base path. `createRunOptions` otherwise defaults its config lookup
+  // to `process.cwd()` (not `cwd`/appDirectory), so headless invocations that
+  // run from a different directory than the app — e.g. the create CLI spawning
+  // this from the workspace root — find no config, and `findExists` returns
+  // `false`. That `false` then flows into `cli.init` -> `getConfigFilePath` ->
+  // `path.isAbsolute(false)`, throwing the opaque
+  // `The "path" argument must be of type string. Received type boolean (false)`.
+  // Passing an absolute base is resolution-based: cwd no longer matters, and the
+  // downstream `getConfigFile` still appends the correct extension.
+  const { findExists, CONFIG_FILE_EXTENSIONS } = utils as {
+    findExists: (paths: string[]) => string | false;
+    CONFIG_FILE_EXTENSIONS: string[];
+  };
+  const configFileBase = path.resolve(opts.appDirectory, 'modern.config');
+  const resolvedConfigFile = findExists(
+    CONFIG_FILE_EXTENSIONS.map(extension => `${configFileBase}${extension}`),
+  );
+  if (!resolvedConfigFile) {
+    throw new Error(
+      `[plugin-tanstack] Unable to locate a Modern.js config file (modern.config.{${CONFIG_FILE_EXTENSIONS.map(
+        extension => extension.slice(1),
+      ).join(',')}}) in ${opts.appDirectory}. ` +
+        'TanStack route generation requires the app config to resolve its plugins.',
+    );
+  }
+
+  const runOptions = await createRunOptions({
+    cwd: opts.appDirectory,
+    configFile: configFileBase,
+    version:
+      opts.version || process.env.MODERN_JS_VERSION || '0.0.0-routes-generate',
+    internalPlugins: (utils as { INTERNAL_RUNTIME_PLUGINS: unknown })
+      .INTERNAL_RUNTIME_PLUGINS as never,
+  });
+  await cli.init({ ...runOptions, command: 'build' });
+}

package/src/cli/index.ts

@@ -18,15 +18,17 @@ import {
   fs,
   NESTED_ROUTE_SPEC_FILE,
 } from '@modern-js/utils';
+import { writeTanstackRouterTypesForEntries } from './artifacts';
 import {
   createTanstackRsbuildRouteSplittingProfile,
   type TanstackRouteCodeSplittingOption,
 } from './routeSplitting';
-import {
-  collectCanonicalRoutesForEntry,
-  generateTanstackRouterTypesSourceForEntry,
-} from './tanstackTypes';
 
+export {
+  generateTanstackRouteArtifacts,
+  writeTanstackRegisterFile,
+  writeTanstackRouterTypesForEntries,
+} from './artifacts';
 export type {
   TanstackRouteCodeSplittingOption,
   TanstackRsbuildRouteSplittingProfile,
@@ -113,186 +115,6 @@ function getRuntimeRouterCli(): RuntimeRouterCliHelpers {
   );
 }
 
-async function writeFileIfChanged(filePath: string, content: string) {
-  try {
-    const previous = (await fs.pathExists(filePath))
-      ? await fs.readFile(filePath, 'utf-8')
-      : null;
-    if (previous === content) {
-      return;
-    }
-  } catch {
-    // Fall through and rewrite the generated file.
-  }
-
-  await fs.outputFile(filePath, content, 'utf-8');
-}
-
-function createRegisterDtsContent(opts: {
-  entries: string[];
-  runtimeModule: string;
-  canonicalRoutes?: Record<string, string> | null;
-  i18nRuntimeModule?: string;
-}) {
-  const importStatements = opts.entries
-    .map(
-      (entryName, index) =>
-        `import type { router as router${index} } from './${entryName}/router.gen';`,
-    )
-    .join('\n');
-  const routerUnionType = opts.entries
-    .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}
-
-declare module '${opts.runtimeModule}' {
-  interface Register {
-    router: ${routerUnionType};
-  }
-}
-${canonicalRoutesAugmentation}`;
-}
-
-export async function writeTanstackRegisterFile(opts: {
-  entries: string[];
-  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) {
-    return;
-  }
-
-  const registerDtsPath = path.join(
-    srcDirectory,
-    generatedDirName,
-    'register.gen.d.ts',
-  );
-
-  await writeFileIfChanged(
-    registerDtsPath,
-    createRegisterDtsContent({
-      entries,
-      runtimeModule,
-      canonicalRoutes,
-      i18nRuntimeModule,
-    }),
-  );
-}
-
-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);
-
-  await Promise.all(
-    entryNames.map(async entryName => {
-      const { routerGenTs } = await generateTanstackRouterTypesSourceForEntry({
-        appContext,
-        entryName,
-        generatedDirName,
-        routes: routesByEntry[entryName],
-      });
-
-      await writeFileIfChanged(
-        path.join(
-          appContext.srcDirectory,
-          generatedDirName,
-          entryName,
-          'router.gen.ts',
-        ),
-        routerGenTs,
-      );
-    }),
-  );
-
-  const mainEntryName = appContext.entrypoints?.find(
-    entrypoint => entrypoint.isMainEntry,
-  )?.entryName;
-  const registerEntries = entryNames.sort((a, b) => {
-    if (mainEntryName && a === mainEntryName) {
-      return -1;
-    }
-
-    if (mainEntryName && b === mainEntryName) {
-      return 1;
-    }
-
-    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,
-  });
-}
-
 export function tanstackRouterPlugin(
   options: TanstackRouterPluginOptions = {},
 ): CliPlugin<AppTools> {
@@ -518,66 +340,4 @@ export function tanstackRouterPlugin(
   };
 }
 
-/**
- * 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.
- */
-export async function generateTanstackRouteArtifacts(opts: {
-  appDirectory: string;
-  version?: string;
-}): Promise<void> {
-  const [{ createRunOptions }, { cli }, utils] = await Promise.all([
-    import('@modern-js/app-tools/cli/run'),
-    import('@modern-js/plugin/cli'),
-    import('@modern-js/utils'),
-  ]);
-  // Load-bearing, not decoration: app-tools' analyze.onPrepare only fires
-  // generateEntryCode (the hook that writes the route artifacts) when
-  // checkIsBuildCommands() is true, and getCommand() resolves the command
-  // from MODERN_ARGV before process.argv — cli.init's `command` option does
-  // not feed that check.
-  process.env.MODERN_ARGV = 'node modern build';
-  process.env.NODE_ENV = process.env.NODE_ENV || 'production';
-
-  // Resolve the app's Modern.js config file ourselves and pass it as an
-  // absolute base path. `createRunOptions` otherwise defaults its config lookup
-  // to `process.cwd()` (not `cwd`/appDirectory), so headless invocations that
-  // run from a different directory than the app — e.g. the create CLI spawning
-  // this from the workspace root — find no config, and `findExists` returns
-  // `false`. That `false` then flows into `cli.init` -> `getConfigFilePath` ->
-  // `path.isAbsolute(false)`, throwing the opaque
-  // `The "path" argument must be of type string. Received type boolean (false)`.
-  // Passing an absolute base is resolution-based: cwd no longer matters, and the
-  // downstream `getConfigFile` still appends the correct extension.
-  const { findExists, CONFIG_FILE_EXTENSIONS } = utils as {
-    findExists: (paths: string[]) => string | false;
-    CONFIG_FILE_EXTENSIONS: string[];
-  };
-  const configFileBase = path.resolve(opts.appDirectory, 'modern.config');
-  const resolvedConfigFile = findExists(
-    CONFIG_FILE_EXTENSIONS.map(extension => `${configFileBase}${extension}`),
-  );
-  if (!resolvedConfigFile) {
-    throw new Error(
-      `[plugin-tanstack] Unable to locate a Modern.js config file (modern.config.{${CONFIG_FILE_EXTENSIONS.map(
-        extension => extension.slice(1),
-      ).join(',')}}) in ${opts.appDirectory}. ` +
-        'TanStack route generation requires the app config to resolve its plugins.',
-    );
-  }
-
-  const runOptions = await createRunOptions({
-    cwd: opts.appDirectory,
-    configFile: configFileBase,
-    version:
-      opts.version || process.env.MODERN_JS_VERSION || '0.0.0-routes-generate',
-    internalPlugins: (utils as { INTERNAL_RUNTIME_PLUGINS: unknown })
-      .INTERNAL_RUNTIME_PLUGINS as never,
-  });
-  await cli.init({ ...runOptions, command: 'build' });
-}
-
 export default tanstackRouterPlugin;

package/src/cli/tanstackTypes/canonicalRoutes.ts

@@ -0,0 +1,157 @@
+// @effect-diagnostics asyncFunction:off strictBooleanExpressions:off
+
+import type { NestedRouteForCli, PageRoute } from '@modern-js/types';
+import { MAIN_ENTRY_NAME } from '@modern-js/utils';
+import path from 'path';
+
+import { toTanstackPath } from './shared';
+
+const LOCALE_PARAM_SEGMENTS = new Set([
+  ':lang',
+  ':locale',
+  ':language',
+  '$lang',
+  '$locale',
+  '$language',
+]);
+
+type CanonicalAwareRoute = (NestedRouteForCli | PageRoute) & {
+  modernCanonicalPath?: string;
+  index?: boolean;
+  isRoot?: boolean;
+  children?: CanonicalAwareRoute[];
+};
+
+function paramsTypeForCanonicalPath(canonicalPath: string): string {
+  const fields: string[] = [];
+
+  for (const segment of canonicalPath.split('/')) {
+    if (!segment) {
+      continue;
+    }
+    if (segment === '*' || segment === '$') {
+      fields.push(`'_splat'?: string`);
+      continue;
+    }
+    if (segment.startsWith('{-$') && segment.endsWith('}')) {
+      fields.push(`${JSON.stringify(segment.slice(3, -1))}?: string`);
+      continue;
+    }
+    if (segment.startsWith('$')) {
+      fields.push(`${JSON.stringify(segment.slice(1))}: string`);
+      continue;
+    }
+    if (segment.startsWith(':')) {
+      const optional = segment.endsWith('?');
+      const name = segment.slice(1, optional ? undefined : segment.length);
+      fields.push(
+        `${JSON.stringify(optional ? name.slice(0, -1) : name)}${
+          optional ? '?' : ''
+        }: string`,
+      );
+    }
+  }
+
+  return fields.length > 0
+    ? `{ ${fields.join('; ')} }`
+    : 'Record<string, never>';
+}
+
+export type CollectCanonicalRoutesOptions = {
+  /**
+   * Whether a leading `:lang`/`:locale`/`:language` route param may be
+   * treated as an i18n locale prefix. This MUST only be enabled when
+   * `@modern-js/plugin-i18n` is actually installed: the emitted
+   * `declare module '@modern-js/plugin-i18n/runtime'` augmentation breaks
+   * typechecking (TS2664) for apps that hand-roll a `/:lang/` param without
+   * the plugin. Routes carrying `modernCanonicalPath` metadata are always
+   * honored — only plugin-i18n produces them.
+   */
+  localeParamHeuristic?: boolean;
+};
+
+/**
+ * Derive the canonical (language-agnostic) route map for an entry: the
+ * leading locale param is stripped and localized physical variants (routes
+ * carrying `modernCanonicalPath` metadata from `@modern-js/plugin-i18n`)
+ * collapse to their canonical pattern. Returns `null` when the entry has no
+ * i18n routing surface (no locale param and no localized variants), so plain
+ * TanStack apps never get a `@modern-js/plugin-i18n` module augmentation.
+ */
+export function collectCanonicalRoutesForEntry(
+  routes: (NestedRouteForCli | PageRoute)[],
+  options: CollectCanonicalRoutesOptions = {},
+): Record<string, string> | null {
+  const { localeParamHeuristic = true } = options;
+  const canonicalParams = new Map<string, string>();
+  let hasI18nSurface = false;
+
+  const normalizeJoined = (joined: string): string => {
+    const collapsed = joined.replace(/\/+/g, '/');
+    const withLeading = collapsed.startsWith('/') ? collapsed : `/${collapsed}`;
+    return withLeading.length > 1
+      ? withLeading.replace(/\/+$/, '')
+      : withLeading;
+  };
+
+  const record = (canonicalPath: string) => {
+    const normalized = normalizeJoined(canonicalPath || '/');
+    const key = toTanstackPath(normalized);
+    if (!canonicalParams.has(key)) {
+      canonicalParams.set(key, paramsTypeForCanonicalPath(normalized));
+    }
+  };
+
+  const visit = (route: CanonicalAwareRoute, parentPath: string) => {
+    let currentPath = parentPath;
+
+    if (typeof route.modernCanonicalPath === 'string') {
+      hasI18nSurface = true;
+      currentPath = normalizeJoined(route.modernCanonicalPath);
+    } else if (typeof route.path === 'string' && route.path.length > 0) {
+      const segments = route.path
+        .replace(/\[(.+?)\]/g, ':$1')
+        .split('/')
+        .filter(Boolean);
+      if (
+        localeParamHeuristic &&
+        parentPath === '' &&
+        LOCALE_PARAM_SEGMENTS.has(segments[0])
+      ) {
+        hasI18nSurface = true;
+        segments.shift();
+      }
+      currentPath = segments.length
+        ? normalizeJoined(`${parentPath}/${segments.join('/')}`)
+        : parentPath;
+    }
+
+    const children = route.children;
+    if (children && children.length > 0) {
+      for (const child of children) {
+        visit(child, currentPath);
+      }
+      return;
+    }
+
+    // Leaf page or index route: a navigable target.
+    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, '');
+  }
+
+  if (!hasI18nSurface || canonicalParams.size === 0) {
+    return null;
+  }
+
+  return Object.fromEntries(
+    [...canonicalParams.entries()].sort(([a], [b]) => a.localeCompare(b)),
+  );
+}