vinext 1.2.1 → 1.3.1

package/dist/build/client-reference-async.d.ts

@@ -0,0 +1,48 @@
+//#region src/build/client-reference-async.d.ts
+type AsyncModuleGraphInfo = {
+  code: string | null;
+  importedIds: readonly string[];
+};
+/** A chunk of the emitted output, as `renderChunk`'s `meta.chunks` lists it. */
+export type EmittedChunk = {
+  fileName: string;
+  /** The chunks it imports statically, by file name, and its externals. */
+  imports: readonly string[];
+  /** Its modules, with their code after tree-shaking. */
+  modules: Readonly<Record<string, {
+    code: string | null;
+    renderedLength: number;
+  }>>;
+};
+/**
+ * Whether `code` awaits at the top level of the module: an `await`, a
+ * `for await` or an `await using` outside any function. Code that fails to
+ * parse counts as synchronous.
+ */
+export declare function hasTopLevelAwait(code: string): boolean;
+/**
+ * The `roots` whose evaluation is asynchronous in the emitted output: the
+ * module, or a module it imports at any depth, awaits at its top level. Webpack
+ * calls these async modules, and React's Flight client suspends on them as they
+ * load. Only what the output keeps counts: modules tree-shaking dropped don't
+ * make a module async. Neither do imports of a module in a chunk the
+ * importer's chunks never load, nor of one `declaresSideEffects` reports, which
+ * the output drops when unused. Other imports stay: the imported module's side
+ * effects, its await included, run before the importer.
+ */
+export declare function collectAsyncModules(options: {
+  roots: readonly string[];
+  getModuleInfo: (id: string) => AsyncModuleGraphInfo | null;
+  chunks: readonly EmittedChunk[];
+  declaresSideEffects?: (id: string) => boolean;
+}): Set<string>;
+/**
+ * Whether a module's package declares which of its modules have side effects
+ * (`sideEffects` other than `true` in the nearest package.json naming a
+ * package or declaring it). A bundler drops an unused import of a module the
+ * declaration marks side-effect-free, which Rolldown's module info doesn't
+ * report, so an import into such a package may not survive.
+ */
+export declare function createSideEffectsDeclarationCheck(): (id: string) => boolean;
+//#endregion
+export {};

package/dist/build/client-reference-async.js

@@ -0,0 +1,123 @@
+import path from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index.js";
+import { parseProgram, walkAst } from "../plugins/ast-utils.js";
+import fs from "node:fs";
+//#region src/build/client-reference-async.ts
+/**
+* Whether `code` awaits at the top level of the module: an `await`, a
+* `for await` or an `await using` outside any function. Code that fails to
+* parse counts as synchronous.
+*/
+function hasTopLevelAwait(code) {
+	if (!code.includes("await")) return false;
+	let program;
+	try {
+		program = parseProgram(code, { sourceType: "module" });
+	} catch {
+		return false;
+	}
+	let found = false;
+	walkAst(program, (node) => {
+		if (found) return false;
+		if (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression") return false;
+		if (node.type === "AwaitExpression") {
+			found = true;
+			return false;
+		}
+		if (node.type === "ForOfStatement" && node.await || node.type === "VariableDeclaration" && node.kind === "await using") found = true;
+	});
+	return found;
+}
+/**
+* The `roots` whose evaluation is asynchronous in the emitted output: the
+* module, or a module it imports at any depth, awaits at its top level. Webpack
+* calls these async modules, and React's Flight client suspends on them as they
+* load. Only what the output keeps counts: modules tree-shaking dropped don't
+* make a module async. Neither do imports of a module in a chunk the
+* importer's chunks never load, nor of one `declaresSideEffects` reports, which
+* the output drops when unused. Other imports stay: the imported module's side
+* effects, its await included, run before the importer.
+*/
+function collectAsyncModules(options) {
+	const chunkOf = /* @__PURE__ */ new Map();
+	for (const chunk of options.chunks) for (const [id, module] of Object.entries(chunk.modules)) if (module.renderedLength > 0) chunkOf.set(id, chunk);
+	const chunksByFile = new Map(options.chunks.map((chunk) => [chunk.fileName, chunk]));
+	const loadedChunks = /* @__PURE__ */ new Map();
+	const chunksLoadedWith = (chunk) => {
+		let files = loadedChunks.get(chunk);
+		if (files) return files;
+		files = /* @__PURE__ */ new Set([chunk.fileName]);
+		const queue = [chunk];
+		for (let index = 0; index < queue.length; index++) for (const file of queue[index].imports) {
+			const imported = chunksByFile.get(file);
+			if (!imported || files.has(file)) continue;
+			files.add(file);
+			queue.push(imported);
+		}
+		loadedChunks.set(chunk, files);
+		return files;
+	};
+	const importers = /* @__PURE__ */ new Map();
+	const awaiting = [];
+	const visited = /* @__PURE__ */ new Set();
+	const stack = options.roots.filter((id) => chunkOf.has(id));
+	while (stack.length > 0) {
+		const id = stack.pop();
+		if (visited.has(id)) continue;
+		visited.add(id);
+		const chunk = chunkOf.get(id);
+		const info = options.getModuleInfo(id);
+		const code = chunk.modules[id].code ?? info?.code ?? null;
+		if (code !== null && hasTopLevelAwait(code)) awaiting.push(id);
+		const loaded = chunksLoadedWith(chunk);
+		for (const imported of info?.importedIds ?? []) {
+			const importedChunk = chunkOf.get(imported);
+			if (!importedChunk || !loaded.has(importedChunk.fileName)) continue;
+			if (options.declaresSideEffects?.(imported)) continue;
+			let list = importers.get(imported);
+			if (!list) importers.set(imported, list = []);
+			list.push(id);
+			stack.push(imported);
+		}
+	}
+	const asyncModules = new Set(awaiting);
+	for (let index = 0; index < awaiting.length; index++) for (const importer of importers.get(awaiting[index]) ?? []) {
+		if (asyncModules.has(importer)) continue;
+		asyncModules.add(importer);
+		awaiting.push(importer);
+	}
+	return new Set(options.roots.filter((id) => asyncModules.has(id)));
+}
+/**
+* Whether a module's package declares which of its modules have side effects
+* (`sideEffects` other than `true` in the nearest package.json naming a
+* package or declaring it). A bundler drops an unused import of a module the
+* declaration marks side-effect-free, which Rolldown's module info doesn't
+* report, so an import into such a package may not survive.
+*/
+function createSideEffectsDeclarationCheck() {
+	const byDirectory = /* @__PURE__ */ new Map();
+	const declares = (directory) => {
+		const cached = byDirectory.get(directory);
+		if (cached !== void 0) return cached;
+		let pkg;
+		try {
+			pkg = JSON.parse(fs.readFileSync(path.join(directory, "package.json"), "utf8"));
+		} catch {
+			pkg = void 0;
+		}
+		let result;
+		if (pkg && typeof pkg === "object" && ("sideEffects" in pkg || "name" in pkg)) result = "sideEffects" in pkg && pkg.sideEffects !== true;
+		else {
+			const parent = path.dirname(directory);
+			result = parent !== directory && declares(parent);
+		}
+		byDirectory.set(directory, result);
+		return result;
+	};
+	return (id) => {
+		const file = id.split("?")[0];
+		return !id.startsWith("\0") && path.isAbsolute(file) && declares(path.dirname(file));
+	};
+}
+//#endregion
+export { collectAsyncModules, createSideEffectsDeclarationCheck, hasTopLevelAwait };

package/dist/build/client-reference-chunks.d.ts

@@ -0,0 +1,32 @@
+import { ClientReferenceChunks } from "../utils/client-reference-chunks.js";
+import { ResolvedConfig, Rollup } from "vite";
+//#region src/build/client-reference-chunks.d.ts
+/**
+ * Collect what each App Router client reference loads in the browser from the
+ * client bundle: the chunk holding the module that registers it (see
+ * plugins/rsc-client-reference-loaders.ts), and the JS chunks and stylesheets
+ * that chunk needs, as Vite's preload helper would load them for a dynamic
+ * import. JS chunks the App browser entry imports statically have loaded
+ * before any Flight row decodes, so they are left out.
+ *
+ * @param moduleKeys Client reference modules by resolved id, with the keys of
+ *   the references each registers.
+ * @param modulePreload The client build's `build.modulePreload`, which picks
+ *   the JS chunks to modulepreload, as it does for Vite's preload helper. Its
+ *   `resolveDependencies` sees the chunk that dynamically imports each
+ *   registering module as the host, as Vite passes it.
+ */
+export declare function collectClientReferenceChunks(bundle: Rollup.OutputBundle, moduleKeys: ReadonlyMap<string, readonly string[]>, appBrowserEntry: Rollup.OutputChunk | undefined, modulePreload?: ResolvedConfig["build"]["modulePreload"]): ClientReferenceChunks | undefined;
+/**
+ * Vite's build manifest keys a dynamic import by the module it imports, and
+ * next/dynamic's SSR preloads look up the module a boundary imports (see
+ * shims/dynamic-preload-chunks.tsx). The client build imports a client
+ * reference outside every group through the module that registers it, not
+ * the reference's own module, so map the reference's module to the chunk of
+ * the module that registers it, keyed as Vite keys a manifest entry.
+ *
+ * @param getImportedIds A module's static imports, as the bundler resolved
+ *   them.
+ */
+export declare function collectClientReferenceSources(bundle: Rollup.OutputBundle, getImportedIds: (moduleId: string) => readonly string[] | undefined, root: string): Record<string, string> | undefined;
+//#endregion

package/dist/build/client-reference-chunks.js

@@ -0,0 +1,111 @@
+import "../plugins/rsc-client-reference-loaders.js";
+import { toManifestModuleId } from "../plugins/dynamic-preload-metadata.js";
+//#region src/build/client-reference-chunks.ts
+/** As Vite's preload helper tells a stylesheet: by its URL's path. */
+function isStylesheet(file) {
+	return new URL(file, "http://vinext.local/").pathname.endsWith(".css");
+}
+/**
+* Collect what each App Router client reference loads in the browser from the
+* client bundle: the chunk holding the module that registers it (see
+* plugins/rsc-client-reference-loaders.ts), and the JS chunks and stylesheets
+* that chunk needs, as Vite's preload helper would load them for a dynamic
+* import. JS chunks the App browser entry imports statically have loaded
+* before any Flight row decodes, so they are left out.
+*
+* @param moduleKeys Client reference modules by resolved id, with the keys of
+*   the references each registers.
+* @param modulePreload The client build's `build.modulePreload`, which picks
+*   the JS chunks to modulepreload, as it does for Vite's preload helper. Its
+*   `resolveDependencies` sees the chunk that dynamically imports each
+*   registering module as the host, as Vite passes it.
+*/
+function collectClientReferenceChunks(bundle, moduleKeys, appBrowserEntry, modulePreload) {
+	const chunks = /* @__PURE__ */ new Map();
+	let host;
+	for (const output of Object.values(bundle)) {
+		if (output.type !== "chunk") continue;
+		chunks.set(output.fileName, output);
+		if (output.facadeModuleId === "\0virtual:vinext-client-reference-chunks") host = output;
+	}
+	const staticImports = (chunk) => {
+		const seen = /* @__PURE__ */ new Set([chunk.fileName]);
+		const order = [chunk];
+		for (let i = 0; i < order.length; i++) for (const file of order[i].imports) {
+			const imported = chunks.get(file);
+			if (!imported || seen.has(file)) continue;
+			seen.add(file);
+			order.push(imported);
+		}
+		return order;
+	};
+	const eager = new Set(appBrowserEntry ? staticImports(appBrowserEntry).map((chunk) => chunk.fileName) : []);
+	const result = {
+		references: {},
+		modules: []
+	};
+	for (const chunk of chunks.values()) {
+		const keys = chunk.moduleIds.flatMap((moduleId) => moduleKeys.get(moduleId) ?? []);
+		if (keys.length === 0) continue;
+		const imports = [];
+		const css = /* @__PURE__ */ new Set();
+		const visited = /* @__PURE__ */ new Set();
+		const addDeps = (loaded) => {
+			if (visited.has(loaded.fileName)) return;
+			visited.add(loaded.fileName);
+			if (loaded !== chunk) imports.push(loaded.fileName);
+			for (const file of loaded.imports) {
+				const imported = chunks.get(file);
+				if (imported) addDeps(imported);
+			}
+			for (const file of loaded.viteMetadata?.importedCss ?? []) css.add(file);
+		};
+		addDeps(chunk);
+		let preloads = imports.length + css.size > 0 ? [chunk.fileName, ...imports] : [];
+		let stylesheets = [...css];
+		if (modulePreload === false) preloads = [];
+		else if (modulePreload?.resolveDependencies && host) {
+			const resolved = modulePreload.resolveDependencies(chunk.fileName, preloads, {
+				hostId: host.fileName,
+				hostType: "js"
+			});
+			preloads = resolved.filter((file) => !isStylesheet(file));
+			stylesheets = [.../* @__PURE__ */ new Set([...resolved.filter(isStylesheet), ...css])];
+		}
+		preloads = [...new Set(preloads)].filter((file) => !eager.has(file) && (file !== chunk.fileName || stylesheets.length > 0));
+		const index = result.modules.push({
+			file: chunk.fileName,
+			imports: preloads,
+			css: stylesheets
+		}) - 1;
+		for (const key of keys) result.references[key] = index;
+	}
+	return result.modules.length > 0 ? result : void 0;
+}
+/**
+* Vite's build manifest keys a dynamic import by the module it imports, and
+* next/dynamic's SSR preloads look up the module a boundary imports (see
+* shims/dynamic-preload-chunks.tsx). The client build imports a client
+* reference outside every group through the module that registers it, not
+* the reference's own module, so map the reference's module to the chunk of
+* the module that registers it, keyed as Vite keys a manifest entry.
+*
+* @param getImportedIds A module's static imports, as the bundler resolved
+*   them.
+*/
+function collectClientReferenceSources(bundle, getImportedIds, root) {
+	const sources = {};
+	for (const output of Object.values(bundle)) {
+		if (output.type !== "chunk") continue;
+		for (const moduleId of output.moduleIds) {
+			if (!moduleId.startsWith("\0virtual:vinext-client-reference-module/")) continue;
+			const source = getImportedIds(moduleId)?.at(-1);
+			if (source === void 0 || source.startsWith("\0")) continue;
+			const key = toManifestModuleId(root, source);
+			if (key) sources[key] = output.fileName;
+		}
+	}
+	return Object.keys(sources).length > 0 ? sources : void 0;
+}
+//#endregion
+export { collectClientReferenceChunks, collectClientReferenceSources };

package/dist/build/client-reference-groups.d.ts

@@ -0,0 +1,171 @@
+import { actionOwnerRouteEntryIds } from "./action-owner-manifest.js";
+import { Rollup } from "vite";
+//#region src/build/client-reference-groups.d.ts
+/**
+ * Client references whose estimated group cost (see
+ * {@link measureClientReferenceGroupCosts}) is larger than this many
+ * transformed source bytes keep their own lazy chunk instead of joining a route
+ * group. Grouping makes every member load with the group, so a heavy component
+ * that a route can reach but rarely renders must not be pulled into that
+ * route's startup bundle.
+ */
+export declare const CLIENT_REFERENCE_GROUP_MAX_COST_BYTES: number;
+type ClientReferenceGroupRoute = Parameters<typeof actionOwnerRouteEntryIds>[0];
+type ModuleGraphInfo = Pick<Rollup.ModuleInfo, "dynamicallyImportedIds" | "importedIds">;
+/**
+ * Map each client reference reachable from App Router route files to a
+ * signature naming the owners that reach it. A route owns its page, layouts,
+ * templates, boundaries and parallel slots, which render with it. Intercepting
+ * routes (which only render on soft navigation), global-error and
+ * global-not-found render on their own, so each is owned by its file, named by
+ * its path relative to `root`. References with the same signature are needed
+ * together, mirroring Next.js' per-route client entries. The map is in the
+ * order a depth-first walk in import order first reaches each reference from
+ * the route files in render order, which follows ES module evaluation order.
+ *
+ * References reachable from no route file (for example vinext's internal
+ * runtime references) are omitted and keep their own lazy chunk. So are
+ * references that route code reaches through a dynamic import (`next/dynamic`,
+ * `React.lazy`), directly or through the dynamically imported module's graph.
+ */
+export declare function collectClientReferenceRouteSignatures(options: {
+  canonicalizeModuleId?: (id: string) => string;
+  clientReferenceIds: ReadonlySet<string>;
+  getModuleInfo: (id: string) => ModuleGraphInfo | null;
+  root: string;
+  routes: readonly ClientReferenceGroupRoute[];
+  sharedRoots?: readonly string[];
+}): Map<string, string>;
+export type ClientReferencePreloadPlan = {
+  /**
+   * Client references any render may use: those reached from outside route
+   * files (vinext's runtime, server actions), those of `alwaysRoots`
+   * (global-error, the root boundaries), and those no walk reaches.
+   */
+  always: string[];
+  /** The client references each route file reaches, through any import. */
+  files: string[][];
+  /** Each route pattern's files, as indices into `files`. */
+  routes: Map<string, number[]>;
+  /** The files of a render without a route, as indices into `files`. */
+  routeless: number[];
+  /**
+   * References route files reach only through static imports, outside
+   * `always`. A render may stream one whose module evaluates asynchronously
+   * instead of waiting for it; a reference any dynamic import reaches, such as
+   * a `next/dynamic` component, always loads first.
+   */
+  staticOnly: string[];
+};
+/**
+ * Plan which client references SSR loads before rendering each route. A route
+ * preloads every client reference its page, layouts, templates, boundaries and
+ * parallel slots reach, statically or through dynamic imports (a
+ * `next/dynamic` component renders on the server), plus the `always` set.
+ * Intercepting routes only render on soft navigation, which SSR never
+ * renders, so they add to no set. `entryIds` are the RSC graph's entries:
+ * walking them up to route files finds what renders outside any route.
+ */
+export declare function collectClientReferencePreloadPlan(options: {
+  alwaysRoots?: readonly string[];
+  canonicalizeModuleId?: (id: string) => string;
+  clientReferenceIds: ReadonlySet<string>;
+  entryIds: readonly string[];
+  getModuleInfo: (id: string) => ModuleGraphInfo | null;
+  routelessFiles?: readonly string[];
+  routes: readonly ClientReferenceGroupRoute[];
+}): ClientReferencePreloadPlan;
+/** Export names an importer uses from a module, or `"*"` for all of them. */
+type UsedNames = ReadonlySet<string> | "*";
+type ModuleBindings = {
+  /** Transformed source bytes, not counting import and export-list statements. */
+  bytes: number;
+  /** Static imports, with the names each one uses. */
+  imports: ReadonlyArray<{
+    id: string;
+    names: UsedNames;
+  }>;
+  /**
+   * Re-exports: `export { a as b } from`, `export * from` (`exportName` and
+   * `importName` are `"*"`), `export * as ns from` (`importName` is `"*"`), and
+   * imported bindings that the module only re-exports.
+   */
+  reexports: ReadonlyArray<{
+    id: string;
+    exportName: string;
+    importName: string;
+  }>;
+};
+type LoadedModule = {
+  code: string | null;
+  importedIds: readonly string[];
+  /**
+   * Without bindings, every static import of the module counts in full. With
+   * them, a side-effect-free module's re-exports only count for the names its
+   * importers use, as tree-shaking would keep them.
+   */
+  bindings?: ModuleBindings;
+};
+/**
+ * Read a module's static imports and re-exports for
+ * {@link measureClientReferenceGroupCosts}. Returns undefined when the code does
+ * not parse or a specifier does not resolve to one of `importedIds`.
+ */
+export declare function readClientModuleBindings(options: {
+  code: string;
+  importedIds: readonly string[];
+  resolve: (specifier: string) => Promise<string | null>;
+}): Promise<ModuleBindings | undefined>;
+/**
+ * Estimate, in transformed source bytes, how much code each client reference
+ * would add to a route group's chunk: the modules only it uses, plus the cost
+ * of every client reference it statically imports (grouping a reference pulls
+ * those along). Modules shared with other client references are not charged
+ * to any one of them, so shared libraries do not block grouping. With
+ * {@link readClientModuleBindings}, a side-effect-free module only charges the
+ * re-exports that are imported from it, so a reference that imports one icon
+ * from a barrel is not charged for the whole library.
+ *
+ * `references` maps each client reference id to its module id in the client
+ * graph. `isSideEffectFree` reports a module's package `sideEffects` flag as
+ * the bundler resolved it. Traversal stops at modules for which `isExcluded`
+ * returns true (CSS, always-loaded framework chunks, virtual modules that must
+ * not be loaded re-entrantly). A reference whose import graph cannot be fully
+ * loaded is reported as `null` so callers keep it out of groups.
+ */
+export declare function measureClientReferenceGroupCosts(options: {
+  references: ReadonlyMap<string, string>;
+  loadModule: (id: string) => Promise<LoadedModule>;
+  isExcluded: (id: string) => boolean;
+  /**
+   * Whether a module has no side effects. A side-effect-free module is not
+   * loaded until a reference uses one of its exports.
+   */
+  isSideEffectFree: (id: string) => boolean;
+}): Promise<Map<string, number | null>>;
+export type ClientReferenceGroup = {
+  /** Stable, filename-safe identifier derived from the route signature. */
+  key: string;
+  /**
+   * Member client reference ids in signature (route walk) order, which sets
+   * module evaluation and CSS order inside the group chunk.
+   */
+  referenceIds: string[];
+};
+/**
+ * Group client references that share a route signature. References without a
+ * signature, references whose cost is unknown or above `maxCostBytes`, and
+ * signatures with a single member stay ungrouped. Group keys derive from the
+ * members' `referenceKeys`, so a group keeps its chunk name when routes change
+ * but its members do not.
+ */
+export declare function planClientReferenceGroups(options: {
+  referenceIds: ReadonlySet<string>;
+  /** Stable, machine-independent key of each client reference. */
+  referenceKeys: ReadonlyMap<string, string>;
+  signatures: ReadonlyMap<string, string>;
+  costs: ReadonlyMap<string, number | null>;
+  maxCostBytes: number;
+}): ClientReferenceGroup[];
+//#endregion
+export {};