vite-plugin-react

The @vitejs/plugin-rsc package provides React Server Components (RSC) support for Vite. It is designed to be:

• Framework-agnostic: Implements low-level RSC bundler features and provides the react-server-dom API without framework-specific abstractions.
• Runtime-agnostic: Built on the Vite environment API, making it compatible with various runtimes (e.g., Cloudflare Workers).
• HMR-enabled: Supports Hot Module Replacement for both client and server components.
• CSS-ready: Automatically handles CSS code-splitting for both client and server components, injecting them upon rendering.

The vite-plugin-react repository provides official Vite plugins for React development. It is divided into three primary functional areas:

1. Standard React Plugin (@vitejs/plugin-react): The default plugin for React projects using Babel for transformations.
2. SWC-based React Plugin (@vitejs/plugin-react-swc): A high-performance alternative that uses SWC (Speedy Web Compiler) instead of Babel.
3. React Server Components Plugin (@vitejs/plugin-rsc): Support for React Server Components (RSC) within the Vite ecosystem.

For detailed installation and configuration instructions, refer to the specific package documentation linked in the package list.

The plugin provides built-in validation for server-only and client-only imports to prevent sensitive code from leaking into client bundles or browser-specific code from being used on the server.

• Importing server-only in a client build will trigger a build-time error.
• Importing client-only in a server build will trigger a build-time error.

Note: You do not need to install official npm packages for these; the plugin intercepts these imports internally. This validation can be disabled by setting validateImports: false in the plugin options.

// client.js
'use client'
import { getData } from './server-utils.js' // ❌ 'server-only' cannot be imported in client build

When observing RSC performance tracks in Chrome DevTools, the visibility of async component spans depends on the React version's ability to recover debug information during the performance flush.

• React 19.2.8 and earlier: These versions may show track markers in Chrome without the corresponding async component spans. This happens because debug information moved from initialized child chunks onto their resolved values can be lost during the performance flush.
• React 19.3.0+ (or versions with fix #34839): React recovers moved debug information from the resolved value during the performance flush, allowing the full component spans to appear in the DevTools tracks.
• Workaround for older React versions: Frameworks like Waku apply a transform (equivalent to recovering debug information) to support RSC performance tracking on React versions that lack the native fix.

For React Fast Refresh to work correctly, files should ideally only export React components. If a module exports incompatible types (like non-component constants), the module may be invalidated, causing HMR to trigger a full reload.

To minimize impact, the plugin only invalidates the module when the value of the non-component export changes. You can use ESLint (eslint-plugin-react-refresh) or Oxlint to catch these issues.

For React Fast Refresh to work correctly, files should only export React components.

If a module exports incompatible types (like non-component constants), the module will be invalidated and HMR will trigger a full reload. While the plugin attempts to mitigate this by only invalidating when the value of a constant changes, it is best practice to keep exports limited to components.

To catch these issues, use linting rules from eslint-plugin-react-refresh, oxc, or biome.

The global __VITE_ENVIRONMENT_RUNNER_IMPORT__ function is used by import.meta.viteRsc.loadModule to import modules in a target environment during development. While the plugin provides a default implementation that uses the environment's module runner, frameworks with custom setups (like separate workers) can override this global to provide custom module loading logic.

// Custom logic to import module between multiple environments inside worker
globalThis.__VITE_ENVIRONMENT_RUNNER_IMPORT__ = async (environmentName, id) => {
  return myWorkerRunners[environmentname].import(id)
}

When extending React Server Components (RSC) with custom directives (e.g., "use custom-server" instead of the built-in "use server"), responsibilities are split between two layers:

1. Directive Owner (Third-party Plugin): Responsible for transforming the custom syntax and registering the function with the React runtime.
2. Bundler Layer (@vitejs/plugin-rsc): Responsible for module identity, graph visibility, manifests, and reference resolution.

To integrate a custom directive, a third-party Vite plugin should transform the custom syntax and report its exports as server reference claims. @vitejs/plugin-rsc will then aggregate these custom claims with the built-in "use server" claims. This allows custom syntax and metadata policies to remain decoupled from the RSC plugin while maintaining a single canonical reference identity for the bundler.