Merge pull request #223 from JoviDeCroock/JoviDeCroock/preload-client-entry-deps

Preload the client entry's static import closure

Author: JoviDeCroock

.changeset/preload-client-entry-deps.md

@@ -0,0 +1,7 @@
+---
+"@pracht/core": patch
+"@pracht/vite-plugin": patch
+"@pracht/cli": patch
+---
+
+Emit modulepreload links for the client entry's own static import closure. The client entry statically imports secondary chunks (shared runtime, preload helper), but generated HTML previously only preloaded shell/route chunks — so the browser discovered those imports only after downloading and parsing the entry, adding a serial round trip before hydration. The build now stores each entry's transitive static JS imports in the js manifest under its virtual module id, and both server-rendered and prerendered pages merge them into the page's modulepreload links. Islands pages preload the islands bootstrap's closure; `hydration: "none"` pages still emit no JS at all.

packages/cli/src/build-metadata.ts

@@ -89,20 +89,43 @@ export function readClientBuildAssets(root: string = process.cwd()): ClientBuild
     }
   }
 
+  const clientEntryJs = clientEntry
+    ? collectTransitiveDeps("virtual:pracht/client").js.map((file) => `/${file}`)
+    : [];
+  const islandsEntryJs = islandsEntry
+    ? collectTransitiveDeps("virtual:pracht/islands-client").js.map((file) => `/${file}`)
+    : [];
+
+  // Mirror @pracht/vite-plugin's readClientBuildAssets: expose each entry's
+  // static import closure (minus the entry file itself) under its virtual
+  // module id so prerendered pages get the same modulepreload links as
+  // server-rendered ones.
+  addEntryDeps(jsManifest, "virtual:pracht/client", clientEntry, clientEntryJs);
+  addEntryDeps(jsManifest, "virtual:pracht/islands-client", islandsEntry, islandsEntryJs);
+
   return {
     clientEntryUrl: clientEntry ? `/${clientEntry.file}` : null,
-    clientEntryJs: clientEntry
-      ? collectTransitiveDeps("virtual:pracht/client").js.map((file) => `/${file}`)
-      : [],
+    clientEntryJs,
     islandsEntryUrl: islandsEntry ? `/${islandsEntry.file}` : null,
-    islandsEntryJs: islandsEntry
-      ? collectTransitiveDeps("virtual:pracht/islands-client").js.map((file) => `/${file}`)
-      : [],
+    islandsEntryJs,
     cssManifest,
     jsManifest,
   };
 }
 
+function addEntryDeps(
+  jsManifest: Record<string, string[]>,
+  entryKey: string,
+  entry: ViteManifestEntry | undefined,
+  entryJs: string[],
+): void {
+  if (!entry) return;
+  const deps = entryJs.filter((url) => url !== `/${entry.file}`);
+  if (deps.length > 0) {
+    jsManifest[entryKey] = deps;
+  }
+}
+
 function stripPrachtClientModuleQuery(id: string): string {
   const queryStart = id.indexOf("?");
   if (queryStart === -1) return id;

packages/cli/test/pracht-cli.test.js

@@ -340,6 +340,7 @@ export const app = defineApp({
         jsManifest: {
           "src/routes/dashboard.tsx": ["/assets/dashboard.js", "/assets/vendor.js"],
           "src/shells/app.tsx": ["/assets/app.js", "/assets/vendor.js"],
+          "virtual:pracht/client": ["/assets/vendor.js"],
         },
       },
       mode: "manifest",

packages/framework/src/runtime-manifest.ts

@@ -1,5 +1,28 @@
 import type { ModuleImporter, ModuleRegistry } from "./types.ts";
 
+// Reserved jsManifest keys under which the build stores the transitive static
+// JS imports of the client/islands entry chunks. Without these, the browser
+// only discovers the entry's secondary chunks after downloading and parsing
+// the entry itself — one extra serial round trip before hydration. Must match
+// the virtual module ids in @pracht/vite-plugin (plugin-assets.ts).
+export const CLIENT_ENTRY_MANIFEST_KEY = "virtual:pracht/client";
+export const ISLANDS_ENTRY_MANIFEST_KEY = "virtual:pracht/islands-client";
+
+/**
+ * Merge an entry chunk's own static import urls into a page's modulepreload
+ * list. Entry deps come first — they gate hydration — and duplicates from the
+ * page's route/shell chunk closure are dropped.
+ */
+export function mergeEntryPreloadUrls(
+  jsManifest: Record<string, string[]> | undefined,
+  entryKey: string,
+  pageUrls: string[],
+): string[] {
+  const entryUrls = jsManifest?.[entryKey];
+  if (!entryUrls || entryUrls.length === 0) return pageUrls;
+  return [...new Set([...entryUrls, ...pageUrls])];
+}
+
 /** Strip leading `./` and `/` so all module paths share one canonical form. */
 export function normalizeModulePath(path: string): string {
   return path.replace(/^\.?\//, "");

packages/framework/src/runtime-response.ts

@@ -16,6 +16,9 @@ import {
 } from "./runtime-headers.ts";
 import { buildHtmlDocument, htmlResponse } from "./runtime-html.ts";
 import {
+  CLIENT_ENTRY_MANIFEST_KEY,
+  ISLANDS_ENTRY_MANIFEST_KEY,
+  mergeEntryPreloadUrls,
   resolveManifestEntries,
   resolvePageCssUrls,
   resolvePageJsUrls,
@@ -214,10 +217,10 @@ export async function renderRouteErrorResponse<TContext>(options: {
     options.shellFile,
     options.routeArgs.route.file,
   );
-  const modulePreloadUrls = resolvePageJsUrls(
+  const modulePreloadUrls = mergeEntryPreloadUrls(
     options.options.jsManifest,
-    options.shellFile,
-    options.routeArgs.route.file,
+    CLIENT_ENTRY_MANIFEST_KEY,
+    resolvePageJsUrls(options.options.jsManifest, options.shellFile, options.routeArgs.route.file),
   );
   const renderToString = await getRenderToStringAsync();
 
@@ -291,7 +294,11 @@ export async function renderRouteErrorResponse<TContext>(options: {
         body,
         clientEntryUrl: islandsEntryUrl,
         cssUrls,
-        modulePreloadUrls: [...islandPreloadUrls],
+        modulePreloadUrls: islandsEntryUrl
+          ? mergeEntryPreloadUrls(options.options.jsManifest, ISLANDS_ENTRY_MANIFEST_KEY, [
+              ...islandPreloadUrls,
+            ])
+          : [...islandPreloadUrls],
       }),
       routeErrorWithDiagnostics.status,
       documentHeaders,

packages/framework/src/runtime.ts

@@ -19,6 +19,9 @@ import {
   type IslandCapture,
 } from "./islands-server.ts";
 import {
+  CLIENT_ENTRY_MANIFEST_KEY,
+  ISLANDS_ENTRY_MANIFEST_KEY,
+  mergeEntryPreloadUrls,
   resolveManifestEntries,
   resolvePageCssUrls,
   resolvePageJsUrls,
@@ -456,10 +459,10 @@ export async function handlePrachtRequest<TContext>(
         match.route.shellFile,
         match.route.file,
       );
-      const modulePreloadUrls = resolvePageJsUrls(
+      const modulePreloadUrls = mergeEntryPreloadUrls(
         options.jsManifest,
-        match.route.shellFile,
-        match.route.file,
+        CLIENT_ENTRY_MANIFEST_KEY,
+        resolvePageJsUrls(options.jsManifest, match.route.shellFile, match.route.file),
       );
 
       if (match.route.render === "spa") {
@@ -600,7 +603,11 @@ export async function handlePrachtRequest<TContext>(
             body: ssrContent,
             clientEntryUrl: islandsEntryUrl,
             cssUrls,
-            modulePreloadUrls: [...islandPreloadUrls],
+            modulePreloadUrls: islandsEntryUrl
+              ? mergeEntryPreloadUrls(options.jsManifest, ISLANDS_ENTRY_MANIFEST_KEY, [
+                  ...islandPreloadUrls,
+                ])
+              : [...islandPreloadUrls],
             speculationRules: getAppSpeculationRules(resolvedApp),
           }),
           200,

packages/framework/test/runtime.test.ts

@@ -1174,6 +1174,47 @@ describe("prerenderApp", () => {
     expect(page.html).toContain('<link rel="modulepreload" href="/assets/vendor-abc123.js">');
   });
 
+  it("preloads the client entry's own static import closure without duplicates", async () => {
+    const app = defineApp({
+      routes: [route("/pricing", "./routes/pricing.tsx", { render: "ssg", shell: "public" })],
+      shells: {
+        public: "./shells/public.tsx",
+      },
+    });
+
+    const [page] = await prerenderApp({
+      app,
+      clientEntryUrl: "/assets/client-abc123.js",
+      jsManifest: {
+        "src/routes/pricing.tsx": ["/assets/pricing-abc123.js", "/assets/vendor-abc123.js"],
+        "src/shells/public.tsx": ["/assets/public-abc123.js", "/assets/vendor-abc123.js"],
+        "virtual:pracht/client": ["/assets/runtime-abc123.js", "/assets/vendor-abc123.js"],
+      },
+      registry: {
+        routeModules: {
+          "/src/routes/pricing.tsx": async () => ({
+            Component: ({ data }) => h("main", null, (data as { plan: string }).plan),
+            loader: async () => ({ plan: "MVP" }),
+          }),
+        },
+        shellModules: {
+          "/src/shells/public.tsx": async () => ({
+            Shell: ({ children }) => h("section", null, children),
+          }),
+        },
+      },
+    });
+
+    // The chunk the entry statically imports is preloaded even though no
+    // route/shell references it — the browser would otherwise discover it
+    // only after parsing the entry.
+    expect(page.html).toContain('<link rel="modulepreload" href="/assets/runtime-abc123.js">');
+    // Shared urls between the entry closure and route/shell chunks stay deduped.
+    expect(page.html.match(/href="\/assets\/vendor-abc123\.js"/g)).toHaveLength(1);
+    // The entry itself is loaded via <script src>, never preloaded.
+    expect(page.html).not.toContain('<link rel="modulepreload" href="/assets/client-abc123.js">');
+  });
+
   it("preserves document headers on prerendered pages", async () => {
     const app = defineApp({
       routes: [route("/pricing", "./routes/pricing.tsx", { render: "ssg", shell: "public" })],

packages/vite-plugin/src/plugin-assets.ts

@@ -53,6 +53,14 @@ export function readClientBuildAssets(root = process.cwd()): ClientBuildAssets {
     }
   }
 
+  // Store each entry's own static import closure under its virtual module id
+  // so the runtime can emit modulepreload links for chunks the browser would
+  // otherwise only discover after parsing the entry (@pracht/core reads these
+  // via CLIENT_ENTRY_MANIFEST_KEY / ISLANDS_ENTRY_MANIFEST_KEY). The entry
+  // file itself is excluded — it is already the page's <script src>.
+  addEntryDeps(manifest, jsManifest, PRACHT_CLIENT_MODULE_ID, clientEntry);
+  addEntryDeps(manifest, jsManifest, PRACHT_ISLANDS_CLIENT_MODULE_ID, islandsEntry);
+
   return {
     clientEntryUrl: clientEntry ? `/${clientEntry.file}` : null,
     islandsEntryUrl: islandsEntry ? `/${islandsEntry.file}` : null,
@@ -61,6 +69,19 @@ export function readClientBuildAssets(root = process.cwd()): ClientBuildAssets {
   };
 }
 
+function addEntryDeps(
+  manifest: Record<string, ViteManifestEntry>,
+  jsManifest: Record<string, string[]>,
+  entryKey: string,
+  entry: ViteManifestEntry | undefined,
+): void {
+  if (!entry) return;
+  const deps = collectTransitiveDeps(manifest, entryKey).js.filter((file) => file !== entry.file);
+  if (deps.length > 0) {
+    jsManifest[entryKey] = deps.map((file) => `/${file}`);
+  }
+}
+
 // Walk static imports transitively (not dynamicImports — those belong to
 // other shells/routes loaded separately). Returns both CSS and JS deps.
 function collectTransitiveDeps(