@vitejs/plugin-rsc 0.4.30 → 0.4.31

package/README.md

@@ -353,6 +353,17 @@ export default defineConfig({
       // this behavior can be customized by `serverHandler` option.
       serverHandler: false,
 
+      // the plugin provides build-time validation of 'server-only' and 'client-only' imports.
+      // this is enabled by default. See the "server-only and client-only import" section below for details.
+      validateImports: true,
+
+      // 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: 'process.env.MY_ENCRYPTION_KEY',
+
       // when `loadModuleDevProxy: true`, `import.meta.viteRsc.loadModule` is implemented
       // through `fetch` based RPC, which allows, for example, rsc environment inside
       // cloudflare workers to communicate with node ssr environment on main Vite process.
@@ -362,13 +373,6 @@ export default defineConfig({
       // if it breaks, it can be opt-out or selectively applied based on files.
       rscCssTransform: { filter: (id) => id.includes('/my-app/') },
 
-      // 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: 'process.env.MY_ENCRYPTION_KEY',
-
       // see `RscPluginOptions` for full options ...
     }),
   ],
@@ -405,7 +409,9 @@ This module re-exports RSC runtime API provided by `react-server-dom/client.brow
 - `createFromFetch`: a robust way of `createFromReadableStream((await fetch("...")).body)`
 - `encodeReply/setServerCallback`: server function related...
 
-## CSS Support
+## Tips
+
+### CSS Support
 
 The plugin automatically handles CSS code-splitting and injection for server components. This eliminates the need to manually call [`import.meta.viteRsc.loadCss()`](#importmetaviterscloadcss) in most cases.
 
@@ -439,11 +445,11 @@ export function Page() {
 }
 ```
 
-## Canary and Experimental channel releases
+### Canary and Experimental channel releases
 
 See https://github.com/vitejs/vite-plugin-react/pull/524 for how to install the package for React [canary](https://react.dev/community/versioning-policy#canary-channel) and [experimental](https://react.dev/community/versioning-policy#all-release-channels) usages.
 
-## Using `@vitejs/plugin-rsc` as a framework package's `dependencies`
+### Using `@vitejs/plugin-rsc` as a framework package's `dependencies`
 
 By default, `@vitejs/plugin-rsc` is expected to be used as `peerDependencies` similar to `react` and `react-dom`. When `@vitejs/plugin-rsc` is not available at the project root (e.g., in `node_modules/@vitejs/plugin-rsc`), you will see warnings like:
 
@@ -474,7 +480,7 @@ export default function myRscFrameworkPlugin() {
 }
 ```
 
-## Typescript
+### Typescript
 
 Types for global API are defined in `@vitejs/plugin-rsc/types`. For example, you can add it to `tsconfig.json` to have types for `import.meta.viteRsc` APIs:
 
@@ -494,6 +500,67 @@ import.meta.viteRsc.loadModule
 
 See also [Vite documentation](https://vite.dev/guide/api-hmr.html#intellisense-for-typescript) for `vite/client` types.
 
+### `server-only` and `client-only` import
+
+<!-- references? -->
+<!-- https://nextjs.org/docs/app/getting-started/server-and-client-components#preventing-environment-poisoning -->
+<!-- https://overreacted.io/how-imports-work-in-rsc/ -->
+
+You can use the `server-only` import to prevent accidentally importing server-only code into client bundles, which can expose sensitive server code in public static assets.
+For example, the plugin will show an error `'server-only' cannot be imported in client build` for the following code:
+
+- server-utils.js
+
+```tsx
+import 'server-only'
+
+export async function getData() {
+  const res = await fetch('https://internal-service.com/data', {
+    headers: {
+      authorization: process.env.API_KEY,
+    },
+  })
+  return res.json()
+}
+```
+
+- client.js
+
+```tsx
+'use client'
+import { getData } from './server-utils.js' // ❌ 'server-only' cannot be imported in client build
+...
+```
+
+Similarly, the `client-only` import ensures browser-specific code isn't accidentally imported into server environments.
+For example, the plugin will show an error `'client-only' cannot be imported in server build` for the following code:
+
+- client-utils.js
+
+```tsx
+import 'client-only'
+
+export function getStorage(key) {
+  // This uses browser-only APIs
+  return window.localStorage.getItem(key)
+}
+```
+
+- server.js
+
+```tsx
+import { getStorage } from './client-utils.js' // ❌ 'client-only' cannot be imported in server build
+
+export function ServerComponent() {
+  const data = getStorage("settings")
+  ...
+}
+```
+
+Note that while there are official npm packages [`server-only`](https://www.npmjs.com/package/server-only) and [`client-only`](https://www.npmjs.com/package/client-only) created by React team, they don't need to be installed. The plugin internally overrides these imports and surfaces their runtime errors as build-time errors.
+
+This build-time validation is enabled by default and can be disabled by setting `validateImports: false` in the plugin options.
+
 ## Credits
 
 This project builds on fundamental techniques and insights from pioneering Vite RSC implementations.

package/dist/index.js

@@ -3,7 +3,7 @@ import "./plugin-CZbI4rhS.js";
 import "./transforms-D1-2JfCh.js";
 import "./encryption-utils-BDwwcMVT.js";
 import "./rpc-CUvSZurk.js";
-import { getPluginApi, vitePluginRsc } from "./plugin-Bzocj-4a.js";
+import { getPluginApi, vitePluginRsc } from "./plugin-BI8kK-GE.js";
 import "./cjs-WQBk0zA_.js";
 import "./shared-AvKUASD5.js";
 

package/dist/{plugin-Bzocj-4a.js → plugin-BI8kK-GE.js}

@@ -183,29 +183,82 @@ function validateImportPlugin() {
 		name: "rsc:validate-imports",
 		resolveId: {
 			order: "pre",
-			async handler(source, importer, options) {
+			async handler(source, _importer, options) {
 				if ("scan" in options && options.scan) return;
-				if (source === "client-only") {
-					if (this.environment.name === "rsc") throw new Error(`'client-only' cannot be imported in server build (importer: '${importer ?? "unknown"}', environment: ${this.environment.name})`);
-					return {
-						id: `\0virtual:vite-rsc/empty`,
-						moduleSideEffects: false
+				if (source === "client-only" || source === "server-only") {
+					if (source === "client-only" && this.environment.name === "rsc" || source === "server-only" && this.environment.name !== "rsc") return {
+						id: `\0virtual:vite-rsc/validate-imports/invalid/${source}`,
+						moduleSideEffects: true
 					};
-				}
-				if (source === "server-only") {
-					if (this.environment.name !== "rsc") throw new Error(`'server-only' cannot be imported in client build (importer: '${importer ?? "unknown"}', environment: ${this.environment.name})`);
 					return {
-						id: `\0virtual:vite-rsc/empty`,
+						id: `\0virtual:vite-rsc/validate-imports/valid/${source}`,
 						moduleSideEffects: false
 					};
 				}
 			}
 		},
 		load(id) {
-			if (id.startsWith("\0virtual:vite-rsc/empty")) return `export {}`;
+			if (id.startsWith("\0virtual:vite-rsc/validate-imports/invalid/")) return `throw new Error("invalid import of '${id.slice(id.lastIndexOf("/") + 1)}'")`;
+			if (id.startsWith("\0virtual:vite-rsc/validate-imports/")) return `export {}`;
+		},
+		transform: {
+			order: "post",
+			async handler(_code, id) {
+				if (this.environment.mode === "dev") {
+					if (id.startsWith(`\0virtual:vite-rsc/validate-imports/invalid/`)) {
+						const chain = getImportChainDev(this.environment, id);
+						validateImportChain(chain, this.environment.name, this.environment.config.root);
+					}
+				}
+			}
+		},
+		buildEnd() {
+			if (this.environment.mode === "build") {
+				const serverOnly = getImportChainBuild(this, "\0virtual:vite-rsc/validate-imports/invalid/server-only");
+				validateImportChain(serverOnly, this.environment.name, this.environment.config.root);
+				const clientOnly = getImportChainBuild(this, "\0virtual:vite-rsc/validate-imports/invalid/client-only");
+				validateImportChain(clientOnly, this.environment.name, this.environment.config.root);
+			}
 		}
 	};
 }
+function getImportChainDev(environment, id) {
+	const chain = [];
+	const recurse = (id$1) => {
+		if (chain.includes(id$1)) return;
+		const info = environment.moduleGraph.getModuleById(id$1);
+		if (!info) return;
+		chain.push(id$1);
+		const next = [...info.importers][0];
+		if (next && next.id) recurse(next.id);
+	};
+	recurse(id);
+	return chain;
+}
+function getImportChainBuild(ctx, id) {
+	const chain = [];
+	const recurse = (id$1) => {
+		if (chain.includes(id$1)) return;
+		const info = ctx.getModuleInfo(id$1);
+		if (!info) return;
+		chain.push(id$1);
+		const next = info.importers[0];
+		if (next) recurse(next);
+	};
+	recurse(id);
+	return chain;
+}
+function validateImportChain(chain, environmentName, root) {
+	if (chain.length === 0) return;
+	const id = chain[0];
+	const source = id.slice(id.lastIndexOf("/") + 1);
+	let result = `'${source}' cannot be imported in ${source === "server-only" ? "client" : "server"} build ('${environmentName}' environment):\n`;
+	result += chain.slice(1, 6).map((id$1, i) => " ".repeat(i + 1) + `imported by ${path.relative(root, id$1).replaceAll("\0", "")}\n`).join("");
+	if (chain.length > 6) result += " ".repeat(7) + "...\n";
+	const error = new Error(result);
+	if (chain[1]) Object.assign(error, { id: chain[1] });
+	throw error;
+}
 
 //#endregion
 //#region src/plugins/find-source-map-url.ts
@@ -813,6 +866,11 @@ import.meta.hot.on("rsc:update", () => {
   document.querySelectorAll("vite-error-overlay").forEach((n) => n.close())
 });
 `;
+			code += `import.meta.hot.on("rsc:prune", ${(e) => {
+				document.querySelectorAll("link[rel='stylesheet']").forEach((node) => {
+					if (e.paths.includes(node.dataset.rscCssHref)) node.remove();
+				});
+			}});`;
 			return code;
 		}),
 		...vitePluginRscMinimal(rscPluginOptions, manager),
@@ -997,7 +1055,7 @@ function vitePluginUseClient(useClientPluginOptions, manager) {
 			resolveId: {
 				order: "pre",
 				async handler(source, importer, options) {
-					if (this.environment.name === serverEnvironmentName && bareImportRE.test(source)) {
+					if (this.environment.name === serverEnvironmentName && bareImportRE.test(source) && !(source === "client-only" || source === "server-only")) {
 						const resolved = await this.resolve(source, importer, options);
 						if (resolved && resolved.id.includes("/node_modules/")) {
 							packageSources.set(resolved.id, source);
@@ -1408,6 +1466,19 @@ function vitePluginRscCss(rscCssOptions = {}, manager) {
 		},
 		{
 			name: "rsc:importer-resources",
+			configureServer(server) {
+				const hot = server.environments.rsc.hot;
+				const original = hot.send;
+				hot.send = function(...args) {
+					const e = args[0];
+					if (e && typeof e === "object" && e.type === "prune") server.environments.client.hot.send({
+						type: "custom",
+						event: "rsc:prune",
+						data: e
+					});
+					return original.apply(this, args);
+				};
+			},
 			async transform(code, id) {
 				if (!code.includes("import.meta.viteRsc.loadCss")) return;
 				assert(this.environment.name === "rsc");
@@ -1507,7 +1578,8 @@ function generateResourcesCode(depsCode, manager) {
 				key: "css:" + href,
 				rel: "stylesheet",
 				precedence: "vite-rsc/importer-resources",
-				href
+				href,
+				"data-rsc-css-href": href
 			})), RemoveDuplicateServerCss && React.createElement(RemoveDuplicateServerCss, { key: "remove-duplicate-css" })]);
 		};
 	};

package/dist/plugin.js

@@ -3,7 +3,7 @@ import "./plugin-CZbI4rhS.js";
 import "./transforms-D1-2JfCh.js";
 import "./encryption-utils-BDwwcMVT.js";
 import "./rpc-CUvSZurk.js";
-import { getPluginApi, transformRscCssExport, vitePluginRsc, vitePluginRscMinimal } from "./plugin-Bzocj-4a.js";
+import { getPluginApi, transformRscCssExport, vitePluginRsc, vitePluginRscMinimal } from "./plugin-BI8kK-GE.js";
 import "./cjs-WQBk0zA_.js";
 import "./shared-AvKUASD5.js";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitejs/plugin-rsc",
-  "version": "0.4.30",
+  "version": "0.4.31",
   "description": "React Server Components (RSC) support for Vite.",
   "keywords": [
     "vite",