@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

package/src/vite/discovery/virtual-module-codegen.ts

@@ -5,11 +5,25 @@
  * per-router virtual modules used by the load() hook.
  */
 
+import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, basename, join } from "node:path";
 import { jsonParseExpression } from "../utils/manifest-utils.js";
 import { VIRTUAL_ROUTES_MANIFEST_ID } from "./state.js";
 import type { DiscoveryState } from "./state.js";
 
+/**
+ * Serialized-payload size (bytes) at or above which the trie/precomputedEntries
+ * are shipped through a runtime channel (Text module / `?raw` import) instead of
+ * an inline `JSON.parse` literal (issue #665). 512KB is ~2500 routes — the
+ * crossover where the channel's benefit (removing the JS compile on cloudflare,
+ * reclaiming ~19% escaping bloat everywhere) clears the cost of an extra
+ * artifact. Below it the inline literal wins (sub-millisecond compile, ~0 gain),
+ * so the whole long tail of normal apps stays byte-identical. The compile/parse
+ * cost tracks bytes, not route count, so this stays a byte threshold.
+ * RANGO_MANIFEST_TEXT=1 bypasses it.
+ */
+const MANIFEST_EXTERNALIZE_THRESHOLD = 512 * 1024;
+
 /**
  * Generate the code for the main virtual:rsc-router/routes-manifest module.
  */
@@ -137,6 +151,22 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
   return `// Route manifest will be populated at runtime`;
 }
 
+/**
+ * Deterministic short hash (FNV-1a, base36) used to disambiguate staged
+ * manifest filenames. The sanitized `safeId` alone collapses distinct router
+ * ids — e.g. "a/b" and "a.b" both sanitize to "a_b" — which in a multi-router
+ * build would overwrite one router's staged manifest with another's. Appending
+ * a hash of the ORIGINAL id keeps them distinct.
+ */
+function shortHash(input: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(36);
+}
+
 /**
  * Generate the code for a per-router virtual module.
  */
@@ -144,40 +174,116 @@ export function generatePerRouterModule(
   state: DiscoveryState,
   routerId: string,
 ): string {
-  // Find the per-router entry to get the gen file path
-  const routerEntry = state.perRouterManifests.find((e) => e.id === routerId);
+  const sourceFile = state.perRouterManifests.find(
+    (e) => e.id === routerId,
+  )?.sourceFile;
   const trie = state.perRouterTrieMap.get(routerId);
   const entries = state.perRouterPrecomputedMap.get(routerId);
   const lines: string[] = [];
 
-  if (routerEntry?.sourceFile) {
-    const routerDir = dirname(routerEntry.sourceFile);
-    const routerBasename = basename(routerEntry.sourceFile).replace(
-      /\.(tsx?|jsx?)$/,
-      "",
-    );
+  // No name->path map here: the eager routes-manifest module already calls
+  // setRouterManifest() with __flat(NamedRoutes) for every router, so this
+  // module carries only the derived match data (trie + precomputedEntries).
+  // The bare gen-file import is load-bearing: it is the module-graph edge that
+  // invalidates this module when routes change in dev. Without it, a Cloudflare
+  // dev program reload re-imports the cached module and ensureRouterManifest()
+  // re-installs a stale authoritative trie (wrong 404s until full restart).
+  if (sourceFile) {
+    const routerDir = dirname(sourceFile);
+    const routerBasename = basename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
     const genPath = join(
       routerDir,
       `${routerBasename}.named-routes.gen.js`,
     ).replaceAll("\\", "/");
-    lines.push(`import { NamedRoutes as _r } from ${JSON.stringify(genPath)};`);
-    lines.push(
-      `function __flat(r) { const o = {}; for (const [k, v] of Object.entries(r)) o[k] = typeof v === "string" ? v : v.path; return o; }`,
-    );
-    lines.push(`export const manifest = __flat(_r);`);
-  } else {
-    const manifest = state.perRouterManifestDataMap.get(routerId);
-    if (manifest) {
-      lines.push(`export const manifest = ${jsonParseExpression(manifest)};`);
-    }
+    lines.push(`import ${JSON.stringify(genPath)};`);
+  }
+  const hasTrie = !!trie;
+  const hasEntries = !!entries && entries.length > 0;
+
+  // The trie + precomputedEntries are the largest generated data. Inlined as a
+  // `JSON.parse('<literal>')` in the JS chunk, the isolate/process must LEX and
+  // compile that multi-MB source literal on first request before JSON.parse even
+  // runs — pure overhead, since it is data, not logic (issue #665). It also
+  // ships bloated: the build minifier re-quotes the literal to double quotes,
+  // escaping every JSON `"` as `\"` (measured 5.71MB vs 4.64MB un-escaped at 26k
+  // routes).
+  //
+  // The ONLY way to fix both is to keep the JSON out of JavaScript source — as a
+  // raw asset file that never passes through the JS minifier/compiler. On
+  // cloudflare that is a workerd Text module: import the staged `.txt` and the
+  // isolate gets the raw un-escaped bytes as a string with no compile pass
+  // (measured ~17% / ~88ms cold first-hit on a real edge deploy at 26k, and it
+  // shrinks the worker upload). The CF vite plugin types `.txt` as Text;
+  // wrangler's default rules type **/*.txt as Text for deploy and dev.
+  //
+  // Scoped to cloudflare deliberately. A Text module is the only no-JS byte
+  // channel that needs no filesystem, and cloudflare is where it pays: edge cold
+  // isolates spin up per-request under load and on every deploy, and Workers
+  // have a hard upload-size limit. node/vercel fall through to the inline
+  // literal below — an efficient runtime channel there needs `fs` (a raw asset
+  // read), whose fragility (asset co-location, runtime ENOENT) is not worth a
+  // large-app-only win that Fluid Compute amortizes and that essentially no real
+  // app reaches. `?raw` is NOT an option: in this build it inlines the JSON as a
+  // (double-quoted, compiled) JS string literal — same bloat, same compile as
+  // the inline form, plus a staged file for nothing.
+  //
+  // Build mode only (dev rebuilds the manifest per HMR; parse cost is
+  // irrelevant). Below MANIFEST_EXTERNALIZE_THRESHOLD the inline literal wins.
+  // RANGO_MANIFEST_TEXT overrides: "0" forces inline, "1" forces the Text module
+  // and bypasses the threshold (used by the cloudflare-basic dogfood e2e, whose
+  // real manifest is below the threshold).
+  const preset = state.opts?.preset ?? "node";
+  const override = process.env.RANGO_MANIFEST_TEXT;
+  const payload = manifestPayload(trie, hasTrie, entries, hasEntries);
+  const payloadJson = hasTrie || hasEntries ? JSON.stringify(payload) : "";
+  const useTextModule =
+    state.isBuildMode &&
+    preset === "cloudflare" &&
+    override !== "0" &&
+    (hasTrie || hasEntries) &&
+    (override === "1" || payloadJson.length >= MANIFEST_EXTERNALIZE_THRESHOLD);
+
+  if (useTextModule) {
+    const dir = join(state.projectRoot, "node_modules", ".rango");
+    mkdirSync(dir, { recursive: true });
+    const safeId = `${routerId.replace(/[^a-zA-Z0-9_-]/g, "_")}-${shortHash(routerId)}`;
+    const filePath = join(dir, `manifest-${safeId}.txt`).replaceAll("\\", "/");
+    writeFileSync(filePath, payloadJson);
+    lines.push(`import __manifestJson from ${JSON.stringify(filePath)};`);
+    lines.push(`const __manifestData = JSON.parse(__manifestJson);`);
+    emitManifestExports(lines, hasTrie, hasEntries);
+    return lines.join("\n");
   }
-  if (trie) {
+
+  if (hasTrie) {
     lines.push(`export const trie = ${jsonParseExpression(trie)};`);
   }
-  if (entries && entries.length > 0) {
+  if (hasEntries) {
     lines.push(
       `export const precomputedEntries = ${jsonParseExpression(entries)};`,
     );
   }
   return lines.join("\n") || "";
 }
+
+function manifestPayload(
+  trie: unknown,
+  hasTrie: boolean,
+  entries: unknown,
+  hasEntries: boolean,
+): Record<string, unknown> {
+  const payload: Record<string, unknown> = {};
+  if (hasTrie) payload.t = trie;
+  if (hasEntries) payload.p = entries;
+  return payload;
+}
+
+function emitManifestExports(
+  lines: string[],
+  hasTrie: boolean,
+  hasEntries: boolean,
+): void {
+  if (hasTrie) lines.push(`export const trie = __manifestData.t;`);
+  if (hasEntries)
+    lines.push(`export const precomputedEntries = __manifestData.p;`);
+}

package/src/vite/index.ts

@@ -24,6 +24,7 @@ export type {
   RangoOptions,
   ClientChunks,
   ClientChunkMeta,
+  HeadScriptsOption,
   BuildEnvOption,
   BuildEnvFactory,
   BuildEnvFactoryContext,

package/src/vite/plugin-types.ts

@@ -107,6 +107,11 @@ export type ClientChunks =
 
 // -- Plugin options ---------------------------------------------------------
 
+/**
+ * Document script strategy. See {@link RangoBaseOptions.headScripts}.
+ */
+export type HeadScriptsOption = "preinit" | "preload";
+
 /**
  * Base options shared by all presets
  */
@@ -126,6 +131,34 @@ interface RangoBaseOptions {
    */
   clientChunks?: ClientChunks;
 
+  /**
+   * How the document ships its JavaScript.
+   *
+   * - `"preinit"` (**default**): client-reference chunks render as EXECUTING
+   *   `<script type="module" async>` tags hoisted into `<head>` (upgrading
+   *   plugin-rsc's modulepreload hints in place), and the browser entry ships
+   *   as Fizz `bootstrapModules` — a head `modulepreload fetchpriority=low`
+   *   hint plus the executing end-of-shell `id="_R_"` module script. Chunk
+   *   execution overlaps body streaming instead of waiting for the hydration
+   *   import walk; under PPR everything lands in the stored shell prelude.
+   * - `"preload"`: the previous behavior — `<link rel="modulepreload">` hints
+   *   only, entry as an inline `import()` script at end of shell. Chunks
+   *   fetch+compile early but execute only when hydration imports them.
+   *
+   * Build-only for the chunk half: plugin-rsc resolves no JS deps per client
+   * reference in dev, so dev documents carry no head chunk scripts in either
+   * mode (the bootstrap conversion does apply in dev). Trades and upstream
+   * limits are documented in src/ssr/preinit-client-references.ts.
+   *
+   * Wired in the generated virtual SSR entry
+   * (`src/ssr/preinit-client-references.ts` has the mechanism); apps with a
+   * custom SSR entry choose per-handler via `SSRDependencies.headScripts` and
+   * `installClientReferencePreinit`.
+   *
+   * @default "preinit"
+   */
+  headScripts?: HeadScriptsOption;
+
   /**
    * Filter which files route discovery scans, by glob. Paths are matched
    * root-relative (e.g. `src/routes/**`). `include` restricts discovery to

package/src/vite/plugins/version-plugin.ts

@@ -142,6 +142,14 @@ export function createVersionPlugin(): Plugin {
     name: "@rangojs/router:version",
     enforce: "pre",
 
+    // The build-time shell capture phase (producer B, #699) stamps entries
+    // with THIS instance's version — the value folded into the shipped worker
+    // — never the discovery temp server's own version-plugin value (a
+    // different Date.now() stamp that would fail the serve-side gate).
+    api: {
+      getBuildVersion: (): string => currentVersion,
+    },
+
     configResolved(config) {
       isDev = config.command === "serve";
       resolvedCacheDir = config.cacheDir

package/src/vite/plugins/virtual-entries.ts

@@ -1,3 +1,5 @@
+import type { HeadScriptsOption } from "../plugin-types.js";
+
 export const VIRTUAL_ENTRY_BROWSER: string = `
 import {
   createFromReadableStream,
@@ -36,21 +38,49 @@ async function initializeApp() {
 initializeApp().catch(console.error);
 `.trim();
 
-export const VIRTUAL_ENTRY_SSR: string = `
-import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
+/**
+ * Generate the virtual SSR entry. `headScripts` mirrors the rango() plugin
+ * option: "preinit" (default) installs the client-reference preinit hook and
+ * lets the SSR handlers convert the bootstrap to `bootstrapModules`;
+ * "preload" omits the hook and pins the handlers to the hint-only strategy.
+ */
+export function getVirtualEntrySSR(
+  headScripts: HeadScriptsOption = "preinit",
+): string {
+  const preinit = headScripts !== "preload";
+  // The preload variant drops exactly three preinit-only lines, all built
+  // here so the template below stays a single unconditional shape.
+  const depsImportNames = preinit
+    ? "createFromReadableStream,\n  setOnClientReference,"
+    : "createFromReadableStream,";
+  const ssrImportNames = preinit ? "\n  installClientReferencePreinit," : "";
+  const install = preinit
+    ? `
+// Upgrade client-reference modulepreload hints to executing module scripts in
+// the document head, for every render pass (live SSR, shell capture, resume).
+// See src/ssr/preinit-client-references.ts for the full rationale.
+installClientReferencePreinit(setOnClientReference);
+`
+    : "";
+  const hs = JSON.stringify(headScripts);
+  return `
+import {
+  ${depsImportNames}
+} from "@rangojs/router/internal/deps/ssr";
 import { renderToReadableStream, resume } from "react-dom/server.edge";
 import { prerender } from "react-dom/static.edge";
 import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
 import {
   createSSRHandler,
   createShellCaptureHandler,
-  createShellResumeHandler,
+  createShellResumeHandler,${ssrImportNames}
 } from "@rangojs/router/ssr";
-
+${install}
 export const renderHTML = createSSRHandler({
   createFromReadableStream,
   renderToReadableStream,
   injectRSCPayload,
+  headScripts: ${hs},
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
@@ -61,6 +91,7 @@ export const captureShellHTML = createShellCaptureHandler({
   injectRSCPayload,
   prerender,
   resume,
+  headScripts: ${hs},
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
@@ -71,10 +102,12 @@ export const resumeShellHTML = createShellResumeHandler({
   injectRSCPayload,
   prerender,
   resume,
+  headScripts: ${hs},
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
 `.trim();
+}
 
 /**
  * Virtual modules an RSC entry must import at startup to register the data the

package/src/vite/rango.ts

@@ -46,6 +46,31 @@ import { createRangoDebugger, NS } from "./debug.js";
 
 const debugConfig = createRangoDebugger(NS.config);
 
+/**
+ * Syntax target for the node/vercel server (`ssr` + `rsc`) build environments.
+ *
+ * Vite 8's build-target default is `baseline-widely-available`, which resolves
+ * to a BROWSER baseline (`chrome111`/`edge111`/…, ≈ES2022) and is applied
+ * per-environment with NO server carve-out: `resolveRolldownOptions` pipes it
+ * straight into rolldown/oxc's `transform.target` for `consumer:"server"` chunks
+ * too. So without an explicit server target our ssr/rsc bundles — which only run
+ * on Node or workerd — get compiled for browsers, needlessly rewriting modern
+ * syntax (e.g. Explicit Resource Management `using`/`await using`) into
+ * `_usingCtx()` runtime helpers. `esnext` emits server code at authored
+ * modernity: no helpers, marginally smaller/faster bundles, semantics that match
+ * reality. The `client` env is intentionally left at the browser baseline.
+ *
+ * The cloudflare preset does NOT use this: `@cloudflare/vite-plugin` hardcodes
+ * `es2024` on its server envs and its `config()` merges after ours, so anything
+ * we set there is a dead no-op (workerd runs es2024 fine).
+ *
+ * Caveat: `esnext` stops downleveling ERM `using`, which parses natively only on
+ * Node 24+ (workerd runs it). Ordinary ≤ES2022 server code still runs across the
+ * whole supported Node range; only an app that authors `using` AND deploys to
+ * Node < 24 would need to downlevel it itself. See issue #729.
+ */
+const SERVER_BUILD_TARGET = "esnext";
+
 // The leading-directive 'use client' sniff is shared with version-plugin's
 // getClientModuleSignature so the two cannot drift. Imported for local use by the
 // HMR transform below and re-exported because the E8 sniff test imports it from
@@ -239,7 +264,11 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       },
     });
 
-    plugins.push(createVirtualEntriesPlugin(finalEntries));
+    plugins.push(
+      createVirtualEntriesPlugin(finalEntries, undefined, {
+        headScripts: resolvedOptions.headScripts,
+      }),
+    );
     plugins.push(performanceTracksPlugin());
     plugins.push(
       rsc({
@@ -405,6 +434,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
             },
             ssr: {
               ...(vercelServerEnv ?? {}),
+              build: {
+                target: SERVER_BUILD_TARGET,
+              },
               optimizeDeps: {
                 entries: [VIRTUAL_IDS.ssr],
                 include: [
@@ -424,6 +456,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
             },
             rsc: {
               ...(vercelServerEnv ?? {}),
+              build: {
+                target: SERVER_BUILD_TARGET,
+              },
               optimizeDeps: {
                 entries: [VIRTUAL_IDS.rsc],
                 include: [
@@ -476,7 +511,11 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       },
     });
 
-    plugins.push(createVirtualEntriesPlugin(finalEntries, routerRef));
+    plugins.push(
+      createVirtualEntriesPlugin(finalEntries, routerRef, {
+        headScripts: resolvedOptions.headScripts,
+      }),
+    );
     plugins.push(performanceTracksPlugin());
     plugins.push(
       rsc({
@@ -536,6 +575,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       prerenderOnError: options?.prerender?.onError,
       discovery: options?.discovery,
       clientChunkCtx,
+      headScripts: resolvedOptions.headScripts,
     }),
   );