Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/.vitepress/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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' },
Expand Down
6 changes: 4 additions & 2 deletions docs/guide/pages-routing/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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

Expand Down
101 changes: 101 additions & 0 deletions docs/guide/pages-routing/server-components.md
Original file line number Diff line number Diff line change
@@ -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 <h1>Hello, world!</h1>;
}
```

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 <h1>Hello, {c.req.query('name') ?? 'world'}!</h1>;
}
```

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<typeof loader>;

export const head = defineHead<Props>((_c, { name }) => ({ title: `Hello, ${name}!` }));

export default function Page({ name }: Props) {
return <h1>Hello, {name}!</h1>;
}
```

Void waits for any `defer()` values before calling `head` or rendering the page, including after a form action. Use `InferServerProps<typeof loader>` 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 `<Button label="Save" />`:

```tsx
import styles from './Button.module.css';

export function Button({ label }: { label?: string }) {
return <button class={styles.button}>{label ?? 'Press me!'}</button>;
}
```

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 <main>{children}</main>;
}
```

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.
3 changes: 2 additions & 1 deletion docs/reference/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
Expand All @@ -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 |
Expand Down
4 changes: 2 additions & 2 deletions docs/reference/cli/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,14 +33,14 @@ void init [--tsconfig] [--github] [--git | --no-git]
[--toolchain <name>] [--framework <name>] [--starter <name>] [--deploy <target>]
```

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` |

Expand Down
2 changes: 1 addition & 1 deletion packages/void/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
15 changes: 15 additions & 0 deletions packages/void/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
1 change: 1 addition & 0 deletions packages/void/skills/void/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
Expand Down
Loading
Loading