spiceflow React framework. RSC stack based on @vitejs/plugin-rsc

.changeset/fifty-rings-poke.md

@@ -0,0 +1,5 @@
+---
+'spiceflow': patch
+---
+
+Clean up leftover React Server Components migration artifacts by removing unused framework-only types and stale exports, and harden the new `@vitejs/plugin-rsc` flow. This update ensures server redirects emit a correct `content-type` header, removes dead exports like `RscHandlerResult`, and makes client action refresh handling safer by setting payload updates before awaiting action results.

.changeset/five-toes-learn.md

@@ -0,0 +1,5 @@
+---
+'spiceflow': patch
+---
+
+initial rsc release

.changeset/pre.json

@@ -0,0 +1,12 @@
+{
+  "mode": "pre",
+  "tag": "rsc",
+  "initialVersions": {
+    "openapi-schema-diff": "0.0.1",
+    "spiceflow": "1.6.1",
+    "how-is-this-not-illegal": "0.1.0"
+  },
+  "changesets": [
+    "five-toes-learn"
+  ]
+}

.gitignore

@@ -18,4 +18,6 @@ __pycache__
 debug
 .env
 .last-run.json
-.react-router
+.react-router
+opensrc
+/di

.gitmodules

@@ -1,3 +0,0 @@
-[submodule "openapi-schema-diff"]
-	path = openapi-schema-diff
-	url = https://github.com/remorses/openapi-schema-diff.git

AGENTS.md

@@ -30,6 +30,78 @@ Sometimes tests work directly on database data, using prisma. To run these tests
 Never write tests yourself that call prisma or interact with database or emails. For these asks the user to write them for you.
 
 
+# e2e testing (example-react)
+
+E2e tests live in `example-react/e2e/` and use Playwright (chromium only). The dev server starts automatically via the `webServer` config in `playwright.config.ts`.
+
+## running e2e tests
+
+```bash
+# run from example-react directory, never from root
+cd example-react
+
+# run all e2e tests
+pnpm test-e2e
+
+# filter by test name
+pnpm test-e2e --grep "SSR error"
+
+# run against production build
+pnpm test-e2e-preview
+```
+
+Tests tagged `@dev` are skipped during preview runs; tests tagged `@build` are skipped during dev runs (controlled by `grepInvert` in playwright.config.ts).
+
+## rebuild dist before testing
+
+The Vite SSR middleware imports from `spiceflow/dist/` (the compiled package), NOT from source. If you modify files in `spiceflow/src/`, you must rebuild before e2e tests will pick up the changes:
+
+```bash
+cd spiceflow
+pnpm tsc --noCheck   # --noCheck skips pre-existing type errors
+```
+
+This is the most common reason e2e tests fail after code changes — stale dist files.
+
+## writing e2e tests
+
+- The base URL and port are defined at the top of `basic.test.ts`:
+  ```ts
+  const port = Number(process.env.E2E_PORT || 6174);
+  const baseURL = `http://localhost:${port}`;
+  ```
+- Use `page.goto("/path")` for browser-based tests that need rendering, JS execution, or DOM interaction.
+- Use Node.js `fetch(baseURL + "/path")` directly (not `page.evaluate`) when you need to control HTTP headers like `Origin` — browsers restrict forbidden headers.
+- Use `page.getByTestId()`, `page.getByText()`, `page.getByRole()` for locators. Prefer test-ids for stability.
+- When a `data-testid` matches multiple elements (e.g. multiple counter components on a page), use `.filter({ hasText: "..." })` to disambiguate:
+  ```ts
+  const clientCounter = page.getByTestId("client-counter").filter({ hasText: "Client counter" });
+  await clientCounter.getByRole("button", { name: "+" }).click();
+  ```
+- If a locator's text changes during the test (e.g. HMR edits), do NOT use it through a pre-filtered variable — query the page directly for the new text.
+
+## adding test routes
+
+To add a route for e2e testing, add it in `example-react/src/main.tsx` using the spiceflow API:
+
+```ts
+.page("/my-test-route", async () => {
+    return <MyComponent />;
+})
+```
+
+Client components used in tests should be created in `example-react/src/app/` with a `"use client"` directive.
+
+## HMR tests
+
+- `createEditor("src/app/file.tsx")` from `e2e/helper.ts` edits a file and auto-reverts on dispose.
+- Always call `file[Symbol.dispose]()` or use `try/finally` to restore files after edits.
+- When editing files, make sure the `replace()` string actually exists in the source. For example, `client.tsx` has `name = "Client"` as a default prop — the literal string "Client counter" does NOT exist in the file, so `replace("Client counter", ...)` would be a no-op and the HMR test would silently fail.
+- **Client HMR preserves state**: editing a client component triggers React Fast Refresh without a server re-render. Client state is preserved. Vite's SSR environment logs `page reload` internally but the browser does not actually reload — Fast Refresh handles it.
+- **Server HMR preserves server state**: editing a server component triggers RSC HMR. Server-side state (e.g. counters stored in module scope) is preserved. Client state is also preserved because no full page reload occurs.
+- The home page has a `serverRenderCount` counter (`data-testid="server-render-count"`) that increments on each RSC render. Use it in tests to verify whether a server re-render happened.
+
+
 # website
 
 the website uses react-router v7.

README.md

@@ -16,6 +16,7 @@ Spiceflow is a lightweight, type-safe API framework for building web services us
 - Can easily generate OpenAPI spec based on your routes
 - Native support for [Fern](https://github.com/fern-api/fern) to generate docs and SDKs (see example docs [here](https://remorses.docs.buildwithfern.com))
 - Support for [Model Context Protocol](https://modelcontextprotocol.io/) to easily wire your app with LLMs
+- Full-stack React framework with React Server Components (RSC), server actions, layouts, and automatic client code splitting
 - Type safe RPC client generation
 - Simple and intuitive API
 - Uses web standards for requests and responses
@@ -1563,3 +1564,135 @@ export const client: SpiceflowClient.Create<App> = createSpiceflowClient<App>(
   {},
 )
 ```
+
+## React Framework (RSC)
+
+Spiceflow includes a full-stack React framework built on React Server Components (RSC). It uses Vite with `@vitejs/plugin-rsc` under the hood. Server components run on the server by default, and you use `"use client"` to mark interactive components that need to run in the browser.
+
+### Setup
+
+Install the dependencies and create a Vite config:
+
+```bash
+npm install spiceflow react react-dom
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { spiceflowPlugin } from 'spiceflow/dist/vite'
+
+export default defineConfig({
+  plugins: [
+    spiceflowPlugin({
+      entry: './src/main.tsx',
+    }),
+  ],
+})
+```
+
+### App Entry (Server Component)
+
+The entry file defines your routes using `.page()` for pages and `.layout()` for layouts. This file runs in the RSC environment on the server.
+
+```tsx
+// src/main.tsx
+import { Spiceflow } from 'spiceflow'
+import { Counter } from './app/counter'
+
+const app = new Spiceflow()
+  .layout('/*', async ({ children }) => {
+    return (
+      <html>
+        <head>
+          <meta charSet="UTF-8" />
+        </head>
+        <body>{children}</body>
+      </html>
+    )
+  })
+  .page('/', async () => {
+    // This runs on the server — you can fetch data, access databases, etc.
+    const data = await fetchSomeData()
+    return (
+      <div>
+        <h1>Welcome</h1>
+        <p>Server-rendered data: {data.message}</p>
+        <Counter />
+      </div>
+    )
+  })
+  .page('/about', async () => {
+    return <div><h1>About</h1></div>
+  })
+
+export default app
+```
+
+### Client Components
+
+Mark interactive components with `"use client"` at the top of the file. These are hydrated in the browser and can use hooks like `useState`.
+
+```tsx
+// src/app/counter.tsx
+'use client'
+
+import { useState } from 'react'
+
+export function Counter() {
+  const [count, setCount] = useState(0)
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={() => setCount(count + 1)}>+</button>
+    </div>
+  )
+}
+```
+
+### Server Actions
+
+Use `"use server"` to define functions that run on the server but can be called from client components (e.g. form actions).
+
+```tsx
+// src/app/actions.tsx
+'use server'
+
+export async function submitForm(formData: FormData) {
+  const name = formData.get('name')
+  await saveToDatabase(name)
+}
+```
+
+### Client Code Splitting
+
+Code splitting of client components is **automatic** — you don't need `React.lazy()` or dynamic `import()`. Each `"use client"` file becomes a separate chunk, and the browser only loads the chunks needed for the current page.
+
+**How it works:** when the RSC flight stream is sent to the browser, it contains references to client component chunks rather than the actual code. The browser resolves and loads only the chunks referenced on the current page. If route `/about` uses `<Map />` and route `/dashboard` uses `<Chart />`, visiting `/about` will never download the Chart component's JavaScript.
+
+**Avoid barrel files with `"use client"`.** If you have a single file with `"use client"` that re-exports many components, all of them end up in one chunk — defeating code splitting. Instead, put `"use client"` in each individual component file:
+
+```tsx
+// BAD — one big chunk for everything
+// src/components/index.tsx
+'use client'
+export { Chart } from './chart'
+export { Map } from './map'
+export { Table } from './table'
+```
+
+```tsx
+// GOOD — each component is its own chunk
+// src/components/chart.tsx
+'use client'
+export function Chart() { /* ... */ }
+
+// src/components/map.tsx
+'use client'
+export function Map() { /* ... */ }
+
+// Re-export barrel has no directive, just passes through
+// src/components/index.tsx
+export { Chart } from './chart'
+export { Map } from './map'
+```