diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 8129bf1ca..421037d3b 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -315,6 +315,7 @@ export default extendConfig(
collapsed: true,
items: [
{ text: 'Overview', link: '/guide/pages-routing/overview' },
+ { text: 'Server Components', link: '/guide/pages-routing/server-components' },
{ text: 'Layouts & Shared Data', link: '/guide/pages-routing/layouts' },
{ text: 'Loaders & Props', link: '/guide/pages-routing/loaders' },
{ text: 'Actions & Forms', link: '/guide/pages-routing/actions-and-forms' },
diff --git a/docs/guide/pages-routing/overview.md b/docs/guide/pages-routing/overview.md
index 5667d48c1..a766fc0af 100644
--- a/docs/guide/pages-routing/overview.md
+++ b/docs/guide/pages-routing/overview.md
@@ -5,6 +5,8 @@ outline: deep
# Pages Routing
+To render JSX as HTML without a framework adapter or browser hydration, see [Server Components](./server-components).
+
Put UI components in `pages/` to make them routes. A page's server loader returns data, and the component receives it as props. This pattern is inspired by [Inertia.js](https://inertiajs.com/) and works with React, Vue, Svelte, and Solid.
Pages mode starts when a `pages/` directory exists. It can live alongside `routes/`: use pages for UI and routes for APIs. Page components normally run on the server for the first render and in the browser for navigation and interaction.
@@ -13,9 +15,9 @@ You can also use your own client-side router and call Void's APIs with [typed fe
## Setup
-In an empty project, `void init` can set up Pages for you. Choose Vite+ or plain Vite, then React, Vue, Svelte, or Solid and a database or static starter. The generated app includes the matching Vite config and page files.
+In an empty project, `void init` can set up Pages for you. Choose Vite+ or plain Vite, then **None** for built-in server components or choose React, Vue, Svelte, or Solid. The generated app includes the matching Vite config and page files.
-If you're adding Pages mode manually, install a framework adapter alongside `void`:
+If you're adding Pages mode manually and want hydration, install a framework adapter alongside `void`:
::: code-group
diff --git a/docs/guide/pages-routing/server-components.md b/docs/guide/pages-routing/server-components.md
new file mode 100644
index 000000000..d5e5d8a0e
--- /dev/null
+++ b/docs/guide/pages-routing/server-components.md
@@ -0,0 +1,101 @@
+# Server Components
+
+Server components are Void Pages that render to HTML without a framework adapter or browser hydration. Choose **None** when creating a Void project to start with one, or use `--framework none`.
+
+Create `pages/index.server.tsx` to serve `/`:
+
+```tsx
+export default function Page() {
+ return
Hello, world!
;
+}
+```
+
+Use `pages/about.server.tsx` or `pages/about/index.server.tsx` for `/about`. Void renders the default export. A `.server.*` file that only exports a loader or actions is still a companion to an adapter page.
+
+Void compiles server views and their imported JSX components with [Hono JSX](https://hono.dev/docs/guides/jsx). For TypeScript editor support, set these options in your `tsconfig.json`:
+
+```json
+{
+ "compilerOptions": {
+ "jsx": "react-jsx",
+ "jsxImportSource": "void/jsx"
+ }
+}
+```
+
+In a mixed project, keep the adapter's TypeScript settings and use `/** @jsxImportSource void/jsx */` in files written for server JSX.
+
+## Props, async work, and styles
+
+Without a `loader`, the page's default export receives the request context (`CloudContext`). You can read query and route parameters directly, or omit the argument if you don't need the request:
+
+```tsx
+import type { CloudContext } from 'void';
+
+export default function Page(c: CloudContext) {
+ return
Hello, {c.req.query('name') ?? 'world'}!
;
+}
+```
+
+If you export a `loader`, the page receives the loader's props instead of the request context, even if the loader returns `{}`:
+
+```tsx
+// pages/greeting.server.tsx
+import { defineHandler, defineHead, type InferProps } from 'void';
+
+export const loader = defineHandler((c) => ({
+ name: c.req.query('name') ?? 'world',
+}));
+
+type Props = InferProps;
+
+export const head = defineHead((_c, { name }) => ({ title: `Hello, ${name}!` }));
+
+export default function Page({ name }: Props) {
+ return
Hello, {name}!
;
+}
+```
+
+Void waits for any `defer()` values before calling `head` or rendering the page, including after a form action. Use `InferServerProps` to infer the resolved types for a loader that uses `defer()`. There are no loading placeholders or browser-side updates. Without a loader, `head(c, props)` still receives the context first and an empty props object second.
+
+Imported components receive the props you pass in JSX. For example, put this component outside `pages/`, import it in your page, and render ``:
+
+```tsx
+import styles from './Button.module.css';
+
+export function Button({ label }: { label?: string }) {
+ return ;
+}
+```
+
+Pages, layouts, and imported components can be async. Void runs their bodies when rendering and awaits their results before sending the document. CSS and CSS modules imported by a page or its components are included in the document without shipping the component code to the browser.
+
+Import server JSX types and helpers such as `FC`, `memo`, `ErrorBoundary`, `createContext`, and `useContext` from `void/jsx`. Calling hooks or reactive primitives from React, Solid, or another client renderer is not supported. Use a hydrated adapter page when you need client state, event handlers, or effects.
+
+Read Hono context before the first `await` in an async component for portability. On Cloudflare Workers, reading it after an `await` requires the `nodejs_compat` compatibility flag.
+
+## Layouts and not-found views
+
+Default-export a component in `pages/layout.server.tsx` to wrap server pages. A layout receives the request context and the child JSX as its second argument:
+
+```tsx
+import type { CloudContext } from 'void';
+import type { Child } from 'void/jsx';
+import './site.css';
+
+export default function Layout(_c: CloudContext, children: Child) {
+ return {children};
+}
+```
+
+On a server page, export `const layout = 'landing'` to replace the innermost layout with the nearest `_layouts/landing.server.tsx`. Use `'!landing'` to replace the entire chain, or `false` to render without a layout. You cannot set `ssr = false` on a server component.
+
+Default-export a component in `pages/_not-found.server.tsx` to render a custom 404. A server page whose loader returns a 404 uses the nearest matching server not-found view and retains the applicable layouts.
+
+Server and adapter pages may live in the same project, but they use separate layout trees. Use regular links to navigate to server pages; they render a new document instead of updating a hydrated page.
+
+## Prerendering
+
+Server pages use the same [prerendering options](../edge/prerendering.md) as other Pages. Export `prerender = true` to opt in, or `prerender = false` to opt out of [static output](../ssg.md) for a page. For a dynamic route, export `getPrerenderPaths()` to enumerate the URLs to generate. Prerendering includes the title and metadata returned by `head`. Leave pages that depend on a visitor's session on request-time rendering.
+
+See the [Server Components playground](https://github.com/voidzero-dev/void/tree/main/playground/server-components) for runnable examples.
diff --git a/docs/reference/api.md b/docs/reference/api.md
index 05a09b43d..de54359f5 100644
--- a/docs/reference/api.md
+++ b/docs/reference/api.md
@@ -37,7 +37,7 @@ Import Void's app-facing APIs from these paths:
| Import path | Contents |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `void` | `voidPlugin`, handler/type re-exports, `defer`, `Deferred`, `DeferredState`, `InferProps`, `HeadConfig`, `HeadDescriptor` |
+| `void` | `voidPlugin`, handler/type re-exports, `defer`, `Deferred`, `DeferredState`, `InferProps`, `InferServerProps`, `HeadConfig`, `HeadDescriptor` |
| `void/handler` | `defineHandler`, `defineMiddleware`, `basicAuth`, `defineScheduled`, `defineQueue`, `defineRender`, `defineHead`, types |
| `void/auth` | `defineAuth`, `getUser`, `getSession`, `requireAuth`, `AuthUser`, `AuthSession`, `AuthState` |
| `void/client` | `fetch`, `fetchStream`, `FetchError`, `auth`, `createAuthClient`, `AuthUser`, `AuthSession`, `AuthState` |
@@ -49,6 +49,7 @@ Import Void's app-facing APIs from these paths:
| `void/sse/client` | `connectEventStream`, browser `EventSource` wrapper types |
| `void/live` | `defineLiveStream`, SSE topic fanout runtime types. Server-only. |
| `void/live/client` | `connectLiveStream`, browser helper for one SSE connection plus POST subscribe/unsubscribe control. |
+| `void/jsx` | [Hono JSX](https://hono.dev/docs/guides/jsx) types and helpers for [Server Components](../guide/pages-routing/server-components), including `FC`, `ErrorBoundary`, `memo`, `createContext`, and `useContext`. |
| `void/response` | `convertReturnValue` |
| `void/validator` | `runValidation`, `ValidatorSlots`, `HandlerInput` |
| `void/drizzle-zod` | Re-exports [`drizzle-zod`](https://orm.drizzle.team/docs/zod) for schema-derived Zod validators for Drizzle tables |
diff --git a/docs/reference/cli/setup.md b/docs/reference/cli/setup.md
index cdaeba5a1..8dbb077ea 100644
--- a/docs/reference/cli/setup.md
+++ b/docs/reference/cli/setup.md
@@ -33,14 +33,14 @@ void init [--tsconfig] [--github] [--git | --no-git]
[--toolchain ] [--framework ] [--starter ] [--deploy ]
```
-Set up a new or existing Void project. In an empty directory, choose Vite+ or Vite, a framework, and a D1, PostgreSQL, MySQL, or Static Pages starter. The new app's `void.config.ts` turns on [`routing.typedRoutes`](../config.md#routing-typedroutes).
+Set up a new or existing Void project. In an empty directory, choose Vite+ or Vite, a framework (or **None** for built-in [Server Components](../../guide/pages-routing/server-components)), and a D1, PostgreSQL, MySQL, or Static Pages starter. The new app's `void.config.ts` turns on [`routing.typedRoutes`](../config.md#routing-typedroutes).
Pass your choices as flags to scaffold from a script or coding agent:
| Flag | Values |
| ------------- | ----------------------------------------- |
| `--toolchain` | `vite-plus`, `vite` |
-| `--framework` | `react`, `vue`, `svelte`, `solid` |
+| `--framework` | `none`, `react`, `vue`, `svelte`, `solid` |
| `--starter` | `sqlite`, `postgresql`, `mysql`, `static` |
| `--deploy` | `cloudflare`, `void`, `none` |
diff --git a/packages/void/AGENTS.md b/packages/void/AGENTS.md
index c8641f6ac..ae1611bf4 100644
--- a/packages/void/AGENTS.md
+++ b/packages/void/AGENTS.md
@@ -194,7 +194,7 @@ page-action and URL clients share `interpolateRouteParams()` for both syntaxes.
HTTP methods are determined by **named exports** in each file (detected by `detect-exports.ts` via `parseSync`), not by filename suffixes. Files/dirs starting with `_` are ignored by the scanner.
-`listRouteFiles()` uses `ROUTE_EXTENSIONS`, shared with HTTP/WebSocket filename parsing, resource-name inference, and route binding inference. Both route scanners use it, with `isWebSocketPatternFile()` sharing the WebSocket filename regex to distinguish `.ws.*` files. `listConventionFiles()` keeps fixed script extensions for crons and queues. Void sets no JSX options: route JSX follows framework plugins, tsconfig (TS files only) or `oxc.jsx`. Page `.server.tsx` and `.server.jsx` companions supply server metadata and handlers; exclude them from component inventories and component manifests.
+`listRouteFiles()` uses `ROUTE_EXTENSIONS`, shared with HTTP/WebSocket filename parsing, resource-name inference, and route binding inference. Both route scanners use it, with `isWebSocketPatternFile()` sharing the WebSocket filename regex to distinguish `.ws.*` files. `listConventionFiles()` keeps fixed script extensions for crons and queues. HTTP route JSX follows framework plugins, tsconfig (TS files only) or `oxc.jsx`. A Pages `.server.*` file with a runtime default export renders through built-in Hono JSX; handler-only companions stay out of view inventories. Keep server views and their layout/boundary trees out of adapter manifests. The client build can traverse the server view's style imports but must not bundle its JavaScript.
The recorded `env` is enforced by `isRouteEnabledForEnvironment()`. The scanners take an optional `environment` (`'dev' | 'prod'`); when it is omitted no filtering happens. `dev` is the Vite dev server, `prod` is every build, `void deploy`, and `vite preview`. A dev-only route is absent from the production bundle, types, generated route/WebSocket config, and inferred bindings. `void prepare` boots no Vite, passes no `environment`, and generates types for both environments. `voidPlugin()` scans unfiltered source during construction for binding-name reservation and plugin membership, then recomputes environment-specific bindings in its `config` hook before emitting Cloudflare config. Binding inference filters recognized route files under `paths.routesDir`, and (with `filterPages`, off for framework apps) Void page files and their `.server` companions under `paths.pagesDir`, read with `pageFileEnvironment()`. The suffix has no effect in `middleware/`, `crons/`, `queues/`, or other source files.
diff --git a/packages/void/package.json b/packages/void/package.json
index 040acf123..070c09ff5 100644
--- a/packages/void/package.json
+++ b/packages/void/package.json
@@ -75,6 +75,21 @@
"import": "./dist/runtime/handler/index.mjs",
"require": "./dist/runtime/handler/index.mjs"
},
+ "./jsx": {
+ "types": "./dist/runtime/jsx/index.d.mts",
+ "import": "./dist/runtime/jsx/index.mjs",
+ "require": "./dist/runtime/jsx/index.mjs"
+ },
+ "./jsx/jsx-runtime": {
+ "types": "./dist/runtime/jsx/jsx-runtime.d.mts",
+ "import": "./dist/runtime/jsx/jsx-runtime.mjs",
+ "require": "./dist/runtime/jsx/jsx-runtime.mjs"
+ },
+ "./jsx/jsx-dev-runtime": {
+ "types": "./dist/runtime/jsx/jsx-dev-runtime.d.mts",
+ "import": "./dist/runtime/jsx/jsx-dev-runtime.mjs",
+ "require": "./dist/runtime/jsx/jsx-dev-runtime.mjs"
+ },
"./response": {
"types": "./dist/runtime/handler/response.d.mts",
"import": "./dist/runtime/handler/response.mjs",
diff --git a/packages/void/skills/void/SKILL.md b/packages/void/skills/void/SKILL.md
index f36ee0b6e..542eb608e 100644
--- a/packages/void/skills/void/SKILL.md
+++ b/packages/void/skills/void/SKILL.md
@@ -76,6 +76,7 @@ Use `void deploy --skip-migrations` when database migrations run separately; it
| Auth login/logout/whoami | `docs/reference/cli/auth.md` |
| Overview / introduction | `docs/guide/index.md` |
| API surface details | `docs/reference/api.md` |
+| Server Components without an adapter | `docs/guide/pages-routing/server-components.md` |
| Meta framework integration | `docs/integrations/frameworks/*.md` |
| Coding agent setup | `docs/integrations/agents.md` |
| Node.js / Bun / Deno targets | `docs/integrations/nodejs-bun-deno.md` |
diff --git a/packages/void/src/cli/help.ts b/packages/void/src/cli/help.ts
index b028c9000..508877295 100644
--- a/packages/void/src/cli/help.ts
+++ b/packages/void/src/cli/help.ts
@@ -130,7 +130,10 @@ const HELP_TREE: HelpTree = {
{ command: '--git', description: 'Initialize a Git repository without prompting' },
{ command: '--no-git', description: 'Skip Git repository initialization' },
{ command: '--toolchain ', description: 'Scaffold with vite-plus or vite' },
- { command: '--framework ', description: 'Scaffold with react, vue, svelte, or solid' },
+ {
+ command: '--framework ',
+ description: 'Scaffold with none, react, vue, svelte, or solid',
+ },
{
command: '--starter ',
description: 'Scaffold the sqlite, postgresql, mysql, or static starter',
diff --git a/packages/void/src/cli/init.ts b/packages/void/src/cli/init.ts
index 740dd6834..8fcb13575 100644
--- a/packages/void/src/cli/init.ts
+++ b/packages/void/src/cli/init.ts
@@ -2260,11 +2260,14 @@ function scaffoldPagesApp(
starterMode,
toolchain,
voidPackageSpec: resolveScaffoldDependencySpec(root, 'void', getOwnVersion()),
- adapterPackageSpec: resolveScaffoldDependencySpec(
- root,
- SCAFFOLD_FRAMEWORKS[framework].adapterPackage,
- getOwnVersion(),
- ),
+ adapterPackageSpec:
+ framework === 'none'
+ ? ''
+ : resolveScaffoldDependencySpec(
+ root,
+ SCAFFOLD_FRAMEWORKS[framework].adapterPackage,
+ getOwnVersion(),
+ ),
});
let pkg: JsonObject = {};
diff --git a/packages/void/src/cli/template.ts b/packages/void/src/cli/template.ts
index 18c7c10db..c54ca84cb 100644
--- a/packages/void/src/cli/template.ts
+++ b/packages/void/src/cli/template.ts
@@ -18,7 +18,7 @@ export const SCAFFOLD_GITIGNORE_LINES = [
'.DS_Store',
] as const;
-export type ScaffoldFramework = 'react' | 'vue' | 'svelte' | 'solid';
+export type ScaffoldFramework = 'none' | 'react' | 'vue' | 'svelte' | 'solid';
export type ScaffoldStarterMode = 'sqlite' | 'postgresql' | 'mysql' | 'static';
export type ScaffoldToolchain = 'vite-plus' | 'vite';
@@ -56,6 +56,7 @@ const REACT_SCAFFOLD_COMPILER_DEV_DEPENDENCIES = {
} as const;
export const SCAFFOLD_FRAMEWORK_OPTIONS = [
+ { value: 'none', label: 'None', hint: 'Server-rendered JSX Pages without a framework adapter.' },
{ value: 'react', label: 'React', hint: 'TSX Pages starter with the React adapter.' },
{ value: 'vue', label: 'Vue', hint: 'Vue SFC Pages starter with the Vue adapter.' },
{ value: 'svelte', label: 'Svelte', hint: 'Svelte 5 Pages starter with the Svelte adapter.' },
@@ -79,6 +80,16 @@ type ScaffoldFrameworkConfig = {
};
export const SCAFFOLD_FRAMEWORKS: Record = {
+ none: {
+ label: 'Void',
+ docsUrl: 'https://void.cloud/guide/pages-routing/server-components',
+ adapterPackage: '',
+ adapterImport: '',
+ adapterPlugin: '',
+ pageExtension: 'server.tsx',
+ dependencies: {},
+ tsconfigCompilerOptions: { jsx: 'react-jsx', jsxImportSource: 'void/jsx' },
+ },
react: {
label: 'React',
docsUrl: 'https://react.dev/',
@@ -158,7 +169,7 @@ export function detectScaffoldFrameworkFromDependencies(
for (const [framework, config] of Object.entries(SCAFFOLD_FRAMEWORKS) as Array<
[ScaffoldFramework, ScaffoldFrameworkConfig]
>) {
- if (config.adapterPackage in deps) {
+ if (config.adapterPackage && config.adapterPackage in deps) {
return framework;
}
}
@@ -199,12 +210,16 @@ export function createPagesStarterTemplate(options: {
'pages/vite-env.d.ts': '/// \n',
'public/stack.svg': readFileSync(join(assets, 'stack.svg'), 'utf8'),
'public/void.svg': readFileSync(join(assets, 'void.svg'), 'utf8'),
- [`public/${framework}.svg`]: readFileSync(join(assets, `${framework}.svg`), 'utf8'),
'public/icons.svg': readFileSync(join(assets, 'icons.svg'), 'utf8'),
};
+ if (framework !== 'none') {
+ files[`public/${framework}.svg`] = readFileSync(join(assets, `${framework}.svg`), 'utf8');
+ }
if (starterMode !== 'static') {
- files['pages/index.server.ts'] = getIndexServer();
+ if (framework !== 'none') {
+ files['pages/index.server.ts'] = getIndexServer();
+ }
files['routes/api/hello.ts'] = getHelloRoute(config.label, starterMode);
files['db/schema.ts'] = getSchemaFile(starterMode);
files['db/seed.ts'] = getSeedFile();
@@ -228,7 +243,7 @@ export function createPagesStarterTemplate(options: {
void: voidPackageSpec,
...SCAFFOLD_BASE_DEV_DEPENDENCIES,
...(toolchain === 'vite-plus' ? SCAFFOLD_VITE_PLUS_DEV_DEPENDENCIES : {}),
- [config.adapterPackage]: adapterPackageSpec,
+ ...(config.adapterPackage && { [config.adapterPackage]: adapterPackageSpec }),
...config.devDependencies,
},
files,
@@ -236,6 +251,13 @@ export function createPagesStarterTemplate(options: {
}
function getViteConfig(framework: ScaffoldFramework, config: ScaffoldFrameworkConfig): string {
+ if (framework === 'none') {
+ return `import { defineConfig } from "vite";
+import { voidPlugin } from "void";
+
+export default defineConfig({ plugins: [voidPlugin()] });
+`;
+ }
if (framework === 'react') {
return `import { defineConfig } from "vite";
import { voidPlugin } from "void";
@@ -348,6 +370,22 @@ export default defineSeed(async ({ db, schema }) => {
}
function getIndexPage(framework: ScaffoldFramework, starterMode: ScaffoldStarterMode): string {
+ if (framework === 'none') {
+ return `${starterMode === 'static' ? 'export const prerender = true;\n' : ''}
+import "./style.css";
+
+export default function Page() {
+ return (
+
+
+