@moku-labs/web 2.4.11 → 2.4.12

package/dist/index.cjs

@@ -2299,7 +2299,8 @@ const headPlugin = createPlugin$1("head", {
 /**
 * @file build phase 1 — bundle. Runs `Bun.build` for CSS and JS separately into
 * outDir (honoring `config.minify`) with content-hashed output naming; caches the
-* fingerprinted asset paths for the pages phase and the complete output list for
+* fingerprinted asset paths for the pages phase, the chunks the JS entry imports
+* statically (for `<link rel="modulepreload">`), and the complete output list for
 * the cache-headers phase.
 */
 /** Conventional CSS entry candidates (project-relative). */
@@ -2358,10 +2359,11 @@ const CSS_EXTERNAL_FONT_GLOBS = [
 * @param options.naming.asset - Naming template for additional emitted assets.
 * @param options.external - Import/url() globs left unresolved in the output.
 * @param options.define - Global names replaced with constant expressions.
+* @param options.metafile - Whether to return the build metafile.
 * @returns The structural build result.
 * @example
 * ```ts
-* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser", naming: FINGERPRINT_NAMING, external: [], define: {} });
+* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser", naming: FINGERPRINT_NAMING, external: [], define: {}, metafile: false });
 * ```
 */
 async function defaultRunner(options) {
@@ -2456,6 +2458,73 @@ function normalizeAssetPath(absolutePath, outDir) {
 	return node_path$1.default.relative(node_path$1.default.resolve(outDir), node_path$1.default.resolve(absolutePath)).split(node_path$1.default.sep).join("/");
 }
 /**
+* Parse the runner's metafile into the structural view (object or JSON string).
+*
+* @param metafile - The metafile as the runner returned it (possibly absent).
+* @returns The parsed metafile, or `undefined` when absent or unreadable.
+* @example
+* ```ts
+* parseMetafile('{"outputs":{}}'); // { outputs: {} }
+* ```
+*/
+function parseMetafile(metafile) {
+	if (typeof metafile !== "string") return metafile;
+	try {
+		return JSON.parse(metafile);
+	} catch {
+		return;
+	}
+}
+/**
+* Normalize an outdir-relative output path into one graph key ("./a.js" and "a.js"
+* are the same file; Windows separators become "/").
+*
+* @param file - An outdir-relative output path.
+* @returns The normalized POSIX key.
+* @example
+* ```ts
+* toKey("./chunk-1.js"); // "chunk-1.js"
+* ```
+*/
+function toKey(file) {
+	return node_path$1.default.posix.normalize(file.split(node_path$1.default.sep).join("/"));
+}
+/**
+* Collect the chunks the JS entry points import STATICALLY, transitively, from the
+* metafile import graph. Only `import-statement` edges are followed: a chunk reached
+* only through a dynamic `import()` stays lazy and is never preloaded. These are the
+* files the browser would otherwise discover only after the entry finished
+* downloading (a request waterfall); the pages phase emits one
+* `<link rel="modulepreload">` per path so they load in parallel with the entry.
+* The walk starts from the `entry-point` artifacts, not from the metafile: Bun also
+* tags each lazy chunk with an `entryPoint`, and a lazy chunk may import the entry.
+*
+* @param result - The JS pass result (artifacts + metafile; no metafile → no preloads).
+* @param outdir - The bundler output directory the metafile paths are relative to.
+* @param outDir - The publish root the web paths are made relative to.
+* @returns The publish-root-relative paths of the static chunks (entries excluded).
+* @example
+* ```ts
+* staticEntryChunks(result, "dist/assets", "dist"); // ["assets/chunk-9f8e.js"]
+* ```
+*/
+function staticEntryChunks(result, outdir, outDir) {
+	const metafile = parseMetafile(result.metafile);
+	if (!metafile) return [];
+	const graph = new Map(Object.entries(metafile.outputs).map(([file, output]) => [toKey(file), (output.imports ?? []).filter((edge) => edge.kind === "import-statement").map((edge) => toKey(edge.path))]));
+	const entries = result.outputs.filter((output) => output.kind === "entry-point" && output.path.endsWith(".js")).map((output) => toKey(node_path$1.default.relative(node_path$1.default.resolve(outdir), node_path$1.default.resolve(output.path))));
+	const seen = new Set(entries);
+	const queue = [...entries];
+	const chunks = [];
+	for (let file = queue.shift(); file !== void 0; file = queue.shift()) for (const target of graph.get(file) ?? []) {
+		if (seen.has(target)) continue;
+		seen.add(target);
+		queue.push(target);
+		chunks.push(normalizeAssetPath(node_path$1.default.join(outdir, target), outDir));
+	}
+	return chunks;
+}
+/**
 * Run one bundler pass for a single asset kind and record the hashed output
 * paths under `state.buildCache` keyed by the original entry basename. Lazy
 * split chunks are emitted to disk but excluded from the recorded manifest
@@ -2484,7 +2553,8 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify, de
 		target: "browser",
 		naming: FINGERPRINT_NAMING,
 		external: kind === "css" ? [...CSS_EXTERNAL_FONT_GLOBS] : [],
-		define
+		define,
+		metafile: kind === "js"
 	});
 	if (!result.success) throw new Error(`[web] build.bundle ${kind} build failed`);
 	const hashed = {};
@@ -2494,6 +2564,7 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify, de
 	}
 	ctx.state.buildCache.set(kind, hashed);
 	ctx.state.buildCache.set(`${kind}:outputs`, result.outputs.map((output) => normalizeAssetPath(output.path, outDir)));
+	if (kind === "js") ctx.state.buildCache.set("js:preload", staticEntryChunks(result, outdir, outDir));
 	ctx.log.debug("build:bundle", {
 		kind,
 		count: result.outputs.length
@@ -2570,6 +2641,22 @@ function readBundleOutputs(ctx, kind) {
 	return Array.isArray(entry) ? entry : [];
 }
 /**
+* Read the chunks the JS entry imports statically (publish-root-relative web paths),
+* recorded by the bundle phase under `js:preload`. Dynamic-import-only chunks are
+* never in this list.
+*
+* @param ctx - Plugin context (provides `state`).
+* @returns The static chunk paths, or an empty array when absent.
+* @example
+* ```ts
+* readPreloads(ctx); // ["assets/chunk-9f8e.js"]
+* ```
+*/
+function readPreloads(ctx) {
+	const entry = ctx.state.buildCache.get("js:preload");
+	return Array.isArray(entry) ? entry : [];
+}
+/**
 * Render the stylesheet `<link>` tags for the fingerprinted CSS manifest.
 *
 * @param ctx - Plugin context (provides `state`).
@@ -2583,17 +2670,23 @@ function buildCssTags(ctx) {
 	return Object.values(readManifest(ctx, "css")).map((href) => `<link rel="stylesheet" href="/${href}">`).join("");
 }
 /**
-* Render the module `<script>` tags for the fingerprinted JS manifest.
+* Render the module `<script>` tags for the fingerprinted JS manifest, followed by
+* one `<link rel="modulepreload">` per chunk the entry imports statically. Without
+* the preloads the browser finds those chunks only after the entry has downloaded
+* and parsed, a request waterfall that delays hydration.
 *
 * @param ctx - Plugin context (provides `state`).
-* @returns The concatenated `<script type="module">` tags (possibly `""`).
+* @returns The concatenated `<script type="module">` and modulepreload tags (possibly `""`).
 * @example
 * ```ts
-* buildJsTags(ctx); // '<script type="module" src="/assets/spa-abc123.js"><\/script>'
+* buildJsTags(ctx);
+* // '<script type="module" src="/assets/spa-abc123.js"><\/script><link rel="modulepreload" href="/assets/chunk-9f8e.js">'
 * ```
 */
 function buildJsTags(ctx) {
-	return Object.values(readManifest(ctx, "js")).map((src) => `<script type="module" src="/${src}"><\/script>`).join("");
+	const scripts = Object.values(readManifest(ctx, "js")).map((src) => `<script type="module" src="/${src}"><\/script>`).join("");
+	if (scripts === "") return "";
+	return scripts + readPreloads(ctx).map((href) => `<link rel="modulepreload" href="/${href}">`).join("");
 }
 /**
 * Build the asset tag block from the fingerprinted manifests — both kinds by

package/dist/index.mjs

@@ -2255,7 +2255,8 @@ const headPlugin = createPlugin$1("head", {
 /**
 * @file build phase 1 — bundle. Runs `Bun.build` for CSS and JS separately into
 * outDir (honoring `config.minify`) with content-hashed output naming; caches the
-* fingerprinted asset paths for the pages phase and the complete output list for
+* fingerprinted asset paths for the pages phase, the chunks the JS entry imports
+* statically (for `<link rel="modulepreload">`), and the complete output list for
 * the cache-headers phase.
 */
 /** Conventional CSS entry candidates (project-relative). */
@@ -2314,10 +2315,11 @@ const CSS_EXTERNAL_FONT_GLOBS = [
 * @param options.naming.asset - Naming template for additional emitted assets.
 * @param options.external - Import/url() globs left unresolved in the output.
 * @param options.define - Global names replaced with constant expressions.
+* @param options.metafile - Whether to return the build metafile.
 * @returns The structural build result.
 * @example
 * ```ts
-* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser", naming: FINGERPRINT_NAMING, external: [], define: {} });
+* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser", naming: FINGERPRINT_NAMING, external: [], define: {}, metafile: false });
 * ```
 */
 async function defaultRunner(options) {
@@ -2412,6 +2414,73 @@ function normalizeAssetPath(absolutePath, outDir) {
 	return path.relative(path.resolve(outDir), path.resolve(absolutePath)).split(path.sep).join("/");
 }
 /**
+* Parse the runner's metafile into the structural view (object or JSON string).
+*
+* @param metafile - The metafile as the runner returned it (possibly absent).
+* @returns The parsed metafile, or `undefined` when absent or unreadable.
+* @example
+* ```ts
+* parseMetafile('{"outputs":{}}'); // { outputs: {} }
+* ```
+*/
+function parseMetafile(metafile) {
+	if (typeof metafile !== "string") return metafile;
+	try {
+		return JSON.parse(metafile);
+	} catch {
+		return;
+	}
+}
+/**
+* Normalize an outdir-relative output path into one graph key ("./a.js" and "a.js"
+* are the same file; Windows separators become "/").
+*
+* @param file - An outdir-relative output path.
+* @returns The normalized POSIX key.
+* @example
+* ```ts
+* toKey("./chunk-1.js"); // "chunk-1.js"
+* ```
+*/
+function toKey(file) {
+	return path.posix.normalize(file.split(path.sep).join("/"));
+}
+/**
+* Collect the chunks the JS entry points import STATICALLY, transitively, from the
+* metafile import graph. Only `import-statement` edges are followed: a chunk reached
+* only through a dynamic `import()` stays lazy and is never preloaded. These are the
+* files the browser would otherwise discover only after the entry finished
+* downloading (a request waterfall); the pages phase emits one
+* `<link rel="modulepreload">` per path so they load in parallel with the entry.
+* The walk starts from the `entry-point` artifacts, not from the metafile: Bun also
+* tags each lazy chunk with an `entryPoint`, and a lazy chunk may import the entry.
+*
+* @param result - The JS pass result (artifacts + metafile; no metafile → no preloads).
+* @param outdir - The bundler output directory the metafile paths are relative to.
+* @param outDir - The publish root the web paths are made relative to.
+* @returns The publish-root-relative paths of the static chunks (entries excluded).
+* @example
+* ```ts
+* staticEntryChunks(result, "dist/assets", "dist"); // ["assets/chunk-9f8e.js"]
+* ```
+*/
+function staticEntryChunks(result, outdir, outDir) {
+	const metafile = parseMetafile(result.metafile);
+	if (!metafile) return [];
+	const graph = new Map(Object.entries(metafile.outputs).map(([file, output]) => [toKey(file), (output.imports ?? []).filter((edge) => edge.kind === "import-statement").map((edge) => toKey(edge.path))]));
+	const entries = result.outputs.filter((output) => output.kind === "entry-point" && output.path.endsWith(".js")).map((output) => toKey(path.relative(path.resolve(outdir), path.resolve(output.path))));
+	const seen = new Set(entries);
+	const queue = [...entries];
+	const chunks = [];
+	for (let file = queue.shift(); file !== void 0; file = queue.shift()) for (const target of graph.get(file) ?? []) {
+		if (seen.has(target)) continue;
+		seen.add(target);
+		queue.push(target);
+		chunks.push(normalizeAssetPath(path.join(outdir, target), outDir));
+	}
+	return chunks;
+}
+/**
 * Run one bundler pass for a single asset kind and record the hashed output
 * paths under `state.buildCache` keyed by the original entry basename. Lazy
 * split chunks are emitted to disk but excluded from the recorded manifest
@@ -2440,7 +2509,8 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify, de
 		target: "browser",
 		naming: FINGERPRINT_NAMING,
 		external: kind === "css" ? [...CSS_EXTERNAL_FONT_GLOBS] : [],
-		define
+		define,
+		metafile: kind === "js"
 	});
 	if (!result.success) throw new Error(`[web] build.bundle ${kind} build failed`);
 	const hashed = {};
@@ -2450,6 +2520,7 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify, de
 	}
 	ctx.state.buildCache.set(kind, hashed);
 	ctx.state.buildCache.set(`${kind}:outputs`, result.outputs.map((output) => normalizeAssetPath(output.path, outDir)));
+	if (kind === "js") ctx.state.buildCache.set("js:preload", staticEntryChunks(result, outdir, outDir));
 	ctx.log.debug("build:bundle", {
 		kind,
 		count: result.outputs.length
@@ -2526,6 +2597,22 @@ function readBundleOutputs(ctx, kind) {
 	return Array.isArray(entry) ? entry : [];
 }
 /**
+* Read the chunks the JS entry imports statically (publish-root-relative web paths),
+* recorded by the bundle phase under `js:preload`. Dynamic-import-only chunks are
+* never in this list.
+*
+* @param ctx - Plugin context (provides `state`).
+* @returns The static chunk paths, or an empty array when absent.
+* @example
+* ```ts
+* readPreloads(ctx); // ["assets/chunk-9f8e.js"]
+* ```
+*/
+function readPreloads(ctx) {
+	const entry = ctx.state.buildCache.get("js:preload");
+	return Array.isArray(entry) ? entry : [];
+}
+/**
 * Render the stylesheet `<link>` tags for the fingerprinted CSS manifest.
 *
 * @param ctx - Plugin context (provides `state`).
@@ -2539,17 +2626,23 @@ function buildCssTags(ctx) {
 	return Object.values(readManifest(ctx, "css")).map((href) => `<link rel="stylesheet" href="/${href}">`).join("");
 }
 /**
-* Render the module `<script>` tags for the fingerprinted JS manifest.
+* Render the module `<script>` tags for the fingerprinted JS manifest, followed by
+* one `<link rel="modulepreload">` per chunk the entry imports statically. Without
+* the preloads the browser finds those chunks only after the entry has downloaded
+* and parsed, a request waterfall that delays hydration.
 *
 * @param ctx - Plugin context (provides `state`).
-* @returns The concatenated `<script type="module">` tags (possibly `""`).
+* @returns The concatenated `<script type="module">` and modulepreload tags (possibly `""`).
 * @example
 * ```ts
-* buildJsTags(ctx); // '<script type="module" src="/assets/spa-abc123.js"><\/script>'
+* buildJsTags(ctx);
+* // '<script type="module" src="/assets/spa-abc123.js"><\/script><link rel="modulepreload" href="/assets/chunk-9f8e.js">'
 * ```
 */
 function buildJsTags(ctx) {
-	return Object.values(readManifest(ctx, "js")).map((src) => `<script type="module" src="/${src}"><\/script>`).join("");
+	const scripts = Object.values(readManifest(ctx, "js")).map((src) => `<script type="module" src="/${src}"><\/script>`).join("");
+	if (scripts === "") return "";
+	return scripts + readPreloads(ctx).map((href) => `<link rel="modulepreload" href="/${href}">`).join("");
 }
 /**
 * Build the asset tag block from the fingerprinted manifests — both kinds by

package/package.json

@@ -139,5 +139,5 @@
     "typescript-eslint": "8.58.0",
     "vitest": "4.0.18"
   },
-  "version": "2.4.11"
+  "version": "2.4.12"
 }