vite-plugin-react-server 1.1.20 → 1.2.0-alpha.1

package/README.md

@@ -1,473 +1,172 @@
 # Vite React Server Plugin
 
-A Vite plugin that enables React Server Components (RSC) streaming and static HTML page generation. It leverages experimental dependencies from React, specifically `react-server-dom-esm`.
+A Vite plugin that enables React Server Components (RSC) streaming and static HTML page generation. This plugin enables a unique "Native ESM" developer experience based on the React Server Components specifications.
 
-## Example Projects
+**React Components as part of your build tooling** - not just as a dependency.
 
-- [The official demo](https://github.com/nicobrinkkemper/vite-plugin-react-server-demo-official)
-  - [Github Pages](https://nicobrinkkemper.github.io/vite-plugin-react-server-demo-official/)
-- [The mmcelebration.com project](https://github.com/nicobrinkkemper/mmc)
-  - [Github Pages](https://nicobrinkkemper.github.io/mmc/)
+### Vite's Philosophy + React
 
-## Installation
+[Vite's philosophy](https://vite.dev/guide/philosophy.html) is built around Native ESM and making frameworks first-class citizens. This plugin extends that philosophy to React Server Components:
 
-```sh
-npm install -D vite-plugin-react-server
-```
+- **Native ESM for React**: Your React components are true ESM modules that work anywhere
+- **React as Configuration**: Serialize React Server Components for static hosting
+- **On-Demand Loading**: Only streams the pages you're actually developing
 
-## Open Source and Work in Progress
 
-This project uses the latest _OSS-experimental_ React version from [the official React GitHub repository](https://github.com/facebook/react). The plugin includes a patch system to facilitate setup. First, install dependencies and patches:
-
-```sh
-npm install -D patch-package react@experimental react-dom@experimental react-server-dom-esm
-```
-
-Add the following command to your `package.json` scripts:
-
-```json
-"patch": "patch"
-```
-
-Run the patch command:
+## Quick Start
 
 ```sh
+npm install -D vite-plugin-react-server patch-package react@experimental react-dom@experimental react-server-dom-esm
 npm run patch
 ```
 
-It will instruct you to add:
-
-```json
-"postinstall": "patch-package"
-```
-
-This ensures the patch is applied after every `npm install`. If errors arise related to `react-server-dom-esm`, verify that the postinstall step ran.
-
----
-
-## Plugin Structure and Purpose
-
-### Environment-Based Execution
-
-This plugin uses environment detection to determine the execution context. It achieves this by checking the `NODE_OPTIONS` environment variable:
-
-```typescript
-import { getCondition } from "vite-plugin-react-server/config";
-
-if (getCondition() !== "react-server") {
-  throw new Error("-10 poision damage");
-}
-```
-
-Alternatively, you can pass the argument for the `react-` prefix to just get client or server back.
-
-```typescript
-import { getCondition } from "vite-plugin-react-server/config";
-
-import(`plugin.${getCondition("")}.js`);
-```
-
-The main entry point adapts based on the environment:
-
-- **Client Mode** (default) → Does not require the react-server condition, uses a worker thread for RSC requests
-  Benefits:
-  - log errors to console
-  - onMetric event for each page
-  - worker thread
-- **Server Mode** (`NODE_OPTIONS="--conditions react-server"`) → Does not need worker thread for RSC requests
-  - Direct pipeline from vite to react
+**Minimal Config:**
 
-### Custom composition
-
-You can pick and choose only the plugins you like to get the desired behavior as well. For example, we can choose only to use the preserver, the transformer, static plugin, etc.
-
-### Page & prop setup
-
-The minimal config is
-
-```tsx
-// vite.config.tsx
-import type { StreamPluginOptions } from "vite-plugin-react-server/types";
-import { join } from "node:path";
+```ts
+// vite.config.ts
 import { defineConfig } from "vite";
 import { vitePluginReactServer } from "vite-plugin-react-server";
-import { config } from "./vite.react.config.js";
 
-export default defineConfig(() => {
-  return {
+export default defineConfig({
     plugins: vitePluginReactServer({
       moduleBase: "src",
-      Page: "src/page.tsx",
+      Page: `src/page.tsx`,
+      build: { pages: ["/"] }
     }),
-  };
 });
 ```
 
-And our Page file.
+**Create a Page:**
 
 ```tsx
 // src/page.tsx
-import React from "react";
 export function Page({ url }) {
-  return <div>You are on {url}</div>;
-}
-```
-
-Of course we need a client file as well, and the vite index.html pointing to it,
-
-```tsx
-import React, { use } from "react";
-import { createRoot } from "react-dom/client";
-import { createReactFetcher } from "vite-plugin-react-server/utils";
-// src/client.tsx
-const Shell: React.FC<{
-  data: React.Usable<React.ReactNode>;
-}> = ({ data: initialServerData }) => {
-  const content = use(initialServerData);
-  return content as React.ReactNode;
-};
-// Initialize the app
-const rootElement = document.getElementById("root");
-if (!rootElement) throw new Error("Root element not found");
-
-const intitalData = createReactFetcher({
-  url: window.location.pathname,
-  moduleBaseURL: import.meta.env.BASE_URL,
-  publicOrigin: import.meta.env.PUBLIC_ORIGIN,
-});
-
-createRoot(rootElement).render(<Shell data={intitalData} />);
-```
-
-index.html for completeness sake
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/client.tsx"></script>
-  </body>
-</html>
-```
-
-By default, without any prop configurations, the Page receives a normalized url.
-
-With custom "get prop" function, we can enrich the props with more information.
-
-```tsx
-import React from "react";
-
-export const props = (url) => ({ title: "Hello World", file: import.meta.url, url });
-
-export type Props = ReturnType<typeof props>
-
-export function Page({ file, title, url }: Props) {
-  return <>
-     <title>{title}<title>
-     <div>This file is here: {file}</div>;
-     <div>You are on: {url}</div>;
-   </>
+  return <div>Hello from {url}</div>;
 }
 ```
 
-You can also define a router specifically for the props file.
+## Development & Build
 
-```tsx
+```json
 {
-  moduleBase: "src",
-  Page: "src/page.tsx",
-  // define the props router
-  props: "src/props.ts",
+  "scripts": {
+    "dev": "NODE_OPTIONS='--conditions react-server' vite",
+    "dev:client": "vite",
+    "build": "vite build && vite build --ssr && NODE_OPTIONS='--conditions react-server' vite build",
+    "debug-build": "NODE_ENV=development && vite build --mode vite build --mode development && NODE_OPTIONS='--conditions react-server' vite build",
+  }
 }
 ```
 
-Move prop lines from `src/page.tsx` to `src/props.ts`
+- **`npm run dev`**: Server-side development with direct React pipeline
+- **`npm run dev:client`**: Client-side development with worker threads
+- **`npm run build`**: Creates optimized static, client, and server builds
 
-```tsx
-export const props = (url) => ({
-  title: "Hello World",
-  file: import.meta.url,
-  url,
-});
+## Environment-Based Execution
 
-export type Props = ReturnType<typeof props>;
-```
+The plugin uses environment detection to determine execution context:
 
-We can also make a static build for these pages, which will render them to index.html and headless index.rsc files, which can be used to make a static RSC site.
+```typescript
+import { getCondition } from "vite-plugin-react-server/config";
 
-```tsx
-{
-  moduleBase: "src",
-  Page: "src/page.tsx",
-  props: "src/props.ts"
-  // define the routes we want to render
-  build: {
-    pages: ['/', '/404']
-  }
-};
+if (getCondition() !== "react-server") {
+  throw new Error("-10 poison damage");
+}
 ```
 
-And that's how you can work with react server components using a familiar vite workflow.
-If your app grows and you need more control, see the [docs](./docs) - check out the source code - and have fun building.
-
-### Worker support
-
-The client plugin uses the `rsc-worker` to create server side streams. The server plugin uses the `html-worker` to create client side html. If you don't want to use the rsc-worker, simply don't serve the plugin without the `react-server` condition. If you don't want to use the `html-worker` simply don't configure the `build.pages` option.
-
-### Custom Worker
-
-Both workers can be customized using the `htmlWorkerPath` and `rscWorkerPath` respectively. The paths will be used to create the workers instead of the prebuilt worker included with this plugin. If these paths are defined, they will be made part of your application build as well.
-
-Keep in mind that, using your custom worker means interacting with the message system of this plugin during development/static generation process.
+- **Client Mode** (default): Uses worker threads for RSC requests
+- **Server Mode** (`NODE_OPTIONS="--conditions react-server"`): Direct React pipeline
 
-## Plugin Usage
+## Advanced Features
 
-```ts
-import { defineConfig, type Plugin } from "vite";
-import { vitePluginReactClient } from "vite-plugin-react-server";
-import { config } from "./vite.react.config";
-import type { StreamPluginOptions } from "vite-plugin-react-server/server";
+### Props and Routing
 
-const createRouter = (file: "props.ts" | "page.tsx") => (url: string) => {
+```tsx
+// React components configure routing
+const createRouter = (file) => (url) => {
   switch (url) {
-    case "/":
-      return `src/page/${file}`;
-    case "/bidoof":
-      return `src/page/bidoof/${file}`;
-    case "/404":
-    default:
-      return `src/page/404/${file}`;
+    case "/": return `src/home/${file}`;
+    case "/about": return `src/about/${file}`;
+    default: return `src/404/${file}`;
   }
 };
 
-export const config = {
-  moduleBase: "src",
-  Page: createRouter("page.tsx"),
-  props: createRouter("props.ts"),
-  Html: Html,
-  build: {
-    pages: ["/", "/bidoof", "/404"],
-  },
-} satisfies StreamPluginOptions;
-
 export default defineConfig({
-  plugins: vitePluginReactClient(config),
+  plugins: vitePluginReactServer({
+    Page: createRouter("page.tsx"),
+    props: createRouter("props.ts"),
+    build: { pages: ["/", "/about"] }
+  }),
 });
 ```
 
-This will mirror your directory structure for new static routes. If you need to handle
-dynamic requests, like pointing /:theme/ to a certain folder, you need to parse this yourself
-using code.
 
-### Async build pages
 
-If you have a large amount of pages that needs async operations to fetch, you can pass a async function to build pages.
+### Server Actions
 
 ```tsx
-build:{
-  pages: async ()=>await import('my-pages')
-}
-```
-### Built-in React Server Components
-
-This plugin built-in React Component that can be configured through the options to be your own component. Direct server component config inputs are not yet supported through worker threads.
+// actions.server.ts
+"use server";
 
-- Html - used as the wrapper for production pages (use vite's `index.html` for the development wrapper and entry point for client files & global css)
-- CssCollector - used to emit `<link>` and `<style>` tags based on `css` config
-
-Defining your custom Html React server component will affect the final production output.
-
-#### Build Steps
-
-```sh
-vite build
-```
-
-Targets browsers, outputs to `dist/static`.
-
-```sh
-vite build --ssr
-```
-
-Targets non-`react-server` node environment, used for server-side-rendering, outputs to `dist/client`.
-
-```sh
-NODE_OPTIONS="--conditions=react-server" vite build
-```
-
-Targets `react-server`-only environment, outputs to `dist/server`. In this case, `ssr` is implied and defaults to true.
-
----
-
-### vite-plugin-react-server
-
-```ts
-import { defineConfig, Plugin } from "vite";
-import { vitePluginReactServer } from "vite-plugin-react-server";
-import { config } from "./vite.react.config";
-
-export default defineConfig({
-  plugins: vitePluginReactServer(config),
-});
-```
-
-#### Running in Development
-
-```sh
-NODE_OPTIONS="--conditions=react-server" vite
-```
-
-A direct server pipeline that doesn't require a `rsc-worker`.
-
-To develop the app using the `rsc-worker`, simply run
-
-```sh
-vite
-```
-
-without the `react-server` condition. This will work a little bit differently under the hood, it can provide additional development support like error logging, metric events and custom rsc worker development.
-
-## Static Site Generation
-
-Single-out the static generation step by only inluding the static plugin. Expects client and server folders to be there.
-
-```ts
-import { defineConfig, Plugin } from "vite";
-import { reactStaticPlugin } from "vite-plugin-react-server/static";
-import { config } from "./vite.react.config";
-
-export default defineConfig({
-  plugins: [reactStaticPlugin(config)],
-});
-```
-
-Example output structure:
-
-```sh
-dist/static/index.html
-dist/static/index.rsc
-dist/static/about/index.html
-dist/static/about/index.rsc
-```
-
-This plugin is included by default when the `react-server` condition is set.
-
----
-
-## Configuration
-
-### moduleBase
-
-```ts
-const config = {
-  moduleBase: "src",
-};
-```
-
-Defines the root directory for project modules. This can be customized.
-
-### moduleBasePath
-
-```ts
-moduleBasePath: "/",
-```
-
-Passed as the second argument to `renderToPipeableStream` for server-side rendering.
-
-### moduleBaseURL
-
-```ts
-moduleBaseURL: "/",
-```
-
-Defines asset URL resolution for CSS collectors and bootstrapModule.
+export async function addTodo(title: string) {
+  return { success: true };
+}
 
-```ts
-publicOrigin: "https://github.com",
+// Use in components
+import { addTodo } from "./actions.server.js";
+export function TodoForm() {
+  return <form action={addTodo}>...</form>;
+}
 ```
 
-### Page and props Mapping
+### Client Components
 
-```ts
-Page: (id) => join('src', id, "page.tsx");
-```
-
-Defines how pages are mapped to file paths.
+```tsx
+// Counter.client.tsx
+"use client";
+import { useState } from "react";
 
-```ts
-props: (id) => join('src', id, "props.ts");
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+}
 ```
 
-Defines how to load the initial props of the page file.
+## Build Output
 
-If you do not want prop files, just don't define it.
+The plugin generates three build targets:
 
-```ts
-pageExportName: 'Page',
 ```
-
-Changes the default name "Page"
-
-```ts
-propsExportName: 'props',
+dist/
+├── static/     # Browser-ready static files (HTML + RSC)
+├── client/     # Server-side rendering modules  
+└── server/     # React Server Components modules
 ```
 
-Changes the default name "props"
 
----
+## Documentation
 
-## Example Setup
+| Topic | Description |
+|-------|-------------|
+| [Getting Started](./docs/getting-started.md) | Complete installation and setup guide |
+| [Core Concepts](./docs/core-concepts.md) | Architecture, RSC, and plugin design |
+| [Configuration](./docs/configuration.md) | All configuration options and examples |
+| [CSS Handling](./docs/css-handling.md) | CSS collection, inlining, and optimization |
+| [Server Actions](./docs/server-actions.md) | Server-side functions and database integration |
+| [Static Site Generation](./docs/static-site-generation.md) | Building and deploying static sites |
+| [API Reference](./docs/api-reference.md) | Complete API documentation |
+| [Advanced Topics](./docs/advanced-topics.md) | Custom workers and extending the plugin |
 
-### package.json Scripts
+## Requirements
 
-```json
-"scripts": {
-  "build": "build:static && build:client && build:server",
-  "dev": "NODE_OPTIONS='--conditions react-server' vite",
-  "start": "vite",
-  "build:server": "NODE_OPTIONS='--conditions react-server' vite build",
-  "build:client": "vite build --ssr",
-  "build:static": "vite build"
-}
-```
+- **Node.js**: 23.7.0 or higher
+- **React**: Experimental version (handled by patch system)
+- **Vite**: Compatible with latest Vite versions
 
-### Sample Page Component
+## Contributing
 
-```tsx
-// src/my-page.tsx
-export const Page = ({ name }) => {
-  return <div>Hello {name}</div>;
-};
-// src/async-page.tsx
-export const Page = async ({ name }) => {
-  return <div>Hello {name}</div>;
-};
-```
-
-### Sample Props File
-
-All of the below are valid
-
-```ts
-// src/my-props.ts
-export const props = {
-  name: "John Doe",
-};
-export const props = (url)=>{
-  name: "John Doe",
-};
-export const props = async (url)=>{
-  name: "John Doe",
-}
-// enum bonus
-export const props = ['key']; // -> {key: "key"}
-// Object.fromEntries()
-export const props = [['key',{value: 'some value'}]]
-```
+This project uses experimental React features and includes a patch system for compatibility. See [Patch System](./docs/patch-system.md) for maintenance details.
 
-## Contributions
+## License
 
-If you want to help develop or maintain the plugin feel free to open a PR or issue on GitHub.
+MIT License - see [LICENSE](./LICENSE) file for details.

package/dist/_virtual/dynamic-import-helper.js

@@ -21,4 +21,4 @@ const __variableDynamicImportRuntimeHelper = (glob, path, segs) => {
 };
 
 export { __variableDynamicImportRuntimeHelper as default };
-//# sourceMappingURL=dynamic-import-helper.js.map
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZHluYW1pYy1pbXBvcnQtaGVscGVyLmpzIiwic291cmNlcyI6W10sInNvdXJjZXNDb250ZW50IjpbXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OyJ9

package/dist/client.d.ts

@@ -1,3 +1,4 @@
-export { vitePluginReactServer as vitePluginReactClient } from './plugin/plugin.client.js';
+export * from './plugin/plugin.client.js';
+export * from './plugin/react-client/index.js';
 export type * from './plugin/types.js';
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../client.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,qBAAqB,IAAI,qBAAqB,EAAE,MAAM,2BAA2B,CAAA;AAG1F,mBAAmB,mBAAmB,CAAA"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../client.ts"],"names":[],"mappings":"AAKA,cAAc,2BAA2B,CAAA;AACzC,cAAc,gCAAgC,CAAA;AAE9C,mBAAmB,mBAAmB,CAAA"}

package/dist/client.js

@@ -3,5 +3,9 @@
  * Copyright (c) Nico Brinkkemper
  * MIT License
  */
-export { vitePluginReactServer as vitePluginReactClient } from './plugin/plugin.client.js';
-//# sourceMappingURL=client.js.map
+export { vitePluginReactClient, vitePluginReactServer } from './plugin/plugin.client.js';
+export { createWorkerStream } from './plugin/react-client/createWorkerStream.js';
+export { handleWorkerRscStream } from './plugin/react-client/handleWorkerRscStream.js';
+export { handleWorkerServerAction } from './plugin/react-client/handleWorkerServerAction.js';
+export { reactClientPlugin } from './plugin/react-client/plugin.js';
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xpZW50LmpzIiwic291cmNlcyI6W10sInNvdXJjZXNDb250ZW50IjpbXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7OyJ9

package/dist/index.js

@@ -14,4 +14,4 @@ const vitePluginReactServer = await __variableDynamicImportRuntimeHelper((/* #__
 });
 
 export { vitePluginReactServer };
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VzIjpbIi4uL2luZGV4LnRzIl0sInNvdXJjZXNDb250ZW50IjpbIlwidXNlIHN0cmljdFwiO1xuXG5jb25zdCBjb25kaXRpb24gPSBwcm9jZXNzLmVudlsnTk9ERV9PUFRJT05TJ10/Lm1hdGNoKC8tLWNvbmRpdGlvbnNbPSBdcmVhY3Qtc2VydmVyLykgPyAnc2VydmVyJyA6ICdjbGllbnQnXG5cbmV4cG9ydCBjb25zdCB2aXRlUGx1Z2luUmVhY3RTZXJ2ZXIgPSBhd2FpdCBpbXBvcnQoYC4vcGx1Z2luL3JlYWN0LXNlcnZlci9wbHVnaW4uJHtjb25kaXRpb259LmpzYCkudGhlbihtID0+IHtcbiAgaWYoISgndml0ZVBsdWdpblJlYWN0U2VydmVyJyBpbiBtKSl7XG4gICAgdGhyb3cgbmV3IEVycm9yKGBDb3VsZCBub3QgZmluZCB2aXRlUGx1Z2luUmVhY3RTZXJ2ZXIgaW4gLi9wbHVnaW4vcmVhY3Qtc2VydmVyL3BsdWdpbi4ke2NvbmRpdGlvbn0uanNgKTtcbiAgfVxuICByZXR1cm4gbVsndml0ZVBsdWdpblJlYWN0U2VydmVyJ11cbn0pXG5cbi8vIHR5cGVzXG5leHBvcnQgdHlwZSAqIGZyb20gJy4vcGx1Z2luL3R5cGVzLmpzJyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7O0FBRUEsTUFBTSxTQUFBLEdBQVksUUFBUSxHQUFJLENBQUEsY0FBYyxHQUFHLEtBQU0sQ0FBQSw4QkFBOEIsSUFBSSxRQUFXLEdBQUEsUUFBQTtBQUUzRixNQUFNLHdCQUF3QixNQUFNLG9DQUFBLG1DQUFBLEdBQUEsQ0FBQSw2QkFBQSxFQUFBLFNBQUEsQ0FBQSxHQUFBLENBQUEsRUFBQSxDQUFBLENBQWdELENBQU8sS0FBSyxDQUFLLENBQUEsS0FBQTtBQUMxRyxFQUFHLElBQUEsRUFBRSwyQkFBMkIsQ0FBRyxDQUFBLEVBQUE7QUFDakMsSUFBQSxNQUFNLElBQUksS0FBQSxDQUFNLENBQXdFLHFFQUFBLEVBQUEsU0FBUyxDQUFLLEdBQUEsQ0FBQSxDQUFBO0FBQUE7QUFFeEcsRUFBQSxPQUFPLEVBQUUsdUJBQXVCLENBQUE7QUFDbEMsQ0FBQzs7OzsifQ==