@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.131

package/src/vite/utils/forward-user-plugins.ts

@@ -0,0 +1,171 @@
+import type { Plugin, ResolvedConfig, UserConfig } from "vite";
+
+/**
+ * Whether a user plugin must NOT be forwarded into the discovery temp server.
+ *
+ * Framework-owned plugins are matched precisely -- by exact name or a
+ * namespaced prefix -- rather than by a loose substring/word prefix, so an
+ * unrelated user resolver named e.g. `rsc-paths` or `cloudflare-kv-alias` is
+ * still forwarded (it would otherwise reproduce issue #500).
+ *
+ * - `vite:*`               Vite core + official plugins (incl.
+ *                          @vitejs/plugin-react's `vite:react-*`). The temp
+ *                          server already provides its own core; forwarding
+ *                          these would duplicate or conflict with it.
+ * - `rsc` / `rsc:*`        @vitejs/plugin-rsc. createTempRscServer instantiates
+ *                          its own rsc() plugin; forwarding would duplicate it.
+ *                          Matched exactly (`rsc`) or by the `rsc:` namespace --
+ *                          NOT every `rsc`-prefixed name.
+ * - `@rangojs/router*`     Our own plugins. The discovery plugin spawns the
+ *                          temp server, so forwarding would recurse infinitely.
+ * - `@cloudflare/vite-plugin*` / @cloudflare/vite-plugin (emits the scoped
+ *   `vite-plugin-cloudflare*`  `@cloudflare/vite-plugin` and unscoped
+ *                          `vite-plugin-cloudflare` / `vite-plugin-cloudflare:*`).
+ *                          Forwarding re-inits workerd, defeating the Node temp
+ *                          server. Matched specifically so a scoped user resolver
+ *                          like `@cloudflare/kv-alias` is still forwarded.
+ */
+function isDenied(name: string): boolean {
+  return (
+    name.startsWith("vite:") ||
+    name === "rsc" ||
+    name.startsWith("rsc:") ||
+    name.startsWith("@rangojs/router") ||
+    name.startsWith("@cloudflare/vite-plugin") ||
+    name.startsWith("vite-plugin-cloudflare")
+  );
+}
+
+/**
+ * A plugin participates in resolution if it exposes `resolveId` or `load`.
+ * Plugins that only transform, configure the server, or hook into the build
+ * lifecycle do not affect how bare specifiers resolve, so we skip them to keep
+ * the forwarded surface minimal.
+ */
+function hasResolutionHooks(p: Plugin): boolean {
+  return Boolean((p as any).resolveId || (p as any).load);
+}
+
+/**
+ * Strip a resolved plugin instance down to its resolution hooks plus the
+ * gating fields that decide whether/where it runs.
+ *
+ * We reuse the SAME instance objects captured from `config.plugins`. By the
+ * time `configResolved` fires on the discovery plugin, every plugin's own
+ * `config`/`configResolved` has already run on the main server, so any state
+ * a `resolveId` hook depends on (e.g. vite-tsconfig-paths' compiled path
+ * matcher, held in closure) is already populated. Forwarding only the
+ * resolution hooks therefore preserves correct resolution while avoiding a
+ * second `buildStart`/`configureServer`/`config` lifecycle in the temp server.
+ *
+ * `enforce` and `applyToEnvironment` are preserved so ordering and per-environment
+ * gating match the real pipeline.
+ *
+ * `apply` is intentionally dropped. Vite filters plugins by `apply` against the
+ * command during config resolution, so the `config.plugins` we read here is
+ * already command-filtered by the main server (build: `apply: "build"` +
+ * unconditional; dev: `apply: "serve"` + unconditional). The discovery temp
+ * server is always created with `createServer` (`command === "serve"`), so a
+ * forwarded `apply: "build"` plugin would be filtered straight back out -- even
+ * during a production build, where build-only resolvers are exactly what
+ * static/prerender rendering needs. Since the source list is already correct for
+ * the current command, the forwarded copy must carry no `apply` gate.
+ */
+function stripToResolutionHooks(p: Plugin): Plugin {
+  const stripped: Plugin = { name: p.name };
+  if ((p as any).enforce) (stripped as any).enforce = (p as any).enforce;
+  if ((p as any).applyToEnvironment)
+    (stripped as any).applyToEnvironment = (p as any).applyToEnvironment;
+  if ((p as any).resolveId) (stripped as any).resolveId = (p as any).resolveId;
+  if ((p as any).load) (stripped as any).load = (p as any).load;
+  return stripped;
+}
+
+/**
+ * Pick the user's resolution plugins from the resolved plugin list, denylist
+ * framework-owned plugins, keep only those with resolution hooks, and strip
+ * each to its resolution surface. Returns plugin objects safe to drop into the
+ * discovery temp server's `plugins` array.
+ */
+export function selectForwardableResolvePlugins(
+  plugins: readonly Plugin[] | undefined,
+): Plugin[] {
+  if (!plugins) return [];
+  const forwarded: Plugin[] = [];
+  for (const p of plugins) {
+    const name = p?.name;
+    if (!name || isDenied(name)) continue;
+    if (!hasResolutionHooks(p)) continue;
+    forwarded.push(stripToResolutionHooks(p));
+  }
+  return forwarded;
+}
+
+/**
+ * The resolution-relevant slice of the user's resolved config that is plain
+ * data (no plugin re-execution): everything under `resolve` that influences
+ * how specifiers map to files, plus `define` and `oxc` so transforms and
+ * compile-time constants match request time.
+ */
+export interface ForwardedRunnerConfig {
+  resolve: UserConfig["resolve"];
+  define: UserConfig["define"];
+  oxc: UserConfig["oxc"];
+}
+
+/**
+ * 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.
+ *
+ * `tsconfigPaths` is forwarded so Vite 8's native tsconfig `paths` resolution
+ * (a top-level `resolve` flag, off by default) reaches the temp server. The
+ * server is created with `configFile: false` and an explicit, allowlisted
+ * resolve slice, so a flag that is not copied here is simply absent during
+ * discovery — which would make path-aliased imports fail at prerender/static
+ * time the same way unforwarded resolveId plugins did (issue #500).
+ *
+ * `oxc` keeps the user's options but always pins the RSC-required JSX runtime
+ * (automatic, react), since the temp server compiles the handler graph as
+ * React server components regardless of the user's app-level JSX config. Vite 8
+ * replaced the deprecated `esbuild` transform option with `oxc`, so we read and
+ * forward `oxc` exclusively — no `esbuild` field is touched.
+ */
+export function pickForwardedRunnerConfig(
+  config: ResolvedConfig,
+): ForwardedRunnerConfig {
+  const r = config.resolve ?? ({} as ResolvedConfig["resolve"]);
+  const resolve: NonNullable<UserConfig["resolve"]> = {};
+  if (r.alias !== undefined) resolve.alias = r.alias as any;
+  if (r.dedupe !== undefined) resolve.dedupe = r.dedupe;
+  if (r.conditions !== undefined) resolve.conditions = r.conditions;
+  if (r.mainFields !== undefined) resolve.mainFields = r.mainFields;
+  if (r.extensions !== undefined) resolve.extensions = r.extensions;
+  if (r.preserveSymlinks !== undefined)
+    resolve.preserveSymlinks = r.preserveSymlinks;
+  if (r.tsconfigPaths !== undefined) resolve.tsconfigPaths = r.tsconfigPaths;
+
+  // Pin the RSC JSX runtime on top of the user's oxc options. The user's
+  // jsx sub-options (e.g. `development`) are preserved when present; only
+  // `runtime`/`importSource` are forced to the values the RSC compile needs.
+  const userOxc = config.oxc;
+  const userJsx =
+    userOxc &&
+    typeof userOxc === "object" &&
+    typeof userOxc.jsx === "object" &&
+    userOxc.jsx !== null
+      ? userOxc.jsx
+      : {};
+  const oxc: UserConfig["oxc"] =
+    userOxc && typeof userOxc === "object"
+      ? {
+          ...userOxc,
+          jsx: { ...userJsx, runtime: "automatic", importSource: "react" },
+        }
+      : { jsx: { runtime: "automatic", importSource: "react" } };
+
+  return {
+    resolve,
+    define: config.define,
+    oxc,
+  };
+}

package/src/vite/utils/manifest-utils.ts

@@ -0,0 +1,15 @@
+export {
+  flattenLeafEntries,
+  buildRouteToStaticPrefix,
+} from "../../build/prefix-tree-utils.js";
+
+/**
+ * Wrap a value as `JSON.parse('...')` instead of a JS object literal.
+ * V8's JSON parser is significantly faster than its full JS parser for large
+ * objects, so this improves startup time for big route manifests.
+ */
+export function jsonParseExpression(value: unknown): string {
+  const json = JSON.stringify(value);
+  const escaped = json.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+  return `JSON.parse('${escaped}')`;
+}

package/src/vite/utils/package-resolution.ts

@@ -0,0 +1,89 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import packageJson from "../../../package.json";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * The canonical name used in virtual entries (without scope)
+ */
+const VIRTUAL_PACKAGE_NAME = "@rangojs/router";
+
+export function getPublishedPackageName(): string {
+  return packageJson.name;
+}
+
+export function isInstalledFromNpm(): boolean {
+  const packageName = getPublishedPackageName();
+  // Check if the scoped package exists in node_modules
+  return existsSync(resolve(process.cwd(), "node_modules", packageName));
+}
+
+export function isWorkspaceDevelopment(): boolean {
+  return !isInstalledFromNpm();
+}
+
+const SOURCE_EXPORT_SUBPATHS = Object.keys(packageJson.exports)
+  .filter((key) => {
+    const entry = (
+      packageJson.exports as Record<string, Record<string, string>>
+    )[key];
+    // Include if any non-types condition points to TypeScript source
+    return Object.entries(entry).some(
+      ([condition, path]) =>
+        condition !== "types" &&
+        typeof path === "string" &&
+        /\.tsx?$/.test(path),
+    );
+  })
+  .map((key) => key.replace(/^\./, ""));
+
+export function getExcludeDeps(): string[] {
+  const packageName = getPublishedPackageName();
+  const excludes: string[] = [];
+
+  for (const subpath of SOURCE_EXPORT_SUBPATHS) {
+    // Add scoped package paths
+    excludes.push(`${packageName}${subpath}`);
+    // Add virtual/aliased paths (before alias resolution)
+    if (packageName !== VIRTUAL_PACKAGE_NAME) {
+      excludes.push(`${VIRTUAL_PACKAGE_NAME}${subpath}`);
+    }
+  }
+
+  return excludes;
+}
+
+const ALIAS_SUBPATHS = SOURCE_EXPORT_SUBPATHS;
+
+export function getPackageAliases(): Record<string, string> {
+  if (isWorkspaceDevelopment()) {
+    return {};
+  }
+
+  const packageName = getPublishedPackageName();
+  const aliases: Record<string, string> = {};
+
+  for (const subpath of ALIAS_SUBPATHS) {
+    aliases[`${VIRTUAL_PACKAGE_NAME}${subpath}`] = `${packageName}${subpath}`;
+  }
+
+  return aliases;
+}
+
+export function getVendorAliases(): Record<string, string> {
+  const specs = [
+    "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
+    "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+  ];
+  const aliases: Record<string, string> = {};
+  for (const spec of specs) {
+    try {
+      aliases[spec] = require.resolve(spec);
+    } catch {
+      // Non-fatal; Vite will warn if it cannot resolve the spec
+    }
+  }
+  return aliases;
+}

package/src/vite/utils/prerender-utils.ts

@@ -0,0 +1,223 @@
+import { createHash } from "node:crypto";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { resolve } from "node:path";
+
+export function escapeRegExp(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function encodePathParam(value: unknown): string {
+  return String(value)
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+export function substituteRouteParams(
+  pattern: string,
+  params: Record<string, string>,
+  encode: (value: string) => string = encodeURIComponent,
+): string {
+  let result = pattern;
+  let hadOmittedOptional = false;
+
+  for (const [key, value] of Object.entries(params)) {
+    const escaped = escapeRegExp(key);
+    if (value === "") {
+      result = result.replace(
+        new RegExp(`:${escaped}(\\([^)]*\\))?(?!\\?)`),
+        "",
+      );
+      result = result.replace(`*${key}`, "");
+    } else {
+      result = result.replace(
+        new RegExp(`:${escaped}(\\([^)]*\\))?\\??`),
+        encode(value),
+      );
+      result = result.replace(`*${key}`, encode(value));
+    }
+  }
+
+  result = result.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?\?/g, () => {
+    hadOmittedOptional = true;
+    return "";
+  });
+
+  if (hadOmittedOptional) {
+    const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+    result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
+    if (hadTrailingSlash && !result.endsWith("/")) result += "/";
+  }
+
+  return result;
+}
+
+export async function runWithConcurrency<T>(
+  items: T[],
+  concurrency: number,
+  fn: (item: T) => Promise<void>,
+): Promise<void> {
+  const limit = Math.max(1, Math.min(concurrency, items.length));
+  if (limit <= 1) {
+    for (const item of items) await fn(item);
+    return;
+  }
+  let nextIndex = 0;
+  async function worker() {
+    while (nextIndex < items.length) {
+      const idx = nextIndex++;
+      await fn(items[idx]);
+    }
+  }
+  await Promise.all(Array.from({ length: limit }, () => worker()));
+}
+
+export function groupByConcurrency<T extends { concurrency: number }>(
+  entries: T[],
+): { concurrency: number; entries: T[] }[] {
+  const map = new Map<number, T[]>();
+  for (const entry of entries) {
+    const key = entry.concurrency;
+    let group = map.get(key);
+    if (!group) {
+      group = [];
+      map.set(key, group);
+    }
+    group.push(entry);
+  }
+  return Array.from(map.entries(), ([concurrency, items]) => ({
+    concurrency,
+    entries: items,
+  }));
+}
+
+export function notifyOnError(
+  registry: Map<string, any>,
+  error: unknown,
+  phase: "prerender" | "static",
+  routeKey?: string,
+  pathname?: string,
+  skipped?: boolean,
+): void {
+  for (const [, routerInstance] of registry) {
+    const onError = routerInstance.onError;
+    if (!onError) continue;
+
+    const errorObj = error instanceof Error ? error : new Error(String(error));
+    const syntheticUrl = new URL("http://prerender" + (pathname || "/"));
+    const context = {
+      error: errorObj,
+      phase,
+      request: new Request(syntheticUrl),
+      url: syntheticUrl,
+      pathname: syntheticUrl.pathname,
+      method: "GET",
+      routeKey,
+      metadata: skipped ? { skipped: true } : undefined,
+    };
+
+    try {
+      const result = onError(context);
+      if (result instanceof Promise) {
+        result.catch((cbErr: unknown) => {
+          console.error(`[Build.onError] Callback error:`, cbErr);
+        });
+      }
+    } catch (cbErr) {
+      console.error(`[Build.onError] Callback error:`, cbErr);
+    }
+    break; // Only notify the first router with onError
+  }
+}
+
+/**
+ * Resolve a thrown build-time render error into the prerender build's policy and
+ * log a per-entry line. A `Skip` (or any render error under `prerender.onError:
+ * "warn"`) logs and returns so the caller skips the entry; a render error under
+ * the default "fail" logs FAIL, notifies `onError`, and re-throws to fail the
+ * build. Shared by `expandPrerenderRoutes` (prerender) and `renderStaticHandlers`
+ * (static) so the Skip/warn/fail policy lives in one place. `label` is the padded
+ * URL / handler name for the log line; `elapsed` is the per-entry duration string.
+ */
+export function resolvePrerenderError(
+  registry: Map<string, any>,
+  error: any,
+  onError: "fail" | "warn",
+  label: string,
+  elapsed: string,
+  phase: "prerender" | "static",
+  routeKey?: string,
+  pathname?: string,
+): void {
+  const isSkip = error?.name === "Skip";
+  if (isSkip || onError === "warn") {
+    if (isSkip) {
+      console.log(`[rango]   SKIP ${label} (${elapsed}ms) - ${error.message}`);
+    } else {
+      console.warn(
+        `[rango]   WARN ${label} (${elapsed}ms) - render error, not pre-rendered (prerender.onError: "warn"): ${error.message}`,
+      );
+    }
+    notifyOnError(registry, error, phase, routeKey, pathname, true);
+    return;
+  }
+  console.error(`[rango]   FAIL ${label} (${elapsed}ms) - ${error.message}`);
+  notifyOnError(registry, error, phase, routeKey, pathname);
+  throw error;
+}
+
+function getStagedAssetDir(projectRoot: string): string {
+  return resolve(projectRoot, "node_modules/.rangojs-router-build/rsc-assets");
+}
+
+export function resetStagedBuildAssets(projectRoot: string): void {
+  rmSync(getStagedAssetDir(projectRoot), { recursive: true, force: true });
+}
+
+export function stageBuildAssetModule(
+  projectRoot: string,
+  prefix: "__pr" | "__st",
+  exportValue: string,
+): string {
+  const stagedDir = getStagedAssetDir(projectRoot);
+  mkdirSync(stagedDir, { recursive: true });
+
+  const contentHash = createHash("sha256")
+    .update(exportValue)
+    .digest("hex")
+    .slice(0, 8);
+  const fileName = `${prefix}-${contentHash}.js`;
+  const filePath = resolve(stagedDir, fileName);
+
+  if (!existsSync(filePath)) {
+    writeFileSync(filePath, `export default ${exportValue};\n`);
+  }
+
+  return fileName;
+}
+
+export function copyStagedBuildAssets(
+  projectRoot: string,
+  fileNames: Iterable<string>,
+): number {
+  const stagedDir = getStagedAssetDir(projectRoot);
+  const distAssetsDir = resolve(projectRoot, "dist/rsc/assets");
+  mkdirSync(distAssetsDir, { recursive: true });
+
+  let totalBytes = 0;
+  for (const fileName of new Set(fileNames)) {
+    const stagedPath = resolve(stagedDir, fileName);
+    const distPath = resolve(distAssetsDir, fileName);
+    copyFileSync(stagedPath, distPath);
+    totalBytes += statSync(stagedPath).size;
+  }
+
+  return totalBytes;
+}