Documentation
The build turns your app into a portable set of ESM artifacts plus manifests, described in Build Output. That contract is the center of these docs: every way of shipping a vprs app is a recipe consuming it, and the guides below are organized around the three ways people actually ship.
Start here
- Starter (vprs-starter) — minimal app to clone: one build shipping CDN snapshots plus a per-request Vercel route (shape 3 below)
- Getting Started — install, first page, dev server, build, deploy
- Build Output — the contract: what the build emits and how it is meant to be consumed
- Migrating to 4.0 — declare a runner, install react-server-loader as a peer
Three ways to ship
One build, three deploy shapes. Pick the one that matches what you're building.
1. A content site on dumb hosting (GitHub Pages, FTP, S3, any CDN).
dist/static/ is the whole deployment: prerendered HTML, .rsc payloads
for client-side navigation, hashed assets. No runtime to operate, and
build.edge: false skips the server bundle this shape never uses.
Getting Started → Deploy ·
Examples → Static Site ·
Build Output → Turning outputs off
2. RSC inside a server you own (plain Node, Express, a serverless
function). createRequestHandler serves the static output correctly,
dispatches "use server" actions through the sealed
baked gate, and renders dynamic routes per request through the
single-isolate edge bundle: flash-free streaming SSR from one
Web fetch handler, no workers and no --conditions. Cloudflare Workers
and Deno Deploy work via the webpack transport's baked consumer.
Build Output → Using the ESM modules in a server ·
Examples → Dynamic Server
3. Mixed rendering from one build. Prerender the content routes, render the per-request ones dynamically, and ship both as one deploy with client-side navigation across the boundary. Build Output → Where it runs · Configuration → Transport
Reference
- Routing — the file-based router: params, loaders, nested layouts, prerendering, client-side
Link - Configuration — all plugin options
- CSS Handling — inline vs linked CSS, CSS modules
- Server Actions —
"use server", form actions - Storybook — rendering RSC components in stories
- Examples — static site, dynamic server, custom routing
- Troubleshooting — common errors and fixes
- React Compatibility — supported React versions, the vendored transport, and the type system
- API Reference — exports, types, components, defaults
- Comparison — how vprs differs from Next.js, Waku, and
@vitejs/plugin-rsc
Maintenance
- Releasing — version bumps, publishing, demo updates
Internals (contributors)
- Architecture — condition system, module structure, plugin composition
- Building on the contract — using vprs as the base of your own framework
- Transformer — directive handling and code transforms
- Workers — the RSC and HTML worker threads
- Module-resolution escape hatches —
external,noExternal,optimizeDeps, virtual stubs, vendor aliases, and how to pick - Advanced topics
- Testing — the fixture/
doBuildharness - Error handling · Debugging · Common issues
Design notes (not user-facing)
Specs for work that is in progress or was reasoned through once. They describe intent, not necessarily what ships today.