vite-plugin-react-server 0.3.4 → 0.3.6

package/README.md

@@ -2,62 +2,60 @@
 
 A Vite plugin that enables React Server Components (RSC) streaming and static building of html pages. Uses experimental dependencies from React, specifically `react-server-dom-esm`.
 
-Temporary patch-package is included in this repository. Example project:
+## Features
 
-the [mmcelebration.com project](https://github.com/nicobrinkkemper/mmc) is using this plugin. The build time for this website of roughly 200 html pages is a couple of seconds - depending on your machine.
+- 🚀 Super fast static build times
+- 🔄 Use vite to create your personal meta-framework
+- ⚡ Full RSC streaming support
+- 📦 Dual-worker architecture for optimal performance
+- 🔧 Automatic client/server code splitting
+- 🎯 Directive-based component targeting
 
-## Canary first development
+## Example Project
 
-This plugin was developed using the react version currrently hosted on the official react github repository. You can
-only get this version of react-server-dom-esm by actually building react from source. There's a patch system included
-that allows you to download the stub version of react-server-dom-esm and apply the patch to it.
+The [mmcelebration.com project](https://github.com/nicobrinkkemper/mmc) uses this plugin. Build time for ~200 html pages is just a few seconds.
 
-```bash
-npm install react-server-dom-esm
-```
-This package exists, but is empty! So, we need to patch it.
+## Installation
 
 ```bash
-npx vite-react-stream/patch
-```
-This will do two things:
-- Look for your installed react version
-- Change the patch around so it matches your react version
-- Writes a file to patches/react-server-dom-esm+YOUR-REACT-VERSION.patch
-```bash
-npm install patch-package --save-dev
-```
-Add to postinstall script in package.json: (you need to do this yourself)
-```json
-"postinstall": "patch-package"
+npm install vite-plugin-react-server
 ```
-Now anytime you run install, it will patch the react-server-dom-esm package. Wait until the package is released
-and you can remove the patch-package script.
-
-If you don't want to rely on this, you can also build react from source yourself and run `npm run link` where the package.json is, then `npm link react-server-dom-esm` where you need to use it. However, make sure to also link the react and react-dom package as well or the versions will mismatch (hence the patch-package system).
 
-## Features
+### React Canary Setup
 
-- 🚀 Super fast static build times
-- 🔄 Use vite to create your personal meta-framework
-
-## Installation
+This plugin requires React's experimental features. You'll need to:
 
+1. Install react-server-dom-esm (currently an empty stub package):
 ```bash
-npm install vite-plugin-react-server
+npm install react-server-dom-esm
 ```
 
-## Usage
+2. Apply the patch:
+```bash
+npx vite-plugin-react-server/patch
+```
+This will:
+- Detect your installed React version
+- Adapt the patch accordingly
+- Create `patches/react-server-dom-esm+YOUR-REACT-VERSION.patch`
 
-Single vite.config.ts file for server and client build - though you can split it up if you want.
-The import `import { viteReactStreamPlugin } from 'vite-plugin-react-server'` will import the
-right client/server plugin based on the NODE_OPTIONS environment variable.
+3. Install patch-package:
+```bash
+npm install patch-package --save-dev
+```
 
-Checkout the [template directory](./template) for a complete example.
+4. Add to package.json:
+```json
+{
+  "scripts": {
+    "postinstall": "patch-package"
+  }
+}
+```
 
+Alternative: You can build React from source and use `npm link` for react-server-dom-esm, react, and react-dom (though the patch system is recommended).
 
-## Configuration
-To keep the client and server build processes easy to seperate, I suggest creating two vite.config.ts files and import the config in both. Let's make the stream plugin config file and name it `.tsx`. Vite config files can't end with `.tsx` but our own files can.
+## Basic Configuration
 
 ```typescript
 // vite.react-server.config.ts
@@ -66,11 +64,8 @@ import type { Options } from 'vite-plugin-react-server'
 
 // Custom router example
 const createRouter = (file: 'props.ts' | 'Page.tsx') => (url: string) => {
-  console.log(url)
-  if(url.includes('bidoof'))
-    return `src/page/bidoof/${file}`
-  if(url === '/index.rsc')
-    return `src/page/${file}`;
+  if(url.includes('bidoof')) return `src/page/bidoof/${file}`
+  if(url === '/index.rsc') return `src/page/${file}`;
   return `src/page/404/${file}`;
 }
 
@@ -82,22 +77,21 @@ export const streamPluginOptions: Options = {
   propsExportName: "props",
 }
 ```
-Now let's make the client build config file.
+
+### Client Build Config
+
 ```typescript
 // vite.config.ts
 import { defineConfig } from 'vite'
 import { viteReactStreamPlugin } from 'vite-plugin-react-server/client'
 import { streamPluginOptions } from './vite.react-server.config.js'
 
-
 export default defineConfig({
-  plugins: [
-    viteReactStreamPlugin(streamPluginOptions)
-  ]
+  plugins: [viteReactStreamPlugin(streamPluginOptions)]
 })
 ```
 
-And the server build config file:
+### Server Build Config
 
 ```typescript
 // vite.server.config.ts
@@ -105,62 +99,37 @@ import { defineConfig } from 'vite'
 import { viteReactStreamPlugin } from 'vite-plugin-react-server/server'
 import { streamPluginOptions } from './vite.react-server.config.js'
 
-export default defineConfig({
-  plugins: [
-    viteReactStreamPlugin(streamPluginOptions)
-  ]
-})
-```
-
-```typescript
-// vite.server.config.ts
-import { viteReactStreamPlugin } from 'vite-plugin-react-server/server'
-import { streamPluginOptions } from './vite.react.config.js'
-
 export default defineConfig({
   plugins: [viteReactStreamPlugin(streamPluginOptions)]
 })
 ```
-```typescript
-// vite.config.ts
-import { viteReactStreamPlugin } from 'vite-plugin-react-server/client'
-import { streamPluginOptions } from './vite.react.config.js'
 
-export default defineConfig({
-  plugins: [viteReactStreamPlugin(streamPluginOptions)]
-})
-```
-Then in the package.json, add the scripts:
+### Scripts Setup
 
 ```json
-"scripts": {
-  "start": "NODE_OPTIONS=--conditions=react-server vite",
-  "build": "npm run build:client && npm run build:server",
-  "build:client": "vite build",
-  "build:server": "NODE_OPTIONS=--conditions=react-server vite build --ssr --config vite.server.config.ts",
-  "test:server": "NODE_OPTIONS=--conditions=react-server vitest --config vite.server.config.ts"
+{
+  "scripts": {
+    "start": "NODE_OPTIONS=--conditions=react-server vite",
+    "build": "npm run build:client && npm run build:server",
+    "build:client": "vite build",
+    "build:server": "NODE_OPTIONS=--conditions=react-server vite build --ssr --config vite.server.config.ts",
+    "test:server": "NODE_OPTIONS=--conditions=react-server vitest --config vite.server.config.ts"
+  }
 }
 ```
 
-Unfortunately, you can not write jsx in the config file since vite does not support the `.tsx` extension - any other file will be fine and jsx works like you would expect.
+## Component Types
 
-
-## Server Components
-
-Create server components in your pages directory:
-
-```typescript
+### Server Components (Default)
+```tsx
 // src/page/pokemon/page.tsx
 export function Page({ pokemon }) {
   return <div>Its a {pokemon.name}!</div>
 }
 ```
 
-## Page Props
-
-Define props for your pages:
-
-```typescript
+### Page Props
+```tsx
 // src/page/pokemon/props.ts
 export const props = async () => {
   const res = await fetch("https://pokeapi.co/api/v2/pokemon-form/399/")
@@ -168,143 +137,25 @@ export const props = async () => {
 }
 ```
 
-## Client Entry
+### Client Components
+Use the "use client" directive for client-side features:
+```tsx
+"use client"
+import { useState } from 'react'
 
-How to fetch the server component streams, I suggest to make a file like this:
-```typescript
-// src/createReactFetcher.tsx
-import type { ReactNode } from "react";
-import { createFromFetch } from "react-server-dom-esm/client.browser";
-import { callServer } from "./callServer.js";
-
-export function createReactFetcher({
-  url = window.location.pathname,
-  moduleBaseURL = "/src",
-  headers = { Accept: "text/x-component" },
-}: {
-  url?: string;
-  moduleBaseURL?: string;
-  headers?: HeadersInit;
-} = {}): Promise<ReactNode> {
-  return createFromFetch(
-    fetch(url, {
-      headers: headers,
-    }),
-    {
-      callServer: callServer,
-      moduleBaseURL: new URL(moduleBaseURL, window.origin).href,
-    }
-  ) as Promise<ReactNode>;
+export function Counter() {
+  const [count, setCount] = useState(0)
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>
 }
 ```
-then use it in your client entry file:
-```typescript
-// src/client.tsx
-const Shell: React.FC<{
-  data: React.Usable<unknown>;
-}> = ({ data: initialServerData }) => {
-  const [, startTransition] = useTransition();
-  const [storeData, setStoreData] =
-    useState<React.Usable<unknown>>(initialServerData);
-
-  const navigate = useCallback((to: string) => {
-    startTransition(() => {
-      // Create new RSC data stream
-      setStoreData(
-        createReactFetcher({
-          url: to + to.endsWith("/") ? "index.rsc" : "/index.rsc",
-        })
-      );
-    });
-  }, []);
-
-  // Routing example, useEventListener would just use useEffect and window.addEventListener
-  useEventListener("popstate", (e) => {
-    if (e instanceof PopStateEvent) {
-      if (e.state?.to) {
-        return navigate(e.state.to);
-      }
-    } else {
-      return navigate(window.location.pathname);
-    }
-  });
-
-  const content = use(storeData);
-
-  return <ErrorBoundary>{content as ReactNode}</ErrorBoundary>;
-};
-// Initialize the app
-const rootElement = document.getElementById("root");
-if (!rootElement) throw new Error("Root element not found");
-
-const intitalData = createReactFetcher({
-  url: "/index.rsc",
-});
-
-createRoot(rootElement).render(<Shell data={intitalData} />);
-```
-
-## HTML Template
-
-For development, you can still use the html template - but 
-you can provide your own Html function directly in the plugin options.
-```html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <link href="src/index.css" rel="stylesheet" />
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/client.tsx"></script>
-  </body>
-</html>
-```
-
-
-## Production html templating
-
-The optional Html component can be used to wrap the entire stream. This component is only
-used for production builds - you can not rely on it for development. This is because,
-during development we use vite's native html template and the stream will only contain
-the page content's.
-
-The Html component is quite powerful since it gets access to all the page props, the vite client manifest,
-and the children of the stream.
-
-```typescript
-import React from "react";
-import type { Manifest } from "vite";
-import { Favicons } from "./layout/Favicons.js";
-import { Head } from "./layout/Head.js";
-
-export const Html = ({
-  children,
-  pageProps,
-  manifest,
-}: {
-  children: React.ReactNode;
-  pageProps: HtmlProps;
-  manifest: Manifest;
-}) => {
-  if (process.env["NODE_ENV"] === "production") {
-    return (
-      <html>
-        <head>
-          <Head title={pageProps.title} />
-          <meta name="description" content={pageProps.description} />
-          <Favicons favicons={pageProps.favicons} />
-        </head>
-        <body>
-          <div id="root">{children}</div>
-        </body>
-      </html>
-    );
-  }
-  return <>{children}</>;
-};
 
+### Server Actions
+Use the "use server" directive for server-side API endpoints:
+```tsx
+"use server"
+export async function submitForm(data: FormData) {
+  // Server-side logic
+}
 ```
 
 ## Notes
@@ -318,5 +169,45 @@ export const Html = ({
 
 MIT
 
+## FAQ
+
+### Why does this plugin use two separate workers?
+
+The plugin uses a dual-worker architecture to handle the complex boundary between server and client code in React 19's new paradigm. This design enables four key scenarios:
+
+1. **Pure Client** - Client-side React rendering
+2. **Pure Server** - Server-side RSC streaming
+3. **Client-with-server-worker** - Thread WITHOUT React server conditions using dependencies that are ONLY available using the server condition
+4. **Server-with-client-worker** - Thread WITH React server conditions using dependencies that are ONLY available WITHOUT the server condition
+
+This architecture is necessary because React 19 introduces a fundamental shift in how server/client boundaries work. While React was traditionally client/browser-oriented, version 19 moves much of the functionality to the server by default.
+
+## When to use which directive?
+
+The "use client" should be used for components that use client-only things, like hooks - browser window, localStorage, etc.
+
+
+The "use server" directive is *not* for server components, it's for server actions. Every component is a server component by default. If the "use server" directive is present, 
+this plugin will register it as a server action - which means you can intend the exported functions to be API endpoints.
+
+## What about .client.tsx files, .server.tsx files?
+
+Whenever you use the directive, it's recommended to also name the file with the .client.tsx or .server.tsx extension respectively.
+While this isn't required for the plugin to work - it's the only way to make sure all client and server files are included in the build - 
+even if they are not a main entry point.
+
+### What's the deal with NODE_OPTIONS and conditions?
+
+The React Server Components system requires specific Node conditions:
+
+- `NODE_OPTIONS='--conditions=react-server'` is required for RSC functionality (generating RSC streams)
+- This condition must NOT be present for client-side React operations (generating HTML from RSC streams)
+
+The plugin recommends using the react-server condition in the main thread to enable React server features from the start. When different conditions are needed (e.g., generating static HTML), the plugin uses workers with appropriate conditions.
+
+### Why start with "use client"?
+
+With React 19's server-first approach, many existing ecosystem tools and patterns need the "use client" directive to work as they did before. It's becoming a common pattern to start with "use client" to maintain compatibility with existing code while gradually adopting the new server-first paradigm.
+
 
 

package/bin/patch.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises'
+import path, { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url';
+
+const PATCH_RECONCILER_VERSION = '0.0.0-experimental-b3a95caf-20250113.patch'
+const STUB_VERSION = '0.0.1'
+const __dirname = dirname(fileURLToPath(import.meta.url));  
+
+async function patchReactExperimental() {
+  try {
+    // Read installed React version from user's project
+    const reactPkg = JSON.parse(
+      await fs.readFile(
+        path.resolve(process.cwd(), 'node_modules/react/package.json'),
+        'utf-8'
+      )
+    )
+    const installedVersion = reactPkg.version
+
+    // Define patches to process
+    const patches = [
+      {
+        template: `../scripts/react-server-dom-esm+${PATCH_RECONCILER_VERSION}`,
+        output: `react-server-dom-esm+${STUB_VERSION}.patch`
+      },
+      {
+        template: `../scripts/react+${PATCH_RECONCILER_VERSION}`,
+        output: `react+${installedVersion}.patch`
+      },
+      {
+        template: `../scripts/react-dom+${PATCH_RECONCILER_VERSION}`,
+        output: `react-dom+${installedVersion}.patch`
+      }
+    ]
+
+    // Create patches dir in user's project
+    const userPatchesDir = path.resolve(process.cwd(), 'patches')
+    await fs.mkdir(userPatchesDir, { recursive: true })
+
+    // Process each patch
+    for (const {template, output} of patches) {
+      const patchPath = path.resolve(__dirname, template)
+      let patchContent = await fs.readFile(patchPath, 'utf-8')
+
+      // Replace version strings
+      patchContent = patchContent.replace(
+        new RegExp(PATCH_RECONCILER_VERSION, 'g'),
+        installedVersion
+      )
+
+      // Write the patch file
+      const newPatchPath = path.resolve(userPatchesDir, output)
+      await fs.writeFile(newPatchPath, patchContent)
+      console.log(`Created patch file: patches/${output}`)
+    }
+
+    console.log(`
+✅ Created patch files for React packages
+   Location: patches/
+
+Next steps:
+1. Install patch-package:
+   npm install patch-package --save-dev
+
+2. Add to package.json:
+   "postinstall": "patch-package"
+
+3. Run:
+   npm install
+
+The patches will be applied automatically on install.
+`)
+    return true
+  } catch (e) {
+    console.error('Failed to create patches:', e)
+    process.exit(1)
+  }
+}
+
+patchReactExperimental().catch((e) => {
+  console.error('Unexpected error:', e)
+  process.exit(1)
+}) 

package/dist/client.d.ts

@@ -0,0 +1,3 @@
+export { reactClientPlugin } from './plugin/react-client/plugin.js';
+export type * from './plugin/types.js';
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAGpE,mBAAmB,mBAAmB,CAAC"}

package/dist/client.js

@@ -0,0 +1,7 @@
+/**
+ * vite-plugin-react-server
+ * Copyright (c) Nico Brinkkemper
+ * MIT License
+ */
+export { reactClientPlugin } from './plugin/react-client/plugin.js';
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;"}

package/dist/index.d.ts

@@ -1,3 +1,8 @@
-export { reactStreamPlugin } from './plugin.js';
-export type * from './types.js';
+import type { StreamPluginOptions } from './plugin/types.js';
+export declare const viteReactServer: (options: StreamPluginOptions) => Promise<import("vite").Plugin<{
+    meta: import("./server.js").ReactStreamPluginMeta;
+    addCssFile: (path: string) => void;
+}> | (() => void)>;
+export declare const viteReactClient: (options: StreamPluginOptions) => Promise<import("vite").Plugin<any> | (() => void)>;
+export declare const viteReactStream: (options: StreamPluginOptions) => Promise<import("vite").Plugin<any> | (() => void)>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGhD,mBAAmB,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAI7D,eAAO,MAAM,eAAe,YAAmB,mBAAmB;;;kBAOjE,CAAA;AAED,eAAO,MAAM,eAAe,YAAmB,mBAAmB,uDAOjE,CAAA;AAED,eAAO,MAAM,eAAe,YAAa,mBAAmB,uDAM3D,CAAA"}

package/dist/index.js

@@ -1,5 +1,34 @@
-import { reactStreamPlugin } from "./react-server/plugin.js";
-export {
-  reactStreamPlugin
+/**
+ * vite-plugin-react-server
+ * Copyright (c) Nico Brinkkemper
+ * MIT License
+ */
+const isServer = process.env["NODE_OPTIONS"]?.match(/--conditions[= ]react-server/);
+const viteReactServer = async (options) => {
+  if (!isServer) {
+    return () => {
+    };
+  } else {
+    const module = await import('./server.js');
+    return module.reactServerPlugin(options);
+  }
 };
+const viteReactClient = async (options) => {
+  if (isServer) {
+    return () => {
+    };
+  } else {
+    const module = await import('./client.js');
+    return module.reactClientPlugin(options);
+  }
+};
+const viteReactStream = (options) => {
+  if (isServer) {
+    return viteReactClient(options);
+  } else {
+    return viteReactServer(options);
+  }
+};
+
+export { viteReactClient, viteReactServer, viteReactStream };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}
+{"version":3,"file":"index.js","sources":["../index.ts"],"sourcesContent":["\"use strict\";\n\nimport type { StreamPluginOptions } from './plugin/types.js';\n\nconst isServer = process.env['NODE_OPTIONS']?.match(/--conditions[= ]react-server/)\n\nexport const viteReactServer = async (options: StreamPluginOptions)=>{\n  if(!isServer){\n    return ()=>{}\n  } else {\n    const module = await import('./server.js')\n    return module.reactServerPlugin(options)\n  }\n}\n\nexport const viteReactClient = async (options: StreamPluginOptions)=>{\n  if(isServer){\n      return ()=>{}\n  } else {\n    const module = await import('./client.js')\n    return module.reactClientPlugin(options)\n  }\n}\n\nexport const viteReactStream = (options: StreamPluginOptions)=>{\n  if(isServer){\n    return viteReactClient(options)\n  } else {\n    return viteReactServer(options)\n  }\n}"],"names":[],"mappings":";;;;;AAIA,MAAM,WAAW,OAAQ,CAAA,GAAA,CAAI,cAAc,CAAA,EAAG,MAAM,8BAA8B,CAAA;AAErE,MAAA,eAAA,GAAkB,OAAO,OAA+B,KAAA;AACnE,EAAA,IAAG,CAAC,QAAS,EAAA;AACX,IAAA,OAAO,MAAI;AAAA,KAAC;AAAA,GACP,MAAA;AACL,IAAM,MAAA,MAAA,GAAS,MAAM,OAAO,aAAa,CAAA;AACzC,IAAO,OAAA,MAAA,CAAO,kBAAkB,OAAO,CAAA;AAAA;AAE3C;AAEa,MAAA,eAAA,GAAkB,OAAO,OAA+B,KAAA;AACnE,EAAA,IAAG,QAAS,EAAA;AACR,IAAA,OAAO,MAAI;AAAA,KAAC;AAAA,GACT,MAAA;AACL,IAAM,MAAA,MAAA,GAAS,MAAM,OAAO,aAAa,CAAA;AACzC,IAAO,OAAA,MAAA,CAAO,kBAAkB,OAAO,CAAA;AAAA;AAE3C;AAEa,MAAA,eAAA,GAAkB,CAAC,OAA+B,KAAA;AAC7D,EAAA,IAAG,QAAS,EAAA;AACV,IAAA,OAAO,gBAAgB,OAAO,CAAA;AAAA,GACzB,MAAA;AACL,IAAA,OAAO,gBAAgB,OAAO,CAAA;AAAA;AAElC;;;;"}