@vitejs/plugin-rsc 0.5.13 → 0.5.15

package/README.md

@@ -245,6 +245,33 @@ ssrModule.renderHTML(...);
 export function renderHTML(...) {}
 ```
 
+#### `import.meta.viteRsc.import`
+
+- Type: `<T>(specifier: string, options: { environment: string }) => Promise<T>`
+
+A more ergonomic alternative to `loadModule`:
+
+1. No manual `rollupOptions.input` config needed - entries are auto-discovered
+2. Specifier matches the path in `typeof import(...)` type annotations
+
+**Comparison:**
+
+```ts
+// Before (loadModule) - requires vite.config.ts:
+// environments.ssr.build.rollupOptions.input = { index: './entry.ssr.tsx' }
+import.meta.viteRsc.loadModule<typeof import('./entry.ssr.tsx')>('ssr', 'index')
+
+// After (import) - no config needed, auto-discovered
+import.meta.viteRsc.import<typeof import('./entry.ssr.tsx')>(
+  './entry.ssr.tsx',
+  { environment: 'ssr' },
+)
+```
+
+During development, this works the same as `loadModule`, using the `__VITE_ENVIRONMENT_RUNNER_IMPORT__` function to import modules in the target environment.
+
+During production build, the plugin auto-discovers these imports and emits them as entries in the target environment. A manifest file (`__vite_rsc_env_imports_manifest.js`) is generated to map module specifiers to their output filenames.
+
 ### Available on `rsc` environment
 
 #### `import.meta.viteRsc.loadCss`
@@ -616,6 +643,13 @@ Note that while there are official npm packages [`server-only`](https://www.npmj
 
 This build-time validation is enabled by default and can be disabled by setting `validateImports: false` in the plugin options.
 
+## Architecture Documentation
+
+For developers interested in the internal architecture:
+
+- **[docs/architecture.md](docs/architecture.md)** - Build pipeline, data flow, and key components
+- **[docs/bundler-comparison.md](docs/bundler-comparison.md)** - How different bundlers approach RSC
+
 ## Credits
 
 This project builds on fundamental techniques and insights from pioneering Vite RSC implementations.

package/dist/core/ssr.js

@@ -9,10 +9,7 @@ function setRequireModule(options) {
 	const requireModule = memoize((id) => {
 		return options.load(removeReferenceCacheTag(id));
 	});
-	const clientRequire = (id) => {
-		return requireModule(id);
-	};
-	globalThis.__vite_rsc_client_require__ = clientRequire;
+	globalThis.__vite_rsc_client_require__ = requireModule;
 	setInternalRequire();
 }
 function createServerConsumerManifest() {

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-import "./index-CFOPl4Gi.js";
-import vitePluginRsc, { PluginApi, RscPluginOptions, getPluginApi } from "./plugin.js";
+import { c as getPluginApi, r as PluginApi, s as RscPluginOptions, u as vitePluginRsc } from "./plugin-V6VFxi_0.js";
+import "./index-DJ0AhQ9B.js";
 export { type PluginApi, type RscPluginOptions, vitePluginRsc as default, getPluginApi };

package/dist/index.js

@@ -1,5 +1,5 @@
 import "./cjs-DH9Oa3zy.js";
-import { r as vitePluginRsc, t as getPluginApi } from "./plugin-DSNqWPmA.js";
+import { r as vitePluginRsc, t as getPluginApi } from "./plugin-DBWiu_Dx.js";
 import "./transforms-D4jDIHgD.js";
 import "./rpc-DbBe389F.js";
 

package/dist/{plugin-DSNqWPmA.js → plugin-DBWiu_Dx.js}

@@ -155,65 +155,6 @@ async function findSourceMapURL(server, filename, environmentName) {
 	};
 }
 
-//#endregion
-//#region src/plugins/resolved-id-proxy.ts
-const RESOLVED_ID_PROXY_PREFIX = "virtual:vite-rsc/resolved-id/";
-function toResolvedIdProxy(resolvedId) {
-	return RESOLVED_ID_PROXY_PREFIX + encodeURIComponent(resolvedId);
-}
-function withResolvedIdProxy(resolvedId) {
-	return resolvedId.startsWith("\0") ? toResolvedIdProxy(resolvedId) : resolvedId;
-}
-function fromResolvedIdProxy(source) {
-	if (!source.startsWith(RESOLVED_ID_PROXY_PREFIX)) return;
-	const clean = source.split("?")[0];
-	return decodeURIComponent(clean.slice(29));
-}
-/**
-* Vite plugin that resolves proxy import specifiers to the original resolved IDs.
-*/
-function vitePluginResolvedIdProxy() {
-	return {
-		name: "rsc:resolved-id-proxy",
-		resolveId: { handler(source) {
-			const originalId = fromResolvedIdProxy(source);
-			if (originalId !== void 0) return originalId;
-		} }
-	};
-}
-
-//#endregion
-//#region src/plugins/scan.ts
-function scanBuildStripPlugin({ manager }) {
-	return {
-		name: "rsc:scan-strip",
-		apply: "build",
-		enforce: "post",
-		async transform(code, _id, _options) {
-			if (!manager.isScanBuild) return;
-			return {
-				code: await transformScanBuildStrip(code),
-				map: { mappings: "" }
-			};
-		}
-	};
-}
-const importGlobRE = /\bimport\.meta\.glob(?:<\w+>)?\s*\(/g;
-async function transformScanBuildStrip(code) {
-	const [imports] = esModuleLexer.parse(code);
-	let output = imports.map((e) => e.n && `import ${JSON.stringify(e.n)};\n`).filter(Boolean).join("");
-	if (importGlobRE.test(code)) {
-		walk(await parseAstAsync(code), { enter(node) {
-			if (node.type === "CallExpression" && node.callee.type === "MemberExpression" && node.callee.object.type === "MetaProperty" && node.callee.object.meta.type === "Identifier" && node.callee.object.meta.name === "import" && node.callee.object.property.type === "Identifier" && node.callee.object.property.name === "meta" && node.callee.property.type === "Identifier" && node.callee.property.name === "glob") {
-				const importMetaGlob = code.slice(node.start, node.end);
-				output += `console.log(${importMetaGlob});\n`;
-			}
-		} });
-		output += "";
-	}
-	return output;
-}
-
 //#endregion
 //#region src/plugins/utils.ts
 function sortObject(o) {
@@ -284,6 +225,183 @@ function getFetchHandlerExport(exports) {
 	throw new Error("Invalid server handler entry");
 }
 
+//#endregion
+//#region src/plugins/import-environment.ts
+const ENV_IMPORTS_MANIFEST_NAME = "__vite_rsc_env_imports_manifest.js";
+const ENV_IMPORTS_MANIFEST_PLACEHOLDER = "virtual:vite-rsc/env-imports-manifest";
+const ENV_IMPORTS_ENTRY_FALLBACK = "virtual:vite-rsc/env-imports-entry-fallback";
+function ensureEnvironmentImportsEntryFallback({ environments }) {
+	for (const [name, config] of Object.entries(environments)) {
+		if (name === "client") continue;
+		const input = normalizeRollupOpitonsInput(config.build?.rollupOptions?.input);
+		if (Object.keys(input).length === 0) {
+			config.build = config.build || {};
+			config.build.rollupOptions = config.build.rollupOptions || {};
+			config.build.rollupOptions.input = { __vite_rsc_env_imports_entry_fallback: ENV_IMPORTS_ENTRY_FALLBACK };
+		}
+	}
+}
+function vitePluginImportEnvironment(manager) {
+	return [{
+		name: "rsc:import-environment",
+		resolveId(source) {
+			if (source === ENV_IMPORTS_MANIFEST_PLACEHOLDER) return {
+				id: ENV_IMPORTS_MANIFEST_PLACEHOLDER,
+				external: true
+			};
+		},
+		buildStart() {
+			if (this.environment.mode !== "build") return;
+			const emitted = /* @__PURE__ */ new Set();
+			for (const byTargetEnv of Object.values(manager.environmentImportMetaMap)) {
+				const imports = byTargetEnv[this.environment.name];
+				if (!imports) continue;
+				for (const meta of Object.values(imports)) if (!emitted.has(meta.resolvedId)) {
+					emitted.add(meta.resolvedId);
+					this.emitFile({
+						type: "chunk",
+						id: meta.resolvedId
+					});
+				}
+			}
+		},
+		transform: { async handler(code, id) {
+			if (!code.includes("import.meta.viteRsc.import")) return;
+			const { server } = manager;
+			const s = new MagicString(code);
+			for (const match of stripLiteral(code).matchAll(/import\.meta\.viteRsc\.import\s*(<[\s\S]*?>)?\s*\(([\s\S]*?)\)/dg)) {
+				const [argStart, argEnd] = match.indices[2];
+				const [specifier, options] = evalValue(`[${code.slice(argStart, argEnd).trim()}]`);
+				const environmentName = options.environment;
+				let resolvedId;
+				if (this.environment.mode === "dev") {
+					const targetEnv$1 = server.environments[environmentName];
+					assert(targetEnv$1, `[vite-rsc] unknown environment '${environmentName}'`);
+					const resolved = await targetEnv$1.pluginContainer.resolveId(specifier, id);
+					assert(resolved, `[vite-rsc] failed to resolve '${specifier}' in environment '${environmentName}'`);
+					resolvedId = resolved.id;
+				} else {
+					const targetEnvConfig = manager.config.environments[environmentName];
+					assert(targetEnvConfig, `[vite-rsc] unknown environment '${environmentName}'`);
+					const resolved = await this.resolve(specifier, id);
+					assert(resolved, `[vite-rsc] failed to resolve '${specifier}' in environment '${environmentName}'`);
+					resolvedId = resolved.id;
+				}
+				const sourceEnv = this.environment.name;
+				const targetEnv = environmentName;
+				manager.environmentImportMetaMap[sourceEnv] ??= {};
+				manager.environmentImportMetaMap[sourceEnv][targetEnv] ??= {};
+				manager.environmentImportMetaMap[sourceEnv][targetEnv][resolvedId] = {
+					resolvedId,
+					targetEnv,
+					sourceEnv,
+					specifier
+				};
+				let replacement;
+				if (this.environment.mode === "dev") replacement = `globalThis.__VITE_ENVIRONMENT_RUNNER_IMPORT__(${JSON.stringify(environmentName)}, ${JSON.stringify(resolvedId)})`;
+				else {
+					const relativeId = manager.toRelativeId(resolvedId);
+					replacement = `(await import(${JSON.stringify(ENV_IMPORTS_MANIFEST_PLACEHOLDER)})).default[${JSON.stringify(relativeId)}]()`;
+				}
+				const [start, end] = match.indices[0];
+				s.overwrite(start, end, replacement);
+			}
+			if (s.hasChanged()) return {
+				code: s.toString(),
+				map: s.generateMap({ hires: "boundary" })
+			};
+		} },
+		renderChunk(code, chunk) {
+			if (code.includes(ENV_IMPORTS_MANIFEST_PLACEHOLDER)) {
+				const replacement = normalizeRelativePath(path.relative(path.join(chunk.fileName, ".."), ENV_IMPORTS_MANIFEST_NAME));
+				code = code.replaceAll(ENV_IMPORTS_MANIFEST_PLACEHOLDER, () => replacement);
+				return { code };
+			}
+		}
+	}, createVirtualPlugin(ENV_IMPORTS_ENTRY_FALLBACK.slice(8), () => {
+		return `export default "__vite_rsc_env_imports_entry_fallback";`;
+	})];
+}
+function writeEnvironmentImportsManifest(manager) {
+	if (Object.keys(manager.environmentImportMetaMap).length === 0) return;
+	for (const [sourceEnv, byTargetEnv] of Object.entries(manager.environmentImportMetaMap)) {
+		const sourceOutDir = manager.config.environments[sourceEnv].build.outDir;
+		const manifestPath = path.join(sourceOutDir, ENV_IMPORTS_MANIFEST_NAME);
+		let code = "export default {\n";
+		for (const [_targetEnv, imports] of Object.entries(byTargetEnv)) for (const [resolvedId, meta] of Object.entries(imports)) {
+			const bundle = manager.bundles[meta.targetEnv];
+			if (!bundle) throw new Error(`[vite-rsc] missing bundle for environment import: ${meta.targetEnv}`);
+			const chunk = Object.values(bundle).find((c) => c.type === "chunk" && c.facadeModuleId === resolvedId);
+			if (!chunk) throw new Error(`[vite-rsc] missing output for environment import: ${resolvedId}`);
+			const targetOutDir = manager.config.environments[meta.targetEnv].build.outDir;
+			const relativePath = normalizeRelativePath(path.relative(sourceOutDir, path.join(targetOutDir, chunk.fileName)));
+			const relativeId = manager.toRelativeId(resolvedId);
+			code += `  ${JSON.stringify(relativeId)}: () => import(${JSON.stringify(relativePath)}),\n`;
+		}
+		code += "}\n";
+		fs.writeFileSync(manifestPath, code);
+	}
+}
+
+//#endregion
+//#region src/plugins/resolved-id-proxy.ts
+const RESOLVED_ID_PROXY_PREFIX = "virtual:vite-rsc/resolved-id/";
+function toResolvedIdProxy(resolvedId) {
+	return RESOLVED_ID_PROXY_PREFIX + encodeURIComponent(resolvedId);
+}
+function withResolvedIdProxy(resolvedId) {
+	return resolvedId.startsWith("\0") ? toResolvedIdProxy(resolvedId) : resolvedId;
+}
+function fromResolvedIdProxy(source) {
+	if (!source.startsWith(RESOLVED_ID_PROXY_PREFIX)) return;
+	const clean = source.split("?")[0];
+	return decodeURIComponent(clean.slice(29));
+}
+/**
+* Vite plugin that resolves proxy import specifiers to the original resolved IDs.
+*/
+function vitePluginResolvedIdProxy() {
+	return {
+		name: "rsc:resolved-id-proxy",
+		resolveId: { handler(source) {
+			const originalId = fromResolvedIdProxy(source);
+			if (originalId !== void 0) return originalId;
+		} }
+	};
+}
+
+//#endregion
+//#region src/plugins/scan.ts
+function scanBuildStripPlugin({ manager }) {
+	return {
+		name: "rsc:scan-strip",
+		apply: "build",
+		enforce: "post",
+		async transform(code, _id, _options) {
+			if (!manager.isScanBuild) return;
+			return {
+				code: await transformScanBuildStrip(code),
+				map: { mappings: "" }
+			};
+		}
+	};
+}
+const importGlobRE = /\bimport\.meta\.glob(?:<\w+>)?\s*\(/g;
+async function transformScanBuildStrip(code) {
+	const [imports] = esModuleLexer.parse(code);
+	let output = imports.map((e) => e.n && `import ${JSON.stringify(e.n)};\n`).filter(Boolean).join("");
+	if (importGlobRE.test(code)) {
+		walk(await parseAstAsync(code), { enter(node) {
+			if (node.type === "CallExpression" && node.callee.type === "MemberExpression" && node.callee.object.type === "MetaProperty" && node.callee.object.meta.type === "Identifier" && node.callee.object.meta.name === "import" && node.callee.object.property.type === "Identifier" && node.callee.object.property.name === "meta" && node.callee.property.type === "Identifier" && node.callee.property.name === "glob") {
+				const importMetaGlob = code.slice(node.start, node.end);
+				output += `console.log(${importMetaGlob});\n`;
+			}
+		} });
+		output += "";
+	}
+	return output;
+}
+
 //#endregion
 //#region src/plugins/validate-import.ts
 function validateImportPlugin() {
@@ -380,13 +498,14 @@ function resolvePackage(name) {
 var RscPluginManager = class {
 	server;
 	config;
-	rscBundle;
+	bundles = {};
 	buildAssetsManifest;
 	isScanBuild = false;
 	clientReferenceMetaMap = {};
 	clientReferenceGroups = {};
 	serverReferenceMetaMap = {};
 	serverResourcesMetaMap = {};
+	environmentImportMetaMap = {};
 	stabilize() {
 		this.clientReferenceMetaMap = sortObject(this.clientReferenceMetaMap);
 		this.serverResourcesMetaMap = sortObject(this.serverResourcesMetaMap);
@@ -401,6 +520,9 @@ var RscPluginManager = class {
 			fs.writeFileSync(manifestPath, assetsManifestCode);
 		}
 	}
+	writeEnvironmentImportsManifest() {
+		writeEnvironmentImportsManifest(this);
+	}
 };
 /** @experimental */
 function getPluginApi(config) {
@@ -465,29 +587,11 @@ function vitePluginRsc(rscPluginOptions = {}) {
 		const logStep = (msg) => {
 			builder.config.logger.info(colors.blue(msg));
 		};
-		if (!builder.environments.ssr?.config.build.rollupOptions.input) {
-			manager.isScanBuild = true;
-			builder.environments.rsc.config.build.write = false;
-			builder.environments.client.config.build.write = false;
-			logStep("[1/4] analyze client references...");
-			await builder.build(builder.environments.rsc);
-			logStep("[2/4] analyze server references...");
-			await builder.build(builder.environments.client);
-			manager.isScanBuild = false;
-			builder.environments.rsc.config.build.write = true;
-			builder.environments.client.config.build.write = true;
-			logStep("[3/4] build rsc environment...");
-			await builder.build(builder.environments.rsc);
-			manager.stabilize();
-			logStep("[4/4] build client environment...");
-			await builder.build(builder.environments.client);
-			manager.writeAssetsManifest(["rsc"]);
-			return;
-		}
 		const rscOutDir = builder.environments.rsc.config.build.outDir;
 		const ssrOutDir = builder.environments.ssr.config.build.outDir;
 		const rscInsideSsr = path.normalize(rscOutDir).startsWith(path.normalize(ssrOutDir) + path.sep);
 		const tempRscOutDir = path.join(builder.config.root, "node_modules", ".vite-rsc-temp", "rsc");
+		ensureEnvironmentImportsEntryFallback(builder.config);
 		manager.isScanBuild = true;
 		builder.environments.rsc.config.build.write = false;
 		builder.environments.ssr.config.build.write = false;
@@ -516,18 +620,10 @@ function vitePluginRsc(rscPluginOptions = {}) {
 			fs.renameSync(tempRscOutDir, rscOutDir);
 		}
 		manager.writeAssetsManifest(["ssr", "rsc"]);
+		manager.writeEnvironmentImportsManifest();
 	};
 	let hasReactServerDomWebpack = false;
 	return [
-		{
-			name: "rsc:builder-api",
-			buildApp: {
-				order: "pre",
-				async handler(builder) {
-					builder.rsc = { manager };
-				}
-			}
-		},
 		{
 			name: "rsc",
 			async config(config, env) {
@@ -883,18 +979,19 @@ export function createRpcClient(params) {
 					assert(this.environment.mode === "dev");
 					const manifest = {
 						bootstrapScriptContent: `import(${serializeValueWithRuntime(assetsURL("@id/__x00__" + VIRTUAL_ENTRIES.browser, manager))})`,
-						clientReferenceDeps: {}
+						clientReferenceDeps: {},
+						cssLinkPrecedence: rscPluginOptions.cssLinkPrecedence
 					};
 					return `export default ${JSON.stringify(manifest, null, 2)}`;
 				}
 			},
 			generateBundle(_options, bundle) {
-				if (this.environment.name === "rsc") manager.rscBundle = bundle;
+				manager.bundles[this.environment.name] = bundle;
 				if (this.environment.name === "client") {
 					const filterAssets = rscPluginOptions.copyServerAssetsToClient ?? (() => true);
 					const rscBuildOptions = manager.config.environments.rsc.build;
 					const rscViteManifest = typeof rscBuildOptions.manifest === "string" ? rscBuildOptions.manifest : rscBuildOptions.manifest && ".vite/manifest.json";
-					for (const asset of Object.values(manager.rscBundle)) {
+					for (const asset of Object.values(manager.bundles["rsc"])) {
 						if (asset.fileName === rscViteManifest) continue;
 						if (asset.type === "asset" && filterAssets(asset.fileName)) this.emitFile({
 							type: "asset",
@@ -903,30 +1000,35 @@ export function createRpcClient(params) {
 						});
 					}
 					const serverResources = {};
-					const rscAssetDeps = collectAssetDeps(manager.rscBundle);
+					const rscAssetDeps = collectAssetDeps(manager.bundles["rsc"]);
 					for (const [id, meta] of Object.entries(manager.serverResourcesMetaMap)) serverResources[meta.key] = assetsURLOfDeps({
 						js: [],
 						css: rscAssetDeps[id]?.deps.css ?? []
 					}, manager);
 					const assetDeps = collectAssetDeps(bundle);
-					const entry = Object.values(assetDeps).find((v) => v.chunk.name === "index");
-					assert(entry);
-					const entryUrl = assetsURL(entry.chunk.fileName, manager);
+					let bootstrapScriptContent = "";
 					const clientReferenceDeps = {};
 					for (const meta of Object.values(manager.clientReferenceMetaMap)) {
 						const deps = assetDeps[meta.groupChunkId]?.deps ?? {
 							js: [],
 							css: []
 						};
-						clientReferenceDeps[meta.referenceKey] = assetsURLOfDeps(mergeAssetDeps(deps, entry.deps), manager);
+						clientReferenceDeps[meta.referenceKey] = assetsURLOfDeps(deps, manager);
+					}
+					if (!rscPluginOptions.customClientEntry) {
+						const entry = Object.values(assetDeps).find((v) => v.chunk.name === "index" && v.chunk.isEntry);
+						if (!entry) throw new Error(`[vite-rsc] Client build must have an entry chunk named "index". Use 'customClientEntry' option to disable this requirement.`);
+						const entryDeps = assetsURLOfDeps(entry.deps, manager);
+						for (const [key, deps] of Object.entries(clientReferenceDeps)) clientReferenceDeps[key] = mergeAssetDeps(deps, entryDeps);
+						const entryUrl = assetsURL(entry.chunk.fileName, manager);
+						if (typeof entryUrl === "string") bootstrapScriptContent = `import(${JSON.stringify(entryUrl)})`;
+						else bootstrapScriptContent = new RuntimeAsset(`"import(" + JSON.stringify(${entryUrl.runtime}) + ")"`);
 					}
-					let bootstrapScriptContent;
-					if (typeof entryUrl === "string") bootstrapScriptContent = `import(${JSON.stringify(entryUrl)})`;
-					else bootstrapScriptContent = new RuntimeAsset(`"import(" + JSON.stringify(${entryUrl.runtime}) + ")"`);
 					manager.buildAssetsManifest = {
 						bootstrapScriptContent,
 						clientReferenceDeps,
-						serverResources
+						serverResources,
+						cssLinkPrecedence: rscPluginOptions.cssLinkPrecedence
 					};
 				}
 			},
@@ -950,6 +1052,7 @@ export default assetsManifest.bootstrapScriptContent;
 			name: "rsc:bootstrap-script-content",
 			async transform(code) {
 				if (!code.includes("loadBootstrapScriptContent") || !/import\s*\.\s*meta\s*\.\s*viteRsc\s*\.\s*loadBootstrapScriptContent/.test(code)) return;
+				assert(!rscPluginOptions.customClientEntry, `[vite-rsc] 'import.meta.viteRsc.loadBootstrapScriptContent' cannot be used with 'customClientEntry' option`);
 				assert(this.environment.name !== "client");
 				const output = new MagicString(code);
 				for (const match of stripLiteral(code).matchAll(/import\s*\.\s*meta\s*\.\s*viteRsc\s*\.\s*loadBootstrapScriptContent\(([\s\S]*?)\)/dg)) {
@@ -1006,6 +1109,7 @@ import.meta.hot.on("rsc:update", () => {
 			return code;
 		}),
 		...vitePluginRscMinimal(rscPluginOptions, manager),
+		...vitePluginImportEnvironment(manager),
 		...vitePluginFindSourceMapURL(),
 		...vitePluginRscCss(rscPluginOptions, manager),
 		{
@@ -1670,13 +1774,13 @@ function vitePluginRscCss(rscCssOptions = {}, manager) {
 						return generateResourcesCode(serializeValueWithRuntime(assetsURLOfDeps({
 							css: result.hrefs.map((href) => href.slice(1)),
 							js: []
-						}, manager)), manager);
+						}, manager)), manager, { cssLinkPrecedence: rscCssOptions.cssLinkPrecedence });
 					} else {
 						const key = manager.toRelativeId(importer);
 						manager.serverResourcesMetaMap[importer] = { key };
 						return `
               import __vite_rsc_assets_manifest__ from "virtual:vite-rsc/assets-manifest";
-              ${generateResourcesCode(`__vite_rsc_assets_manifest__.serverResources[${JSON.stringify(key)}]`, manager)}
+              ${generateResourcesCode(`__vite_rsc_assets_manifest__.serverResources[${JSON.stringify(key)}]`, manager, { cssLinkPrecedence: rscCssOptions.cssLinkPrecedence })}
             `;
 					}
 				}
@@ -1702,13 +1806,14 @@ export default function RemoveDuplicateServerCss() {
 		})
 	];
 }
-function generateResourcesCode(depsCode, manager) {
-	const ResourcesFn = (React, deps, RemoveDuplicateServerCss) => {
+function generateResourcesCode(depsCode, manager, options = {}) {
+	const usePrecedence = options.cssLinkPrecedence !== false;
+	const ResourcesFn = (React, deps, RemoveDuplicateServerCss, precedence) => {
 		return function Resources() {
 			return React.createElement(React.Fragment, null, [...deps.css.map((href) => React.createElement("link", {
 				key: "css:" + href,
 				rel: "stylesheet",
-				precedence: "vite-rsc/importer-resources",
+				...precedence ? { precedence } : {},
 				href,
 				"data-rsc-css-href": href
 			})), RemoveDuplicateServerCss && React.createElement(RemoveDuplicateServerCss, { key: "remove-duplicate-css" })]);
@@ -1723,6 +1828,7 @@ export const Resources = (${ResourcesFn.toString()})(
   __vite_rsc_react__,
   ${depsCode},
   RemoveDuplicateServerCss,
+  ${usePrecedence ? `"vite-rsc/importer-resources"` : `undefined`},
 );
 `;
 }

package/dist/plugin-V6VFxi_0.d.ts

@@ -0,0 +1,193 @@
+import { s as TransformWrapExportFilter } from "./index-DJ0AhQ9B.js";
+import MagicString from "magic-string";
+import { Plugin, ResolvedConfig, Rollup, ViteDevServer, parseAstAsync } from "vite";
+
+//#region src/plugins/import-environment.d.ts
+type EnvironmentImportMeta = {
+  resolvedId: string;
+  targetEnv: string;
+  sourceEnv: string;
+  specifier: string;
+};
+//#endregion
+//#region src/plugin.d.ts
+type ClientReferenceMeta = {
+  importId: string;
+  referenceKey: string;
+  packageSource?: string;
+  exportNames: string[];
+  renderedExports: string[];
+  serverChunk?: string;
+  groupChunkId?: string;
+};
+type ServerRerferenceMeta = {
+  importId: string;
+  referenceKey: string;
+  exportNames: string[];
+};
+/**
+* @experimental
+*/
+declare class RscPluginManager {
+  server: ViteDevServer;
+  config: ResolvedConfig;
+  bundles: Record<string, Rollup.OutputBundle>;
+  buildAssetsManifest: AssetsManifest | undefined;
+  isScanBuild: boolean;
+  clientReferenceMetaMap: Record<string, ClientReferenceMeta>;
+  clientReferenceGroups: Record<string, ClientReferenceMeta[]>;
+  serverReferenceMetaMap: Record<string, ServerRerferenceMeta>;
+  serverResourcesMetaMap: Record<string, {
+    key: string;
+  }>;
+  environmentImportMetaMap: Record<string, Record<string, Record<string, EnvironmentImportMeta>>>;
+  stabilize(): void;
+  toRelativeId(id: string): string;
+  writeAssetsManifest(environmentNames: string[]): void;
+  writeEnvironmentImportsManifest(): void;
+}
+type RscPluginOptions = {
+  /**
+  * shorthand for configuring `environments.(name).build.rollupOptions.input.index`
+  */
+  entries?: Partial<Record<"client" | "ssr" | "rsc", string>>;
+  /** @default { enviornmentName: "rsc", entryName: "index" } */
+  serverHandler?: {
+    environmentName: string;
+    entryName: string;
+  } | false;
+  /** @default false */
+  loadModuleDevProxy?: boolean;
+  rscCssTransform?: false | {
+    filter?: (id: string) => boolean;
+  };
+  /**
+  * This option allows customizing how client build copies assets from server build.
+  * By default, all assets are copied, but frameworks can establish server asset convention
+  * to tighten security using this option.
+  */
+  copyServerAssetsToClient?: (fileName: string) => boolean;
+  /**
+  * This option allows disabling action closure encryption for debugging purpose.
+  * @default true
+  */
+  enableActionEncryption?: boolean;
+  /**
+  * By default, the plugin uses a build-time generated encryption key for
+  * "use server" closure argument binding.
+  * This can be overwritten by configuring `defineEncryptionKey` option,
+  * for example, to obtain a key through environment variable during runtime.
+  * cf. https://nextjs.org/docs/app/guides/data-security#overwriting-encryption-keys-advanced
+  */
+  defineEncryptionKey?: string;
+  /** Escape hatch for Waku's `allowServer` */
+  keepUseCientProxy?: boolean;
+  /**
+  * Enable build-time validation of 'client-only' and 'server-only' imports
+  * @default true
+  */
+  validateImports?: boolean;
+  /**
+  * use `Plugin.buildApp` hook (introduced on Vite 7) instead of `builder.buildApp` configuration
+  * for better composability with other plugins.
+  * @default true since Vite 7
+  */
+  useBuildAppHook?: boolean;
+  /**
+  * Skip the default buildApp orchestration for downstream frameworks
+  * to implement custom build pipelines using `getPluginApi()`.
+  * @experimental
+  * @default false
+  */
+  customBuildApp?: boolean;
+  /**
+  * Custom environment configuration
+  * @experimental
+  * @default { browser: 'client', ssr: 'ssr', rsc: 'rsc' }
+  */
+  environment?: {
+    browser?: string;
+    ssr?: string;
+    rsc?: string;
+  };
+  /**
+  * Custom chunking strategy for client reference modules.
+  *
+  * This function allows you to group multiple client components into
+  * custom chunks instead of having each module in its own chunk.
+  * By default, client chunks are grouped by `meta.serverChunk`.
+  */
+  clientChunks?: (meta: {
+    /** client reference module id */
+    id: string;
+    /** normalized client reference module id */
+    normalizedId: string;
+    /** server chunk which includes a corresponding client reference proxy module */
+    serverChunk: string;
+  }) => string | undefined;
+  /**
+  * Controls whether CSS links use React's `precedence` attribute.
+  * @experimental
+  * @default true
+  */
+  cssLinkPrecedence?: boolean;
+  /**
+  * Opt out of the default "index" client entry convention.
+  * When enabled, the plugin will not:
+  * - Require an entry chunk named "index"
+  * - Automatically include client entry deps in each client reference's dependencies
+  *
+  * Note: `import.meta.viteRsc.loadBootstrapScriptContent` cannot be used with this option.
+  *
+  * Use this when you manually handle client entry setup and preloading.
+  *
+  * @experimental
+  * @default false
+  */
+  customClientEntry?: boolean;
+};
+type PluginApi = {
+  manager: RscPluginManager;
+};
+/** @experimental */
+declare function getPluginApi(config: Pick<ResolvedConfig, "plugins">): PluginApi | undefined;
+/** @experimental */
+declare function vitePluginRscMinimal(rscPluginOptions?: RscPluginOptions, manager?: RscPluginManager): Plugin[];
+declare global {
+  function __VITE_ENVIRONMENT_RUNNER_IMPORT__(environmentName: string, id: string): Promise<any>;
+}
+declare function vitePluginRsc(rscPluginOptions?: RscPluginOptions): Plugin[];
+declare class RuntimeAsset {
+  runtime: string;
+  constructor(value: string);
+}
+type AssetsManifest = {
+  bootstrapScriptContent: string | RuntimeAsset;
+  clientReferenceDeps: Record<string, AssetDeps>;
+  serverResources?: Record<string, Pick<AssetDeps, "css">>;
+  cssLinkPrecedence?: boolean;
+};
+type AssetDeps = {
+  js: (string | RuntimeAsset)[];
+  css: (string | RuntimeAsset)[];
+};
+type ResolvedAssetsManifest = {
+  bootstrapScriptContent: string;
+  clientReferenceDeps: Record<string, ResolvedAssetDeps>;
+  serverResources?: Record<string, Pick<ResolvedAssetDeps, "css">>;
+  cssLinkPrecedence?: boolean;
+};
+type ResolvedAssetDeps = {
+  js: string[];
+  css: string[];
+};
+declare function transformRscCssExport(options: {
+  ast: Awaited<ReturnType<typeof parseAstAsync>>;
+  code: string;
+  id?: string;
+  filter: TransformWrapExportFilter;
+}): Promise<{
+  output: MagicString;
+} | undefined>;
+//#endregion
+export { ResolvedAssetsManifest as a, getPluginApi as c, vitePluginRscMinimal as d, ResolvedAssetDeps as i, transformRscCssExport as l, AssetsManifest as n, RscPluginManager as o, PluginApi as r, RscPluginOptions as s, AssetDeps as t, vitePluginRsc as u };

package/dist/plugin.d.ts

@@ -1,161 +1,3 @@
-import { s as TransformWrapExportFilter } from "./index-CFOPl4Gi.js";
-import MagicString from "magic-string";
-import { Plugin, ResolvedConfig, Rollup, ViteDevServer, parseAstAsync } from "vite";
-
-//#region src/plugin.d.ts
-type ClientReferenceMeta = {
-  importId: string;
-  referenceKey: string;
-  packageSource?: string;
-  exportNames: string[];
-  renderedExports: string[];
-  serverChunk?: string;
-  groupChunkId?: string;
-};
-type ServerRerferenceMeta = {
-  importId: string;
-  referenceKey: string;
-  exportNames: string[];
-};
-/**
-* @experimental
-*/
-declare class RscPluginManager {
-  server: ViteDevServer;
-  config: ResolvedConfig;
-  rscBundle: Rollup.OutputBundle;
-  buildAssetsManifest: AssetsManifest | undefined;
-  isScanBuild: boolean;
-  clientReferenceMetaMap: Record<string, ClientReferenceMeta>;
-  clientReferenceGroups: Record<string, ClientReferenceMeta[]>;
-  serverReferenceMetaMap: Record<string, ServerRerferenceMeta>;
-  serverResourcesMetaMap: Record<string, {
-    key: string;
-  }>;
-  stabilize(): void;
-  toRelativeId(id: string): string;
-  writeAssetsManifest(environmentNames: string[]): void;
-}
-type RscPluginOptions = {
-  /**
-  * shorthand for configuring `environments.(name).build.rollupOptions.input.index`
-  */
-  entries?: Partial<Record<"client" | "ssr" | "rsc", string>>;
-  /** @default { enviornmentName: "rsc", entryName: "index" } */
-  serverHandler?: {
-    environmentName: string;
-    entryName: string;
-  } | false;
-  /** @default false */
-  loadModuleDevProxy?: boolean;
-  rscCssTransform?: false | {
-    filter?: (id: string) => boolean;
-  };
-  /**
-  * This option allows customizing how client build copies assets from server build.
-  * By default, all assets are copied, but frameworks can establish server asset convention
-  * to tighten security using this option.
-  */
-  copyServerAssetsToClient?: (fileName: string) => boolean;
-  /**
-  * This option allows disabling action closure encryption for debugging purpose.
-  * @default true
-  */
-  enableActionEncryption?: boolean;
-  /**
-  * By default, the plugin uses a build-time generated encryption key for
-  * "use server" closure argument binding.
-  * This can be overwritten by configuring `defineEncryptionKey` option,
-  * for example, to obtain a key through environment variable during runtime.
-  * cf. https://nextjs.org/docs/app/guides/data-security#overwriting-encryption-keys-advanced
-  */
-  defineEncryptionKey?: string;
-  /** Escape hatch for Waku's `allowServer` */
-  keepUseCientProxy?: boolean;
-  /**
-  * Enable build-time validation of 'client-only' and 'server-only' imports
-  * @default true
-  */
-  validateImports?: boolean;
-  /**
-  * use `Plugin.buildApp` hook (introduced on Vite 7) instead of `builder.buildApp` configuration
-  * for better composability with other plugins.
-  * @default true since Vite 7
-  */
-  useBuildAppHook?: boolean;
-  /**
-  * Skip the default buildApp orchestration and expose utilities on `builder.rsc`
-  * for downstream frameworks to implement custom build pipelines.
-  * @experimental
-  * @default false
-  */
-  customBuildApp?: boolean;
-  /**
-  * Custom environment configuration
-  * @experimental
-  * @default { browser: 'client', ssr: 'ssr', rsc: 'rsc' }
-  */
-  environment?: {
-    browser?: string;
-    ssr?: string;
-    rsc?: string;
-  };
-  /**
-  * Custom chunking strategy for client reference modules.
-  *
-  * This function allows you to group multiple client components into
-  * custom chunks instead of having each module in its own chunk.
-  * By default, client chunks are grouped by `meta.serverChunk`.
-  */
-  clientChunks?: (meta: {
-    /** client reference module id */
-    id: string;
-    /** normalized client reference module id */
-    normalizedId: string;
-    /** server chunk which includes a corresponding client reference proxy module */
-    serverChunk: string;
-  }) => string | undefined;
-};
-type PluginApi = {
-  manager: RscPluginManager;
-};
-/** @experimental */
-declare function getPluginApi(config: Pick<ResolvedConfig, "plugins">): PluginApi | undefined;
-/** @experimental */
-declare function vitePluginRscMinimal(rscPluginOptions?: RscPluginOptions, manager?: RscPluginManager): Plugin[];
-declare global {
-  function __VITE_ENVIRONMENT_RUNNER_IMPORT__(environmentName: string, id: string): Promise<any>;
-}
-declare function vitePluginRsc(rscPluginOptions?: RscPluginOptions): Plugin[];
-declare class RuntimeAsset {
-  runtime: string;
-  constructor(value: string);
-}
-type AssetsManifest = {
-  bootstrapScriptContent: string | RuntimeAsset;
-  clientReferenceDeps: Record<string, AssetDeps>;
-  serverResources?: Record<string, Pick<AssetDeps, "css">>;
-};
-type AssetDeps = {
-  js: (string | RuntimeAsset)[];
-  css: (string | RuntimeAsset)[];
-};
-type ResolvedAssetsManifest = {
-  bootstrapScriptContent: string;
-  clientReferenceDeps: Record<string, ResolvedAssetDeps>;
-  serverResources?: Record<string, Pick<ResolvedAssetDeps, "css">>;
-};
-type ResolvedAssetDeps = {
-  js: string[];
-  css: string[];
-};
-declare function transformRscCssExport(options: {
-  ast: Awaited<ReturnType<typeof parseAstAsync>>;
-  code: string;
-  id?: string;
-  filter: TransformWrapExportFilter;
-}): Promise<{
-  output: MagicString;
-} | undefined>;
-//#endregion
-export { AssetDeps, AssetsManifest, PluginApi, ResolvedAssetDeps, ResolvedAssetsManifest, type RscPluginManager, RscPluginOptions, vitePluginRsc as default, getPluginApi, transformRscCssExport, vitePluginRscMinimal };
+import { a as ResolvedAssetsManifest, c as getPluginApi, d as vitePluginRscMinimal, i as ResolvedAssetDeps, l as transformRscCssExport, n as AssetsManifest, o as RscPluginManager, r as PluginApi, s as RscPluginOptions, t as AssetDeps, u as vitePluginRsc } from "./plugin-V6VFxi_0.js";
+import "./index-DJ0AhQ9B.js";
+export { AssetDeps, AssetsManifest, PluginApi, ResolvedAssetDeps, ResolvedAssetsManifest, RscPluginManager, RscPluginOptions, vitePluginRsc as default, getPluginApi, transformRscCssExport, vitePluginRscMinimal };

package/dist/plugin.js

@@ -1,5 +1,5 @@
 import "./cjs-DH9Oa3zy.js";
-import { i as vitePluginRscMinimal, n as transformRscCssExport, r as vitePluginRsc, t as getPluginApi } from "./plugin-DSNqWPmA.js";
+import { i as vitePluginRscMinimal, n as transformRscCssExport, r as vitePluginRsc, t as getPluginApi } from "./plugin-DBWiu_Dx.js";
 import "./transforms-D4jDIHgD.js";
 import "./rpc-DbBe389F.js";
 

package/dist/ssr.d.ts

@@ -1,3 +1,24 @@
 import { createServerConsumerManifest, setRequireModule } from "./core/ssr.js";
+import { i as ResolvedAssetDeps } from "./plugin-V6VFxi_0.js";
+import "./index-DJ0AhQ9B.js";
 import { callServer, createFromReadableStream, createServerReference, findSourceMapURL } from "./react/ssr.js";
-export { callServer, createFromReadableStream, createServerConsumerManifest, createServerReference, findSourceMapURL, setRequireModule };
+
+//#region src/ssr.d.ts
+
+/**
+* Callback type for client reference dependency notifications.
+* Called during SSR when a client component's dependencies are loaded.
+* @experimental
+*/
+type OnClientReference = (reference: {
+  id: string;
+  deps: ResolvedAssetDeps;
+}) => void;
+/**
+* Register a callback to be notified when client reference dependencies are loaded.
+* Called during SSR when a client component is accessed.
+* @experimental
+*/
+declare function setOnClientReference(callback: OnClientReference | undefined): void;
+//#endregion
+export { OnClientReference, callServer, createFromReadableStream, createServerConsumerManifest, createServerReference, findSourceMapURL, setOnClientReference, setRequireModule };

package/dist/ssr.js

@@ -6,6 +6,15 @@ import * as ReactDOM from "react-dom";
 import assetsManifest from "virtual:vite-rsc/assets-manifest";
 
 //#region src/ssr.tsx
+let onClientReference;
+/**
+* Register a callback to be notified when client reference dependencies are loaded.
+* Called during SSR when a client component is accessed.
+* @experimental
+*/
+function setOnClientReference(callback) {
+	onClientReference = callback;
+}
 initialize();
 function initialize() {
 	setRequireModule({ load: async (id) => {
@@ -20,7 +29,7 @@ function initialize() {
 			return wrapResourceProxy(await import(
 				/* @vite-ignore */
 				id
-), {
+), id, {
 				js: [],
 				css: (await import(
 					/* @vite-ignore */
@@ -33,16 +42,27 @@ function initialize() {
 		} else {
 			const import_ = clientReferences.default[id];
 			if (!import_) throw new Error(`client reference not found '${id}'`);
-			const deps = assetsManifest.clientReferenceDeps[id];
-			if (deps) preloadDeps(deps);
-			return wrapResourceProxy(await import_(), deps);
+			const deps = assetsManifest.clientReferenceDeps[id] ?? {
+				js: [],
+				css: []
+			};
+			preloadDeps(deps);
+			onClientReference?.({
+				id,
+				deps
+			});
+			return wrapResourceProxy(await import_(), id, deps);
 		}
 	} });
 }
-function wrapResourceProxy(mod, deps) {
+function wrapResourceProxy(mod, id, deps) {
 	return new Proxy(mod, { get(target, p, receiver) {
 		if (p in mod) {
-			if (deps) preloadDeps(deps);
+			preloadDeps(deps);
+			onClientReference?.({
+				id,
+				deps
+			});
 		}
 		return Reflect.get(target, p, receiver);
 	} });
@@ -54,9 +74,9 @@ function preloadDeps(deps) {
 	});
 	for (const href of deps.css) ReactDOM.preinit(href, {
 		as: "style",
-		precedence: "vite-rsc/client-reference"
+		precedence: assetsManifest.cssLinkPrecedence !== false ? "vite-rsc/client-reference" : void 0
 	});
 }
 
 //#endregion
-export { callServer, createFromReadableStream, createServerConsumerManifest, createServerReference, findSourceMapURL, setRequireModule };
+export { callServer, createFromReadableStream, createServerConsumerManifest, createServerReference, findSourceMapURL, setOnClientReference, setRequireModule };

package/dist/transforms/index.d.ts

@@ -1,2 +1,2 @@
-import { a as transformDirectiveProxyExport, c as TransformWrapExportOptions, d as transformHoistInlineDirective, i as TransformProxyExportOptions, l as transformWrapExport, n as getExportNames, o as transformProxyExport, r as hasDirective, s as TransformWrapExportFilter, t as transformServerActionServer, u as findDirectives } from "../index-CFOPl4Gi.js";
+import { a as transformDirectiveProxyExport, c as TransformWrapExportOptions, d as transformHoistInlineDirective, i as TransformProxyExportOptions, l as transformWrapExport, n as getExportNames, o as transformProxyExport, r as hasDirective, s as TransformWrapExportFilter, t as transformServerActionServer, u as findDirectives } from "../index-DJ0AhQ9B.js";
 export { TransformProxyExportOptions, TransformWrapExportFilter, TransformWrapExportOptions, findDirectives, getExportNames, hasDirective, transformDirectiveProxyExport, transformHoistInlineDirective, transformProxyExport, transformServerActionServer, transformWrapExport };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitejs/plugin-rsc",
-  "version": "0.5.13",
+  "version": "0.5.15",
   "description": "React Server Components (RSC) support for Vite.",
   "keywords": [
     "react",
@@ -53,7 +53,7 @@
     "@playwright/test": "^1.57.0",
     "@tsconfig/strictest": "^2.0.8",
     "@types/estree": "^1.0.8",
-    "@types/node": "^24.10.7",
+    "@types/node": "^24.10.9",
     "@types/react": "^19.2.8",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "workspace:*",
@@ -75,5 +75,16 @@
     "react-server-dom-webpack": {
       "optional": true
     }
+  },
+  "compatiblePackages": {
+    "schemaVersion": 1,
+    "rolldown": {
+      "type": "incompatible",
+      "reason": "Uses Vite-specific APIs"
+    },
+    "rollup": {
+      "type": "incompatible",
+      "reason": "Uses Vite-specific APIs"
+    }
   }
 }

package/types/index.d.ts

@@ -4,6 +4,29 @@ declare global {
       loadCss: (importer?: string) => import('react').ReactNode
       loadModule: <T>(environmentName: string, entryName?: string) => Promise<T>
       loadBootstrapScriptContent: (entryName: string) => Promise<string>
+      /**
+       * Import a module from another environment using a module specifier.
+       *
+       * A more ergonomic alternative to `loadModule` that takes a relative path
+       * instead of an entry name, so the specifier matches what you'd use in
+       * `typeof import(...)` type annotations.
+       *
+       * @example
+       * ```ts
+       * const ssr = await import.meta.viteRsc.import<typeof import('./entry.ssr')>(
+       *   './entry.ssr',
+       *   { environment: 'ssr' }
+       * );
+       * ```
+       *
+       * @param specifier - Relative path to the module (e.g., './entry.ssr')
+       * @param options - Options object with `environment` specifying the target environment
+       * @returns Promise resolving to the module exports
+       */
+      import: <T>(
+        specifier: string,
+        options: { environment: string },
+      ) => Promise<T>
     }
   }
 
@@ -17,18 +40,6 @@ declare module 'vite' {
     /** Options for `@vitejs/plugin-rsc` */
     rsc?: import('@vitejs/plugin-rsc').RscPluginOptions
   }
-
-  interface ViteBuilder {
-    /**
-     * RSC plugin API exposed for custom build pipelines.
-     * Available when using `rsc({ customBuildApp: true })`.
-     * @experimental
-     */
-    rsc: {
-      /** Access to internal RscPluginManager for controlling build phases */
-      manager: import('@vitejs/plugin-rsc').RscPluginManager
-    }
-  }
 }
 
 export {}