fix(build): keep staged prerender artifacts canonical

Author: james-elicx

packages/vinext/src/build/inject-pregenerated-paths.ts

@@ -2,25 +2,17 @@ import fs from "node:fs";
 import path from "pathslash";
 import { readPrerenderManifest } from "../server/prerender-manifest.js";
 import { PREGENERATED_CONCRETE_PATHS_MODULE } from "../server/pregenerated-concrete-paths.js";
-import { escapeRegExp } from "../utils/regex.js";
 
 declare global {
   var __VINEXT_PREGENERATED_CONCRETE_PATHS: unknown;
 }
 
-const VINEXT_PREGEN_START = "/* __VINEXT_PREGENERATED_CONCRETE_PATHS_START__ */";
-const VINEXT_PREGEN_END = "/* __VINEXT_PREGENERATED_CONCRETE_PATHS_END__ */";
-const VINEXT_PREGEN_RE = new RegExp(
-  `${escapeRegExp(VINEXT_PREGEN_START)}[\\s\\S]*?${escapeRegExp(VINEXT_PREGEN_END)}\\n?`,
-  "g",
-);
-
 export function injectPregeneratedConcretePaths(
   root: string,
-  workerEntry = path.resolve(root, "dist", "server", "index.js"),
+  applicationEntry = path.resolve(root, "dist", "server", "index.js"),
   serverOutputDir = path.resolve(root, "dist", "server"),
+  additionalRuntimeDirs: readonly string[] = [],
 ): void {
-  const runtimeDir = path.dirname(workerEntry);
   const manifest = readPrerenderManifest(path.join(serverOutputDir, "vinext-prerender.json"));
   const table = manifest?.pregeneratedConcretePaths ?? [];
 
@@ -34,29 +26,18 @@ export function injectPregeneratedConcretePaths(
     table.length > 0
       ? `globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS = ${JSON.stringify(table)};\n`
       : "delete globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS;\n";
-  for (const outputDir of new Set([serverOutputDir, runtimeDir])) {
+  for (const outputDir of new Set([
+    serverOutputDir,
+    path.dirname(applicationEntry),
+    ...additionalRuntimeDirs,
+  ])) {
     fs.mkdirSync(outputDir, { recursive: true });
     fs.writeFileSync(path.join(outputDir, PREGENERATED_CONCRETE_PATHS_MODULE), runtimeModuleCode);
   }
 
-  if (!fs.existsSync(workerEntry)) {
-    if (table.length > 0) globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS = table;
-    else delete globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS;
-    return;
-  }
-
-  let code = fs.readFileSync(workerEntry, "utf-8").replace(VINEXT_PREGEN_RE, "");
-
   if (table.length > 0) {
     globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS = table;
-    code =
-      `${VINEXT_PREGEN_START}\n` +
-      `globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS = ${JSON.stringify(table)};\n` +
-      `${VINEXT_PREGEN_END}\n` +
-      code;
   } else {
     delete globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS;
   }
-
-  fs.writeFileSync(workerEntry, code);
 }

packages/vinext/src/build/prerender.ts

@@ -275,6 +275,11 @@ type PrerenderAppOptions = {
    * to the RSC entry's directory for compatibility with standalone callers.
    */
   serverDir?: string;
+  /**
+   * Root of the complete production build passed to the local prerender
+   * server. Defaults to the parent of `serverDir` for standalone callers.
+   */
+  buildOutDir?: string;
 } & PrerenderOptions;
 
 // ─── Internal option extensions ───────────────────────────────────────────────
@@ -1076,6 +1081,7 @@ export async function prerenderApp({
   mode,
   rscBundlePath,
   serverDir = path.dirname(rscBundlePath),
+  buildOutDir = path.dirname(serverDir),
   ...options
 }: PrerenderAppOptionsInternal): Promise<PrerenderResult> {
   const manifestDir = options.manifestDir ?? outDir;
@@ -1130,7 +1136,7 @@ export async function prerenderApp({
           const srv = await startProdServer({
             port: 0,
             host: "127.0.0.1",
-            outDir: path.dirname(serverDir),
+            outDir: buildOutDir,
             rscEntryPath: rscBundlePath,
             serverDir,
             noCompression: true,
@@ -1806,7 +1812,7 @@ export async function prerenderApp({
       const poolSize = resolvePrerenderPoolSize(urlsToRender.length, concurrency);
       if (poolSize > 1) {
         renderPool = await startOptionalPrerenderServerPool(
-          path.dirname(serverDir),
+          buildOutDir,
           poolSize,
           rscBundlePath,
           serverDir,

packages/vinext/src/build/run-prerender.ts

@@ -167,20 +167,24 @@ export async function runPrerender(options: RunPrerenderOptions): Promise<Preren
 
   if (!appDir && !pagesDir) return null;
 
-  // The manifest lands in dist/server/ alongside the server bundle so it's
-  // cleaned with the rest of vinext's build output on rebuild and co-located
-  // with server artifacts.
-  const manifestDir = path.resolve(
+  // Framework manifests and prerendered routes have one canonical location,
+  // independent of where an adapter asks Vite to emit the executable RSC
+  // graph. Consumers such as cache prewarming always resolve these artifacts
+  // from dist/server.
+  const manifestDir = path.resolve(root, "dist", "server");
+  const buildOutDir = path.resolve(root, "dist");
+  const configuredRscServerDir = path.resolve(
     root,
     options.routeRootConfig?.rscOutDir ?? path.join("dist", "server"),
   );
-  const rscBundlePath = options.rscBundlePath ?? resolveBuiltRscEntryPath(manifestDir);
-  // The emitted entry may live below dist/server (for example entries/app.js).
-  // Build metadata and prerender artifacts remain rooted at dist/server.
-  const relativeEntryPath = path.relative(manifestDir, rscBundlePath);
+  const rscBundlePath = options.rscBundlePath ?? resolveBuiltRscEntryPath(configuredRscServerDir);
+  // The emitted entry may live below its server root (for example
+  // entries/app.js). Keep adjacent build metadata rooted at the configured
+  // RSC output while resolving an explicit external entry from its own folder.
+  const relativeEntryPath = path.relative(configuredRscServerDir, rscBundlePath);
   const serverDir =
     !relativeEntryPath.startsWith("../") && !path.isAbsolute(relativeEntryPath)
-      ? manifestDir
+      ? configuredRscServerDir
       : path.dirname(rscBundlePath);
 
   const config = options.nextConfig
@@ -247,7 +251,7 @@ export async function runPrerender(options: RunPrerenderOptions): Promise<Preren
       sharedProdServer = await startProdServer({
         port: 0,
         host: "127.0.0.1",
-        outDir: path.dirname(serverDir),
+        outDir: buildOutDir,
         rscEntryPath: rscBundlePath,
         serverDir,
         noCompression: true,
@@ -278,6 +282,7 @@ export async function runPrerender(options: RunPrerenderOptions): Promise<Preren
         concurrency: options.concurrency,
         rscBundlePath,
         serverDir,
+        buildOutDir,
         // For hybrid builds pass the shared prod server via internal field.
         // prerenderApp will use it instead of starting its own.
         ...(sharedProdServer ? { _prodServer: sharedProdServer } : {}),
@@ -388,7 +393,7 @@ export async function runPrerender(options: RunPrerenderOptions): Promise<Preren
     );
   }
 
-  injectPregeneratedConcretePaths(root, rscBundlePath, manifestDir);
+  injectPregeneratedConcretePaths(root, rscBundlePath, manifestDir, [configuredRscServerDir]);
   if (fs.existsSync(rscBundlePath)) {
     rememberCurrentServerEntryImportMtime(rscBundlePath);
   }

packages/vinext/src/index.ts

@@ -7094,16 +7094,14 @@ export const loadServerActionClient = ${
           const source = JSON.stringify(manifest);
           fs.writeFileSync(path.join(outDir, "vinext-server.json"), source);
 
-          // Staged discovery and cacheability probing deliberately read build
-          // metadata from the platform-independent server directory. A Pages
-          // Worker bundle may live in a platform-named output directory, so
-          // retain the adjacent copy above and also publish the canonical copy.
-          if (!hasAppDir) {
-            const canonicalServerDir = path.join(root, "dist", "server");
-            if (path.resolve(outDir) !== canonicalServerDir) {
-              fs.mkdirSync(canonicalServerDir, { recursive: true });
-              fs.writeFileSync(path.join(canonicalServerDir, "vinext-server.json"), source);
-            }
+          // Post-build discovery deliberately reads metadata from the
+          // platform-independent server directory. An adapter may emit either
+          // router's executable graph elsewhere, so retain the adjacent copy
+          // above and also publish the canonical copy.
+          const canonicalServerDir = path.join(root, "dist", "server");
+          if (path.resolve(outDir) !== canonicalServerDir) {
+            fs.mkdirSync(canonicalServerDir, { recursive: true });
+            fs.writeFileSync(path.join(canonicalServerDir, "vinext-server.json"), source);
           }
         },
       },

tests/client-assets-build.test.ts

@@ -76,6 +76,14 @@ describe("client asset sidecar builds", () => {
 
       const rscEntry = await fs.readFile(path.join(rscOutDir, "index.js"), "utf8");
       expect(rscEntry).toContain("./vinext-client-assets.js");
+
+      const adjacentServerManifest = await fs.readFile(
+        path.join(rscOutDir, "vinext-server.json"),
+        "utf8",
+      );
+      expect(
+        await fs.readFile(path.join(fixtureRoot, "dist/server/vinext-server.json"), "utf8"),
+      ).toBe(adjacentServerManifest);
     } finally {
       await fs.rm(fixtureRoot, { recursive: true, force: true });
       await fs.rm(outRoot, { recursive: true, force: true });

tests/inject-pregenerated-paths.test.ts

@@ -29,16 +29,20 @@ afterEach(() => {
 });
 
 describe("injectPregeneratedConcretePaths", () => {
-  it("replaces an earlier injection", () => {
-    writeFile("dist/server/index.js", 'import { handler } from "vinext/server/fetch-handler";\n');
+  it("updates the sidecar without rewriting the built entry or its sourcemap", () => {
+    const entry = 'import { handler } from "vinext/server/fetch-handler";\n';
+    const sourceMap = '{"version":3,"sources":["entry.ts"]}\n';
+    writeFile("dist/server/index-a1b2.js", entry);
+    writeFile("dist/server/index-a1b2.js.map", sourceMap);
     writeFile(
       "dist/server/vinext-prerender.json",
       JSON.stringify({
         buildId: "build-a",
         pregeneratedConcretePaths: [["/blog/:slug", ["/blog/post-a"]]],
       }),
     );
-    injectPregeneratedConcretePaths(tmpDir);
+    const entryPath = path.join(tmpDir, "dist/server/index-a1b2.js");
+    injectPregeneratedConcretePaths(tmpDir, entryPath);
 
     writeFile(
       "dist/server/vinext-prerender.json",
@@ -47,31 +51,31 @@ describe("injectPregeneratedConcretePaths", () => {
         pregeneratedConcretePaths: [["/blog/:slug", ["/blog/post-b"]]],
       }),
     );
-    injectPregeneratedConcretePaths(tmpDir);
+    injectPregeneratedConcretePaths(tmpDir, entryPath);
 
-    const output = fs.readFileSync(path.join(tmpDir, "dist/server/index.js"), "utf-8");
-    expect(output).toContain("post-b");
-    expect(output).not.toContain("post-a");
-    expect(output).toContain('import { handler } from "vinext/server/fetch-handler"');
+    const runtimeTable = fs.readFileSync(
+      path.join(tmpDir, "dist/server", PREGENERATED_CONCRETE_PATHS_MODULE),
+      "utf-8",
+    );
+    expect(runtimeTable).toContain("post-b");
+    expect(runtimeTable).not.toContain("post-a");
+    expect(fs.readFileSync(entryPath, "utf-8")).toBe(entry);
+    expect(fs.readFileSync(`${entryPath}.map`, "utf-8")).toBe(sourceMap);
   });
 
-  it("strips an earlier injection when the manifest is missing", () => {
-    writeFile(
-      "dist/server/index.js",
-      [
-        "/* __VINEXT_PREGENERATED_CONCRETE_PATHS_START__ */",
-        'globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS = [["/blog/:slug",["/blog/post-a"]]];',
-        "/* __VINEXT_PREGENERATED_CONCRETE_PATHS_END__ */",
-        'import { handler } from "vinext/server/fetch-handler";',
-        "",
-      ].join("\n"),
-    );
+  it("clears the sidecar when the manifest is missing", () => {
+    const entry = 'import { handler } from "vinext/server/fetch-handler";\n';
+    writeFile("dist/server/index.js", entry);
 
     injectPregeneratedConcretePaths(tmpDir);
 
-    const output = fs.readFileSync(path.join(tmpDir, "dist/server/index.js"), "utf-8");
-    expect(output).not.toContain("__VINEXT_PREGENERATED_CONCRETE_PATHS");
-    expect(output).toContain('import { handler } from "vinext/server/fetch-handler"');
+    expect(
+      fs.readFileSync(
+        path.join(tmpDir, "dist/server", PREGENERATED_CONCRETE_PATHS_MODULE),
+        "utf-8",
+      ),
+    ).toBe("delete globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS;\n");
+    expect(fs.readFileSync(path.join(tmpDir, "dist/server/index.js"), "utf-8")).toBe(entry);
   });
 
   it("uses the concrete-path table stored in the prerender manifest", () => {
@@ -89,7 +93,10 @@ describe("injectPregeneratedConcretePaths", () => {
 
     injectPregeneratedConcretePaths(tmpDir);
 
-    const output = fs.readFileSync(path.join(tmpDir, "dist/server/index.js"), "utf-8");
+    const output = fs.readFileSync(
+      path.join(tmpDir, "dist/server", PREGENERATED_CONCRETE_PATHS_MODULE),
+      "utf-8",
+    );
     const match = output.match(/globalThis\.__VINEXT_PREGENERATED_CONCRETE_PATHS = (\[.*?\]);/);
     expect(match).not.toBeNull();
     expect(JSON.parse(match![1])).toEqual([["/blog/:slug", ["/blog/post-a"]]]);
@@ -100,16 +107,6 @@ describe("injectPregeneratedConcretePaths", () => {
 
   it("clears the current-process global when no concrete paths are available", () => {
     globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS = [["/old/:slug", ["/old/post"]]];
-    writeFile(
-      "dist/server/index.js",
-      [
-        "/* __VINEXT_PREGENERATED_CONCRETE_PATHS_START__ */",
-        'globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS = [["/old/:slug",["/old/post"]]];',
-        "/* __VINEXT_PREGENERATED_CONCRETE_PATHS_END__ */",
-        'export default { fetch() { return new Response("ok"); } };',
-        "",
-      ].join("\n"),
-    );
 
     injectPregeneratedConcretePaths(tmpDir);
 
@@ -123,6 +120,7 @@ describe("injectPregeneratedConcretePaths", () => {
     writeFile(
       "dist/server/index.js",
       [
+        `import "./${PREGENERATED_CONCRETE_PATHS_MODULE}";`,
         `import { getRenderedConcreteUrlPathsForRoute, initPregeneratedPathsFromGlobals } from ${JSON.stringify(registryModuleUrl)};`,
         "initPregeneratedPathsFromGlobals();",
         'export const renderedPaths = [...(getRenderedConcreteUrlPathsForRoute("/blog/:slug") ?? [])];',
@@ -180,9 +178,10 @@ describe("injectPregeneratedConcretePaths", () => {
     const registryModuleUrl = pathToFileURL(
       path.resolve("packages/vinext/src/server/pregenerated-concrete-paths.ts"),
     ).href;
-    const entryPath = path.join(tmpDir, "dist/custom-rsc/application-entry.js");
+    const rscServerDir = path.join(tmpDir, "dist/custom-rsc");
+    const entryPath = path.join(rscServerDir, "entries/application-entry.js");
     writeFile(
-      "dist/custom-rsc/application-entry.js",
+      "dist/custom-rsc/entries/application-entry.js",
       [
         `import "./${PREGENERATED_CONCRETE_PATHS_MODULE}";`,
         `import { getRenderedConcreteUrlPathsForRoute, initPregeneratedPathsFromGlobals } from ${JSON.stringify(registryModuleUrl)};`,
@@ -199,7 +198,9 @@ describe("injectPregeneratedConcretePaths", () => {
       }),
     );
 
-    injectPregeneratedConcretePaths(tmpDir, entryPath);
+    injectPregeneratedConcretePaths(tmpDir, entryPath, path.join(tmpDir, "dist/server"), [
+      rscServerDir,
+    ]);
 
     expect(
       fs.existsSync(path.join(path.dirname(entryPath), PREGENERATED_CONCRETE_PATHS_MODULE)),
@@ -210,31 +211,30 @@ describe("injectPregeneratedConcretePaths", () => {
         "utf-8",
       ),
     ).toContain("/blog/post-a");
+    expect(
+      fs.readFileSync(path.join(rscServerDir, PREGENERATED_CONCRETE_PATHS_MODULE), "utf-8"),
+    ).toContain("/blog/post-a");
     const applicationEntry: unknown = await import(
       `${pathToFileURL(entryPath).href}?t=${Date.now()}`
     );
     expect(applicationEntry).toMatchObject({ renderedPaths: ["/blog/post-a"] });
   });
 
-  it("strips an earlier injection when the manifest is corrupt", () => {
+  it("clears the sidecar without rewriting the entry when the manifest is corrupt", () => {
     const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-    writeFile(
-      "dist/server/index.js",
-      [
-        "/* __VINEXT_PREGENERATED_CONCRETE_PATHS_START__ */",
-        'globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS = [["/",["/"]]];',
-        "/* __VINEXT_PREGENERATED_CONCRETE_PATHS_END__ */",
-        'export default { fetch() { return new Response("ok"); } };',
-        "",
-      ].join("\n"),
-    );
+    const entry = 'export default { fetch() { return new Response("ok"); } };\n';
+    writeFile("dist/server/index.js", entry);
     writeFile("dist/server/vinext-prerender.json", "{invalid json}");
 
     injectPregeneratedConcretePaths(tmpDir);
 
-    const output = fs.readFileSync(path.join(tmpDir, "dist/server/index.js"), "utf-8");
-    expect(output).not.toContain("__VINEXT_PREGENERATED_CONCRETE_PATHS");
-    expect(output).toContain('export default { fetch() { return new Response("ok"); } }');
+    expect(
+      fs.readFileSync(
+        path.join(tmpDir, "dist/server", PREGENERATED_CONCRETE_PATHS_MODULE),
+        "utf-8",
+      ),
+    ).toBe("delete globalThis.__VINEXT_PREGENERATED_CONCRETE_PATHS;\n");
+    expect(fs.readFileSync(path.join(tmpDir, "dist/server/index.js"), "utf-8")).toBe(entry);
     expect(warnSpy).toHaveBeenCalledWith(
       expect.stringContaining("[vinext] Failed to read prerender manifest"),
       expect.any(SyntaxError),