{title}

\n About\n

\n);\n```\n\n```ts\n// src/routes/props.ts — runs on the server; its result is the Page's props\nexport const props = () => ({ title: \"Hello from the server\" });\n```\n\nAdd `src/routes/about/page.tsx` the same way and `/about` exists —\nprerendered, and reachable client-side through `Link` without a page reload.\nA sibling `props.ts` is optional: add one when the page needs\nserver-computed props.\n\n```tsx\n// src/client.tsx — the whole client entry: hydration + client-side navigation\n\"use client\";\nimport { startClient } from \"vite-plugin-react-server/router/client\";\n\nstartClient({\n moduleBaseURL: import.meta.env.BASE_URL,\n publicOrigin: import.meta.env.PUBLIC_ORIGIN,\n});\n```\n\n```html\n\n\n

\n \n\n```\n\nRouting is opt-in: skip `routes` and map URLs to files yourself with\na `Page: (url) => string` mapping — see [Routing](./docs/routing.md).\n\n```bash\nnpx vite # dev server\nnpx vite build --app # build: static site + server/client ESM\n\n# With runner: \"main\" declared instead (react-server on the main thread —\n# a bit faster, better stack traces), every command carries the flag:\nNODE_OPTIONS='--conditions react-server' vite build --app\n```\n\n## Build Output\n\n```\ndist/\n├── static/ # Deployable to any static host\n│ ├── index.html # Pre-rendered HTML\n│ └── index.rsc # RSC payload for client navigation\n├── client/ # Client-side ESM modules (for SSR)\n└── server/ # Server-side ESM modules (with server actions)\n```\n\n`dist/static/` is a complete static site. `dist/client/` and `dist/server/` are ESM modules you can import in your own Express/Hono/Node server.\n\n## Client components\n\nA file is a client module when it starts with a `\"use client\"` directive — the\nsame rule as every other React setup. Nothing else marks one: the filename is\njust a filename.\n\n```tsx\n// src/components/Counter.tsx\n\"use client\";\nimport { useState } from \"react\";\nexport function Counter() {\n const [count, setCount] = useState(0);\n return ;\n}\n```\n\nLeading whitespace, comments, and a `\"use strict\"` prologue may sit above the\ndirective; a `\"use client\"` placed after real code does not count.\n\nName a file `Counter.client.tsx` if you like the reminder — but the name carries\nno meaning, and a file named that way *without* the directive gets a build\nwarning telling you to add one.\n\nSee [Getting Started](./docs/getting-started.md#what-makes-it-a-client-component).\n\n## Third-party client-component packages\n\nComponent libraries like Chakra UI, MUI, Mantine, react-aria, and framer-motion ship per-file `\"use client\"` directives in their compiled output. vprs detects these packages and preserves the directives, so the server build turns each directive module into a client reference instead of executing it under the `react-server` condition (which would throw on `createContext`/`useState`).\n\nTwo rules govern using them:\n\n- **The package must be reachable from the client graph.** The client build only emits (hosts) package modules that some first-party `\"use client\"` module imports; a client reference recorded by the server build dangles at render time (`ERR_MODULE_NOT_FOUND`) if nothing client-side pulls the package in. With such an importer in place, server components can import the package's components directly.\n- **Providers need a `\"use client\"` wrapper.** Props crossing the server→client boundary must be serializable, and a provider's value typically isn't (`ChakraProvider` takes a system object full of functions). This is an RSC constraint, not a vprs one: [Chakra's App Router guide](https://chakra-ui.com/docs/get-started/frameworks/next-app) ships that wrapper as its CLI-generated `provider.tsx` snippet.\n\nIn practice the provider wrapper satisfies both rules at once: it is the client-side importer that gets the package hosted.\n\nDetection is automatic at build start: any package with `react` in its `peerDependencies` is classified as a client package (using [`vitefu.crawlFrameworkPkgs`](https://github.com/svitejs/vitefu)). Two escape hatches if needed:\n\n```ts\nvitePluginReactServer({\n runner: \"isolated\",\n // Force a package into the list (e.g. one that doesn't peerDep react)\n clientPackages: [\"@my/internal-ui\"],\n // Skip a detected one (e.g. devDeps Storybook bringing along @storybook/react)\n excludeClientPackages: [\"@storybook/react\", \"@storybook/react-vite\"],\n});\n```\n\n## Storybook\n\nvprs ships a Storybook preset — add one line and your RSC app's components build\nand render in Storybook:\n\n```ts\n// .storybook/main.ts\nexport default {\n framework: { name: \"@storybook/react-vite\", options: {} },\n addons: [\"vite-plugin-react-server/storybook\"],\n};\n```\n\nIt strips the vprs plugin from Storybook's builder, resolves the\n`react-server-dom-esm` transport (from `react-server-loader`), and silences\n`\"use client\"`/`\"use server\"` directive noise. See\n[Storybook](./docs/storybook.md) for details.\n\n## Documentation\n\nEverything below is also published as a browsable site at\n**nicobrinkkemper.github.io/vite-plugin-react-server**,\nwhich is itself built with vprs.\n\n| Doc | What it covers |\n|-----|---------------|\n| [How vprs compares](./docs/comparison.md) | vprs vs `@vitejs/plugin-rsc`, Waku, Vike — and what vprs does not do |\n| [Getting Started](./docs/getting-started.md) | Install → first page → dev server → build → deploy |\n| [Routing](./docs/routing.md) | The file-based router: params, loaders, nested layouts, `Link` |\n| [Storybook](./docs/storybook.md) | One-line Storybook support for vprs apps |\n| [Build Output](./docs/build-output.md) | What the build produces, how to use the ESM modules |\n| [Configuration](./docs/configuration.md) | All plugin options |\n| [CSS Handling](./docs/css-handling.md) | Inline/linked CSS, CSS modules, the `Css` component |\n| [Server Actions](./docs/server-actions.md) | `\"use server\"` directives, form actions, hosting |\n| [Examples](./docs/examples.md) | Static site, dynamic server, server actions, custom routing |\n| [Troubleshooting](./docs/troubleshooting.md) | Common errors and fixes |\n| [API Reference](./docs/api-reference.md) | Exported functions, types, and components |\n\n### Internals (contributors)\n\n| Doc | What it covers |\n|-----|---------------|\n| [Architecture](./docs/internals/architecture.md) | Condition system, module structure, plugin composition |\n| [Transformer](./docs/internals/transformer.md) | How `\"use client\"` / `\"use server\"` directives are processed |\n| [Workers](./docs/internals/workers.md) | RSC and HTML worker threads |\n\n### Maintenance\n\n| Doc | What it covers |\n|-----|---------------|\n| [Releasing](./docs/releasing.md) | Version bumps, publishing, demo updates |\n| [React Compatibility](./docs/react-type-compatibility.md) | Vendored ESM transport, type system |\n\n## Requirements\n\n- Node.js 22.0.0+ (the build uses `node:fs/promises#glob`, which landed in 22)\n- **React 19.2+**, stable (`react` / `react-dom` at `^19.2.8`) or experimental.\n The RSC server APIs vprs uses (`prerenderToNodeStream`, the `react-server`\n transport exports) ship in stable React; the matching `react-server-dom-esm`\n transport comes from the `react-server-loader` dependency, which tracks your\n React track. See [React Compatibility](./docs/react-type-compatibility.md).\n- **Vite 6, 7, or 8** (`vite` peer: `^6.3.5 || ^7 || ^8`). Vite 8 builds with\n Rolldown/Oxc instead of Rollup/esbuild; vprs runs on all three.\n\n## TypeScript\n\n```json\n{\n \"compilerOptions\": {\n \"types\": [\"vite/client\", \"vite-plugin-react-server/virtual\"]\n }\n}\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}