@rangojs/router 0.30.1 → 0.31.0

package/dist/types/build/generate-route-types.d.ts

@@ -4,5 +4,5 @@ export { generatePerModuleTypesSource, generateRouteTypesSource, } from "./route
 export { DEFAULT_EXCLUDE_PATTERNS, type ScanFilter, createScanFilter, findTsFiles, isInSkippedScanDir, } from "./route-types/scan-filter.js";
 export { writePerModuleRouteTypes, writePerModuleRouteTypesForFile, } from "./route-types/per-module-writer.js";
 export { type UnresolvableReason, type UnresolvableInclude, extractIncludesWithDiagnostics, } from "./route-types/include-resolution.js";
-export { extractUrlsFromRouter, extractBasenameFromRouter, type UrlsExtractionResult, buildCombinedRouteMapForRouterFile, detectUnresolvableIncludes, detectUnresolvableIncludesForUrlsFile, findNestedRouterConflict, formatNestedRouterConflictError, findRouterFiles, findHostRouterFiles, writeCombinedRouteTypes, genFileTsPath, resolveSearchSchemas, } from "./route-types/router-processing.js";
+export { extractUrlsFromRouter, type UrlsExtractionResult, buildCombinedRouteMapForRouterFile, detectUnresolvableIncludes, detectUnresolvableIncludesForUrlsFile, findNestedRouterConflict, formatNestedRouterConflictError, findRouterFiles, findHostRouterFiles, writeCombinedRouteTypes, genFileTsPath, resolveSearchSchemas, } from "./route-types/router-processing.js";
 export { findUrlsVariableNames } from "./route-types/per-module-writer.js";

package/dist/types/build/route-types/include-resolution.d.ts

@@ -1,5 +1,5 @@
 import ts from "typescript";
-export type UnresolvableReason = "factory-call" | "dynamic-expression" | "unresolvable-import" | "file-not-found";
+export type UnresolvableReason = "factory-call" | "dynamic-expression" | "unresolvable-import" | "file-not-found" | "unresolvable-basename";
 export interface UnresolvableInclude {
     pathPrefix: string;
     namePrefix: string | null;

package/dist/types/build/route-types/router-processing.d.ts

@@ -30,11 +30,6 @@ export type UrlsExtractionResult = {
  * Returns either a variable name or an inline code block.
  */
 export declare function extractUrlsFromRouter(code: string): UrlsExtractionResult | null;
-/**
- * Extract the `basename` string literal from createRouter({ basename: "..." }).
- * Returns the basename value or undefined if not present.
- */
-export declare function extractBasenameFromRouter(code: string): string | undefined;
 export declare function genFileTsPath(sourceFile: string): string;
 export declare function resolveSearchSchemas(publicRouteNames: string[], runtimeSchemas: Record<string, Record<string, string>> | undefined, sourceFile: string): Record<string, Record<string, string>> | undefined;
 /**
@@ -47,8 +42,9 @@ export declare function buildCombinedRouteMapForRouterFile(routerFilePath: strin
 };
 /**
  * Walk the full include tree starting from a router file and detect
- * all includes that the static parser cannot resolve.
- * Returns an array of diagnostics; empty means fully resolvable.
+ * all includes that the static parser cannot resolve, plus an explicit
+ * createRouter `basename` it cannot read (every pattern would lack the
+ * prefix). Returns an array of diagnostics; empty means fully resolvable.
  */
 export declare function detectUnresolvableIncludes(routerFilePath: string): UnresolvableInclude[];
 /**

package/dist/types/vite/temp-rsc-server.d.ts

@@ -1,12 +1,14 @@
 /**
  * The discovery temp RSC server: a minimal Vite server whose module runner
  * imports the user's router files. Shared by dev discovery
- * (discovery/dev-server-phase.ts) and build discovery
- * (discovery/build-discovery-phase.ts).
+ * (discovery/dev-server-phase.ts), build discovery
+ * (discovery/build-discovery-phase.ts) and `rango generate --runtime`
+ * (build/runtime-discovery.ts).
  *
  * Sits in src/vite/, not src/vite/discovery/: the loader hook URL below
- * resolves against this module's import.meta.url, and the published bundle
- * (dist/vite/index.js) ships the hook at the same relative path.
+ * resolves against this module's import.meta.url, and the published bundles
+ * (dist/vite/index.js, dist/bin/rango.js) ship the hook at the same relative
+ * path.
  */
 import type { ViteDevServer } from "vite";
 import type { DiscoveryState } from "./discovery/state.js";
@@ -36,4 +38,6 @@ export declare function createTempRscServer(state: DiscoveryState, options?: {
      * shell capture actually runs.
      */
     realSsrEntry?: boolean;
+    /** Caller-specific plugins, appended after the forwarded user plugins. */
+    plugins?: import("vite").Plugin[];
 }): Promise<ViteDevServer>;

package/dist/types/vite/utils/forward-user-plugins.d.ts

@@ -20,6 +20,8 @@ export interface ForwardedRunnerConfig {
 /**
  * Extract the data-only config slice to mirror into the discovery temp server.
  * `alias` is included here so callers no longer need to thread it separately.
+ * Accepts the unresolved config too: `rango generate --runtime` must not
+ * resolve it (that runs rango()'s configResolved, which writes gen files).
  *
  * `tsconfigPaths` is forwarded so Vite 8's native tsconfig `paths` resolution
  * (a top-level `resolve` flag, off by default) reaches the temp server. The
@@ -34,4 +36,4 @@ export interface ForwardedRunnerConfig {
  * replaced the deprecated `esbuild` transform option with `oxc`, so we read and
  * forward `oxc` exclusively — no `esbuild` field is touched.
  */
-export declare function pickForwardedRunnerConfig(config: ResolvedConfig): ForwardedRunnerConfig;
+export declare function pickForwardedRunnerConfig(config: Pick<ResolvedConfig | UserConfig, "resolve" | "define" | "oxc">): ForwardedRunnerConfig;

package/dist/vite/index.js

@@ -4841,6 +4841,11 @@ function getAppVersion() {
 }
 
 // src/router/basename.ts
+function normalizeBasename(basename2) {
+  if (!basename2) return void 0;
+  const trimmed = basename2.replace(/^\/+|\/+$/g, "");
+  return trimmed ? "/" + trimmed : void 0;
+}
 function prefixBasename(path6, basename2) {
   if (!basename2 || !path6.startsWith("/") || path6 === basename2 || path6.startsWith(basename2 + "/") || path6.startsWith(basename2 + "?") || path6.startsWith(basename2 + "#")) {
     return path6;
@@ -5988,7 +5993,7 @@ function serializeSearchSchema(route2, value) {
     throw projectionError(route2, 'path option "search" must be an object');
   }
   const entries = [];
-  for (const key of Object.keys(value).sort()) {
+  for (const key of Object.keys(value)) {
     const schemaValue = value[key];
     if (typeof schemaValue !== "string" || !SEARCH_SCHEMA_VALUES.has(schemaValue)) {
       throw projectionError(
@@ -7141,7 +7146,7 @@ function resolveVersionsFrom(table, routerId2) {
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.30.1",
+  version: "0.31.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -7334,7 +7339,7 @@ var package_default = {
     tag: "latest"
   },
   scripts: {
-    build: "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    build: "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js && mkdir -p dist/bin/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/bin/plugins/cloudflare-protocol-loader-hook.mjs",
     "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
     prepublishOnly: "pnpm build",
     typecheck: "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
@@ -9325,14 +9330,7 @@ function collectCreateRouterCallChain(endpoint) {
     current = receiver;
   }
 }
-function extractAllUrlsFromRouter(code) {
-  const sourceFile = ts5.createSourceFile(
-    "router.tsx",
-    code,
-    ts5.ScriptTarget.Latest,
-    true,
-    ts5.ScriptKind.TSX
-  );
+function findRouterUrls(sourceFile) {
   let result = null;
   function visit(node) {
     if (result) return;
@@ -9360,7 +9358,7 @@ function extractAllUrlsFromRouter(code) {
           if (urls2) extracted.push(urls2);
         }
         if (extracted.length > 0) {
-          result = extracted;
+          result = { createRouterCall, extractions: extracted };
           return;
         }
       }
@@ -9368,13 +9366,9 @@ function extractAllUrlsFromRouter(code) {
     ts5.forEachChild(node, visit);
   }
   visit(sourceFile);
-  return result ?? [];
-}
-function extractUrlsFromRouter(code) {
-  const extractions = extractAllUrlsFromRouter(code);
-  return extractions[extractions.length - 1] ?? null;
+  return result;
 }
-function extractBasenameFromRouter(code) {
+function extractAllUrlsFromRouter(code) {
   const sourceFile = ts5.createSourceFile(
     "router.tsx",
     code,
@@ -9382,25 +9376,112 @@ function extractBasenameFromRouter(code) {
     true,
     ts5.ScriptKind.TSX
   );
-  let result;
-  function visit(node) {
-    if (result !== void 0) return;
-    if (ts5.isCallExpression(node) && ts5.isIdentifier(node.expression) && node.expression.text === "createRouter") {
-      for (const arg of node.arguments) {
-        if (ts5.isObjectLiteralExpression(arg)) {
-          for (const prop of arg.properties) {
-            if (ts5.isPropertyAssignment(prop) && ts5.isIdentifier(prop.name) && prop.name.text === "basename" && ts5.isStringLiteral(prop.initializer)) {
-              result = prop.initializer.text;
-              return;
-            }
-          }
+  return findRouterUrls(sourceFile)?.extractions ?? [];
+}
+function extractUrlsFromRouter(code) {
+  const extractions = extractAllUrlsFromRouter(code);
+  return extractions[extractions.length - 1] ?? null;
+}
+function unwrapTypeOperators(expr) {
+  while (ts5.isAsExpression(expr) || ts5.isSatisfiesExpression(expr)) {
+    expr = expr.expression;
+  }
+  return expr;
+}
+function hasModifier(statement, kind) {
+  return ts5.canHaveModifiers(statement) && (ts5.getModifiers(statement)?.some((m) => m.kind === kind) ?? false);
+}
+function findTopLevelConst(sourceFile, name, exported) {
+  for (const statement of sourceFile.statements) {
+    if (ts5.isVariableStatement(statement) && statement.declarationList.flags & ts5.NodeFlags.Const && !hasModifier(statement, ts5.SyntaxKind.DeclareKeyword) && (!exported || hasModifier(statement, ts5.SyntaxKind.ExportKeyword))) {
+      for (const decl of statement.declarationList.declarations) {
+        if (ts5.isIdentifier(decl.name) && decl.name.text === name) {
+          return decl.initializer && unwrapTypeOperators(decl.initializer);
         }
       }
     }
-    ts5.forEachChild(node, visit);
   }
-  visit(sourceFile);
-  return result;
+  return void 0;
+}
+function findNamedImport(sourceFile, name) {
+  for (const statement of sourceFile.statements) {
+    if (!ts5.isImportDeclaration(statement) || !ts5.isStringLiteral(statement.moduleSpecifier) || statement.importClause?.isTypeOnly) {
+      continue;
+    }
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts5.isNamedImports(bindings)) continue;
+    for (const el of bindings.elements) {
+      if (!el.isTypeOnly && el.name.text === name) {
+        return {
+          specifier: statement.moduleSpecifier.text,
+          exportedName: el.propertyName?.text ?? name
+        };
+      }
+    }
+  }
+  return void 0;
+}
+function resolveTopLevelConst(name, sourceFile, routerFilePath) {
+  const local = findTopLevelConst(sourceFile, name, false);
+  if (local) return local;
+  const imported = findNamedImport(sourceFile, name);
+  if (!imported) return void 0;
+  const target = resolveImportPath(imported.specifier, routerFilePath);
+  if (!target) return void 0;
+  const targetSource = readFileSync4(target, "utf-8");
+  return findTopLevelConst(
+    ts5.createSourceFile(target, targetSource, ts5.ScriptTarget.Latest, true),
+    imported.exportedName,
+    true
+  );
+}
+function isTopLevelScope(node) {
+  for (let p = node.parent; !ts5.isSourceFile(p); p = p.parent) {
+    if (ts5.isFunctionLike(p) || ts5.isClassLike(p) || ts5.isBlock(p) || ts5.isCaseBlock(p) || ts5.isModuleBlock(p) || ts5.isIterationStatement(p, false)) {
+      return false;
+    }
+  }
+  return true;
+}
+function resolveRouterBasename(routerSource, routerFilePath) {
+  const sourceFile = ts5.createSourceFile(
+    routerFilePath,
+    routerSource,
+    ts5.ScriptTarget.Latest,
+    true,
+    ts5.ScriptKind.TSX
+  );
+  const options = findRouterUrls(sourceFile)?.createRouterCall.arguments[0];
+  const prop = options && ts5.isObjectLiteralExpression(options) ? options.properties.find(
+    (p) => (ts5.isPropertyAssignment(p) || ts5.isShorthandPropertyAssignment(p)) && ts5.isIdentifier(p.name) && p.name.text === "basename"
+  ) : void 0;
+  if (!prop) return {};
+  const valueExpr = ts5.isPropertyAssignment(prop) ? prop.initializer : prop.name;
+  const expr = unwrapTypeOperators(valueExpr);
+  let value = getStringValue(expr);
+  if (value === null && isTopLevelScope(prop)) {
+    if (ts5.isIdentifier(expr)) {
+      const init = resolveTopLevelConst(expr.text, sourceFile, routerFilePath);
+      value = init ? getStringValue(init) : null;
+    } else if (ts5.isPropertyAccessExpression(expr) && ts5.isIdentifier(expr.expression)) {
+      const owner = resolveTopLevelConst(
+        expr.expression.text,
+        sourceFile,
+        routerFilePath
+      );
+      value = owner ? resolveConstMember(owner, expr.name.text) : null;
+    }
+  }
+  return value === null ? { unresolved: valueExpr.getText(sourceFile).replace(/\s+/g, " ") } : { value };
+}
+function resolveConstMember(owner, name) {
+  if (!ts5.isObjectLiteralExpression(owner) || owner.properties.some(ts5.isSpreadAssignment)) {
+    return null;
+  }
+  const member = owner.properties.find(
+    (p) => ts5.isPropertyAssignment(p) && ts5.isIdentifier(p.name) && p.name.text === name
+  );
+  return member ? getStringValue(unwrapTypeOperators(member.initializer)) : null;
 }
 function applyBasenameToRoutes(result, basename2) {
   const prefixed = {};
@@ -9498,8 +9579,9 @@ function buildCombinedRouteMapForRouterFile(routerFilePath) {
   if (extractions.length === 0) {
     return { routes: {}, searchSchemas: {} };
   }
-  const rawBasename = extractBasenameFromRouter(routerSource);
-  const basename2 = rawBasename ? ("/" + rawBasename.replace(/^\/+|\/+$/g, "")).replace(/^\/$/, "") : void 0;
+  const basename2 = normalizeBasename(
+    resolveRouterBasename(routerSource, routerFilePath).value
+  );
   const result = { routes: {}, searchSchemas: {} };
   const memo = createScanMemo();
   for (const extraction of extractions) {
@@ -12693,7 +12775,8 @@ async function createTempRscServer(state, options = {}) {
       // to resolveId/load (plus transform for import rewriters, see
       // IMPORT_REWRITE_PLUGINS) and placed last so framework resolution runs first;
       // Vite re-sorts by `enforce`, so `enforce: "pre"` resolvers still lead.
-      ...state.userResolvePlugins
+      ...state.userResolvePlugins,
+      ...options.plugins ?? []
     ]
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.30.1",
+  "version": "0.31.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -259,7 +259,7 @@
     "node": ">=24.0.0"
   },
   "scripts": {
-    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js && mkdir -p dist/bin/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/bin/plugins/cloudflare-protocol-loader-hook.mjs",
     "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
     "test": "playwright test",

package/skills/rango/SKILL.md

@@ -445,11 +445,11 @@ npx rango generate src/urls.tsx src/api/
 
 Three modes:
 
-| Flag        | Behavior                                                                                                                                    |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| (none)      | Static parser. Exits with an error, writing nothing, if an `include()` can't be resolved statically (factory or dynamic).                   |
-| `--static`  | Static parser, but writes partial output and prints the unresolvable includes as warnings.                                                  |
-| `--runtime` | Vite-based runtime discovery (full coverage; needs `vite`; `@vitejs/plugin-rsc` comes with the router). `--config <path>` picks the config. |
+| Flag        | Behavior                                                                                                                                                                                                      |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| (none)      | Static parser. Exits with an error, writing nothing, if an `include()` can't be resolved statically (factory or dynamic), or an explicit `createRouter` `basename` isn't a string literal or top-level const. |
+| `--static`  | Static parser, but writes partial output (an unreadable basename leaves patterns unprefixed) and prints the diagnostics as warnings.                                                                          |
+| `--runtime` | Vite-based runtime discovery (full coverage; needs `vite`; `@vitejs/plugin-rsc` comes with the router). `--config <path>` picks the config.                                                                   |
 
 ### Auto-detection
 

package/skills/typesafety/generated-files-and-cli.md

@@ -111,7 +111,8 @@ imports it directly, so `Rango.Env`, `Rango.Vars`, and optional
 and client helpers.
 
 CLI flags: the default mode fails (and writes nothing) when an `include()` cannot
-be resolved statically (factory functions, dynamic expressions); `--static`
+be resolved statically (factory functions, dynamic expressions) or an explicit
+`createRouter` `basename` is not a string literal or top-level const; `--static`
 accepts partial output with warnings; `--runtime` uses Vite-based discovery for
 full coverage (needs `vite`, optional
 `--config <path>`). Passing a directory scans it for router and `urls()` files.

package/src/bin/rango.ts

@@ -189,23 +189,23 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
 
   if (uniqueDiagnostics.length > 0 && mode === "default") {
     // Hard error: no files written
-    console.error("\n[rango] Unresolvable includes detected:\n");
+    console.error("\n[rango] Unresolvable routes detected:\n");
     formatDiagnostics(uniqueDiagnostics);
     console.error(
-      "\nThe static parser cannot resolve these includes because they use " +
-        "factory functions or dynamic expressions.\n\n" +
+      "\nThe static parser cannot resolve these includes or basename because " +
+        "they use factory functions or dynamic expressions. A basename must be " +
+        "a string literal or a top-level const (in the router file or imported " +
+        "from a relative module).\n\n" +
         "Options:\n" +
         "  rango generate <path> --runtime   Use Vite-based discovery (requires vite)\n" +
-        "  rango generate <path> --static    Accept partial output (missing routes above)\n",
+        "  rango generate <path> --static    Accept partial output (missing routes or basename prefix above)\n",
     );
     process.exit(1);
   }
 
   if (uniqueDiagnostics.length > 0 && mode === "static") {
     // Warning: partial output accepted
-    console.warn(
-      "\n[rango] Warning: partial output (unresolvable includes):\n",
-    );
+    console.warn("\n[rango] Warning: partial output (unresolvable routes):\n");
     formatDiagnostics(uniqueDiagnostics);
     console.warn("");
   }
@@ -317,7 +317,12 @@ function formatDiagnostics(
   diagnostics: Array<UnresolvableInclude & { routerFile: string }>,
 ) {
   for (const d of diagnostics) {
-    const prefix = d.namePrefix ? `${d.namePrefix}.*` : `${d.pathPrefix}*`;
+    const prefix =
+      d.reason === "unresolvable-basename"
+        ? "createRouter basename"
+        : d.namePrefix
+          ? `${d.namePrefix}.*`
+          : `${d.pathPrefix}*`;
     console.error(`  ${prefix}`);
     console.error(`    Reason:  ${d.reason} -- ${d.detail}`);
     console.error(`    Source:  ${d.sourceFile}`);

package/src/build/generate-route-types.ts

@@ -26,7 +26,6 @@ export {
 } from "./route-types/include-resolution.js";
 export {
   extractUrlsFromRouter,
-  extractBasenameFromRouter,
   type UrlsExtractionResult,
   buildCombinedRouteMapForRouterFile,
   detectUnresolvableIncludes,

package/src/build/route-types/include-resolution.ts

@@ -12,7 +12,8 @@ export type UnresolvableReason =
   | "factory-call"
   | "dynamic-expression"
   | "unresolvable-import"
-  | "file-not-found";
+  | "file-not-found"
+  | "unresolvable-basename";
 
 export interface UnresolvableInclude {
   pathPrefix: string;