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 `; +} +``` + +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 ( +
+ Void +

Start building with Void

+

Edit pages/index.server.tsx to update this page.

+ Server Components guide +
+ ); +} +`; + } const { label, docsUrl } = SCAFFOLD_FRAMEWORKS[framework]; const hasDatabase = starterMode !== 'static'; const description = @@ -485,7 +523,7 @@ ${body} } } -function getMessagesDemo(framework: ScaffoldFramework): string { +function getMessagesDemo(framework: Exclude): string { const empty = `

No messages yet. Run void db seed to load the sample row from db/seed.ts.

`; diff --git a/packages/void/src/index.ts b/packages/void/src/index.ts index 94959ebe3..519bca213 100644 --- a/packages/void/src/index.ts +++ b/packages/void/src/index.ts @@ -33,6 +33,7 @@ import { inferBindingsFromSource } from './inference/walk.ts'; import { resolveLocalD1Target, writeLocalD1PersistState } from './local-d1.ts'; import { voidLog, voidWarn } from './log.ts'; import { pagesDevCssAssetsPlugin } from './pages/dev-css-assets.ts'; +import { serverComponentsPlugin } from './pages/server-components-plugin.ts'; import { readVoidDevCredentials, runAiSetupPrompt } from './plugin-ai-setup.ts'; import { bindingRuntimePlugin } from './plugin-binding-runtime.ts'; import { createClientStubsPlugin } from './plugin-client-stubs.ts'; @@ -859,6 +860,7 @@ export function voidPlugin(options?: { envPlugin, serverRuntimeOptimizerPlugin, envSchemaPlugin(root), + ...serverComponentsPlugin(root, paths.pagesDir), ...pagesDevCssAssetsPlugin(root, devTriggerToken), routingPlugin(root, { getApplicationAnalysis, @@ -1016,6 +1018,7 @@ export function voidPlugin(options?: { serverRuntimeOptimizerPlugin, bindingRuntimePlugin(bindingNames), ...(bindings.needsSandbox ? [createSandboxSdkResolvePlugin()] : []), + ...serverComponentsPlugin(root, paths.pagesDir), ...pagesDevCssAssetsPlugin(root, devTriggerToken), routes, drizzlePlugin(root, true, dialect, { @@ -1085,7 +1088,7 @@ export type { QueueMap } from './runtime/queues/index.ts'; export { defer } from './pages/defer.ts'; -export type { Deferred, DeferredState, InferProps } from './pages/defer.ts'; +export type { Deferred, DeferredState, InferProps, InferServerProps } from './pages/defer.ts'; export type { HeadConfig, HeadDescriptor } from './pages/head.ts'; diff --git a/packages/void/src/pages/boundary-plans.ts b/packages/void/src/pages/boundary-plans.ts index d9de7e6fa..f069e4ef3 100644 --- a/packages/void/src/pages/boundary-plans.ts +++ b/packages/void/src/pages/boundary-plans.ts @@ -2,6 +2,7 @@ import { resolveEffectiveLayoutEntries } from './layout-resolution.ts'; import type { PageBoundaryDefinition, PageScanResult } from './types.ts'; export type BoundaryPlan = { + serverView?: boolean; id: string; componentId: string; filePath: string; @@ -36,9 +37,15 @@ export function createBoundaryManifest(scan: PageScanResult): BoundaryManifest { const layoutKey = (id: string) => (pageIds.has(id) ? id.replace(/(^|\/)([^/]+)$/, '$1_$2') : id); for (const page of scan.pages) { const directory = page.componentPath.split('/').slice(0, -1).join('/'); - const layouts = resolveEffectiveLayoutEntries(page, scan.layouts, scan.namedLayouts); + const sameRenderer = (entry: { serverView?: boolean }) => + Boolean(entry.serverView) === Boolean(page.serverView); + const layouts = resolveEffectiveLayoutEntries( + page, + scan.layouts.filter(sameRenderer), + scan.namedLayouts.filter(sameRenderer), + ); const candidates = (scan.boundaries ?? []) - .filter((b) => encloses(b.directory, directory)) + .filter((b) => sameRenderer(b) && encloses(b.directory, directory)) .sort((a, b) => b.directory.length - a.directory.length); const add = (boundary: PageBoundaryDefinition) => { const retained = layouts @@ -66,18 +73,24 @@ export function createBoundaryManifest(scan: PageScanResult): BoundaryManifest { })), }; } - const root = scan.boundaries?.find((b) => b.kind === 'not-found' && !b.directory); + const root = + scan.boundaries?.find((b) => b.kind === 'not-found' && !b.directory && b.serverView) ?? + scan.boundaries?.find((b) => b.kind === 'not-found' && !b.directory); if (root) { - const id = `_void:boundary:root-not-found:${JSON.stringify(scan.layouts.filter((l) => !l.directory).map((l) => l.filePath))}`; + const rootLayouts = scan.layouts.filter( + (l) => !l.directory && Boolean(l.serverView) === Boolean(root.serverView), + ); + const id = `_void:boundary:root-not-found:${JSON.stringify(rootLayouts.map((l) => l.filePath))}`; plans[id] = { id, ...root, source: id, - layouts: scan.layouts - .filter((l) => !l.directory) - .map((l) => layoutKey(l.directory ? l.directory + '/layout' : 'layout')), + layouts: rootLayouts.map((l) => layoutKey(l.directory ? l.directory + '/layout' : 'layout')), }; - const error = scan.boundaries?.find((b) => b.kind === 'error' && !b.directory); + const error = scan.boundaries?.find( + (b) => + b.kind === 'error' && !b.directory && Boolean(b.serverView) === Boolean(root.serverView), + ); const rootErrors: Array = []; if (error) { const errorId = `_void:boundary:root-error:${id}`; diff --git a/packages/void/src/pages/defer.ts b/packages/void/src/pages/defer.ts index ea47e312d..543a35fcb 100644 --- a/packages/void/src/pages/defer.ts +++ b/packages/void/src/pages/defer.ts @@ -1,6 +1,7 @@ import type { CloudContext } from '../runtime/handler/index.ts'; -export const DEFERRED: unique symbol = Symbol('deferred'); +// User handlers and the generated renderer can load separate runtime module instances. +export const DEFERRED: unique symbol = Symbol.for('void.pages.deferred.v1'); export type DeferredSentinel = { [DEFERRED]: true; @@ -24,6 +25,16 @@ export type Deferred = DeferredState & Promise; /** Extract the props type from a typed handler (loader). */ export type InferProps = T extends { __output: infer R } ? R : never; +type ResolveDeferredProp = + T extends Deferred ? (undefined extends Value ? Value | null : Value) : T; + +/** Extract server page props, with top-level deferred fields unwrapped. */ +export type InferServerProps = ResolveDeferredProps>; + +type ResolveDeferredProps = { + [Key in keyof Props]: ResolveDeferredProp; +}; + export function defer(resolver: (c: CloudContext) => Promise): Deferred; export function defer(group: string, resolver: (c: CloudContext) => Promise): Deferred; export function defer( @@ -52,7 +63,7 @@ export function separateDeferred(props: Record): { deferredMap: Record; } { const immediateProps: Record = {}; - const deferredMap: Record = {}; + const deferredMap: Record = Object.create(null); for (const [key, value] of Object.entries(props)) { if (value && typeof value === 'object' && DEFERRED in value) { diff --git a/packages/void/src/pages/islands-plugin.ts b/packages/void/src/pages/islands-plugin.ts index f351e3a2a..53c575fd5 100644 --- a/packages/void/src/pages/islands-plugin.ts +++ b/packages/void/src/pages/islands-plugin.ts @@ -152,14 +152,14 @@ export function islandCssFiles( } for (const layout of resolveEffectiveLayoutChain( page, - pageScan.layouts, - pageScan.namedLayouts, + pageScan.layouts.filter((layout) => !layout.serverView), + pageScan.namedLayouts.filter((layout) => !layout.serverView), )) { files.add(normalizePath(resolve(pagesDir, layout.filePath))); } } for (const boundary of pageScan.boundaries ?? []) { - if (componentPattern.test(boundary.filePath)) { + if (!boundary.serverView && componentPattern.test(boundary.filePath)) { files.add(normalizePath(resolve(pagesDir, boundary.filePath))); } } @@ -221,8 +221,8 @@ export function islandStyleRoots(pageScan: PageScanResult, pagesDir: string): Ar } for (const layout of resolveEffectiveLayoutChain( page, - pageScan.layouts, - pageScan.namedLayouts, + pageScan.layouts.filter((layout) => !layout.serverView), + pageScan.namedLayouts.filter((layout) => !layout.serverView), )) { layouts.add(normalizePath(resolve(pagesDir, layout.filePath))); } @@ -231,9 +231,9 @@ export function islandStyleRoots(pageScan: PageScanResult, pagesDir: string): Ar return [ ...layouts, ...pages, - ...(pageScan.boundaries ?? []).map((boundary) => - normalizePath(resolve(pagesDir, boundary.filePath)), - ), + ...(pageScan.boundaries ?? []) + .filter((boundary) => !boundary.serverView) + .map((boundary) => normalizePath(resolve(pagesDir, boundary.filePath))), ]; } diff --git a/packages/void/src/pages/plugin.ts b/packages/void/src/pages/plugin.ts index 705c45318..c08ef4948 100644 --- a/packages/void/src/pages/plugin.ts +++ b/packages/void/src/pages/plugin.ts @@ -65,9 +65,17 @@ export function createPagesPlugin(pagesDir: string, options: CreatePagesPluginOp const normalizedPagesDir = normalizePath(pagesDir); let pendingRescan: Promise | null = null; async function rescanPages(): Promise { - pageScan = existsSync(pagesDir) + const scan = existsSync(pagesDir) ? await scanPages(root, { pagesDir, environment: isDev ? 'dev' : 'prod' }) : null; + pageScan = scan && { + pages: scan.pages.filter((page) => !page.serverView), + layouts: scan.layouts.filter((layout) => !layout.serverView), + namedLayouts: scan.namedLayouts.filter((layout) => !layout.serverView), + ...(scan.boundaries && { + boundaries: scan.boundaries.filter((boundary) => !boundary.serverView), + }), + }; } function runRescan(): Promise { diff --git a/packages/void/src/pages/protocol.ts b/packages/void/src/pages/protocol.ts index eccd6fb45..33fa0112f 100644 --- a/packages/void/src/pages/protocol.ts +++ b/packages/void/src/pages/protocol.ts @@ -71,6 +71,7 @@ type PageHeadHandler = type PageRequestContext = Context | CloudContext; type PageRenderOptions = { renderMode?: PageRenderMode; + serverView?: boolean; /** Dev server build: rejected deferred props keep their raw error message. */ dev?: boolean; boundaries?: { notFound?: string; notFoundErrors?: Array; errors: Array }; @@ -86,6 +87,7 @@ type RenderPage = ( pageObj: PageObject, assetTags: AssetTags, requestUrl: string, + context?: CloudContext, ) => Promise; type RenderPageWithMetadata = RenderPage & { preambleScript?: string; @@ -244,9 +246,12 @@ async function renderWithAssetTags( pageObj: PageObject, assetTags: AssetTags, requestUrl: string, + context?: CloudContext, ): Promise { try { - return await renderFn(pageObj, assetTags, requestUrl); + return context + ? await renderFn(pageObj, assetTags, requestUrl, context) + : await renderFn(pageObj, assetTags, requestUrl); } catch (error) { attachRenderErrorAssetTags(error, assetTags); } @@ -281,13 +286,20 @@ async function renderPageHtml( renderMode: PageRenderMode, renderFn: RenderPageWithMetadata, getAssetTags: GetAssetTags, + serverView?: boolean, ): Promise<{ html: PageRenderResult; assetTags: AssetTags }> { const assetTags = prepareAssetTags(await getAssetTags(c.req.raw, c.env, componentId)); // Keep the request origin in render context, rather than serialized navigation URLs. const html = renderMode === 'client' ? renderClientOnlyPage(pageObj, assetTags, renderFn) - : await renderWithAssetTags(renderFn, pageObj, assetTags, c.req.url); + : await renderWithAssetTags( + renderFn, + pageObj, + assetTags, + c.req.url, + serverView ? c : undefined, + ); return { html, assetTags }; } @@ -433,7 +445,7 @@ export async function recoverPageHttpException( return undefined; } const context = asCloudContext(c); - if (options?.renderMode !== 'island' && needsPageReload(context)) { + if (!options?.serverView && options?.renderMode !== 'island' && needsPageReload(context)) { return legacyPageResponse(context); } return renderPageFailure(context, error, undefined, renderFn, getAssetTags, configHead, options); @@ -529,7 +541,7 @@ async function renderPageFailure( }; try { let response: Response; - if (isPagesRequest(c) && options?.renderMode !== 'island') { + if (!options?.serverView && isPagesRequest(c) && options?.renderMode !== 'island') { response = pageJsonResponse(c, page); } else { const { html, assetTags } = await renderPageHtml( @@ -539,6 +551,7 @@ async function renderPageFailure( options?.renderMode ?? 'server', renderFn, getAssetTags, + options?.serverView, ); response = renderedResponse(c, html, 'text/html; charset=utf-8', assetTags); } @@ -631,6 +644,45 @@ function stripDeferred(props: Record): Record return result; } +async function assignDeferredGroup( + props: Record, + { resolver, keys }: ResolvedDeferredGroup, + c: CloudContext, +): Promise { + const data = await resolver(c); + if (keys.length === 1) { + props[keys[0]] = data ?? null; + } else { + const values = + typeof data === 'object' && data !== null ? (data as Record) : {}; + for (const key of keys) { + props[key] = values[key]; + } + } +} + +async function resolveDeferredProps( + props: Record, + deferredMap: Record, + c: CloudContext, +): Promise { + await Promise.all( + Object.values(deferredMap).map((group) => assignDeferredGroup(props, group, c)), + ); +} + +async function resolveServerViewProps( + props: Record, + c: CloudContext, +): Promise> { + const { immediateProps, deferredMap } = separateDeferred(props); + if (Object.keys(deferredMap).length === 0) { + return props; + } + await resolveDeferredProps(immediateProps, deferredMap, c); + return immediateProps; +} + async function writeRenderResult( writer: WritableStreamDefaultWriter, encoder: TextEncoder, @@ -784,7 +836,7 @@ async function runPageGet( ): Promise { const renderMode = options?.renderMode ?? 'server'; - if (renderMode !== 'island' && needsPageReload(c)) { + if (!options?.serverView && renderMode !== 'island' && needsPageReload(c)) { return legacyPageResponse(c); } @@ -798,6 +850,9 @@ async function runPageGet( try { // Read at render time so per-route middleware can set them before next() const shared = (c.get('shared') as Record | undefined) ?? {}; + if (options?.serverView) { + props = await resolveServerViewProps(props, c); + } const pageHead = headFn ? headFn(c, props) : undefined; const middlewareHead = c.get('headDefaults') as HeadConfig | undefined; const head = resolveRequestHead(c, configHead, middlewareHead, pageHead); @@ -805,16 +860,21 @@ async function runPageGet( varyPagesResponse(c); } - const { immediateProps, deferredMap } = separateDeferred(props); + const { immediateProps, deferredMap }: ReturnType = + options?.serverView + ? { immediateProps: props, deferredMap: {} } + : separateDeferred(props); const hasDeferred = Object.keys(deferredMap).length > 0; if (hasDeferred && (options?.boundaries?.notFound || options?.boundaries?.errors.length)) { c.header('Cache-Control', 'no-store'); } const deferredKeys: Record = {}; - for (const [group, { keys }] of Object.entries(deferredMap)) { - for (const key of keys) { - deferredKeys[key] = group; + if (hasDeferred) { + for (const [group, { keys }] of Object.entries(deferredMap)) { + for (const key of keys) { + deferredKeys[key] = group; + } } } @@ -833,30 +893,19 @@ async function runPageGet( }; // Island pages always render HTML — no Inertia JSON navigation - if (renderMode !== 'island' && isPagesRequest(c)) { + if (!options?.serverView && renderMode !== 'island' && isPagesRequest(c)) { // Prefetch requests: resolve all deferred props inline (plain JSON, no streaming) const isPrefetch = c.req.header('purpose') === 'prefetch'; if (isPrefetch && hasDeferred) { const resolvedProps: Record = { ...immediateProps }; let deferredErrors: Record | undefined; await Promise.all( - Object.entries(deferredMap).map(async ([group, { resolver, keys }]) => { + Object.entries(deferredMap).map(async ([group, deferred]) => { try { - const data = await resolver(c); - if (keys.length === 1) { - resolvedProps[keys[0]] = data ?? null; - } else { - const obj = - typeof data === 'object' && data !== null - ? (data as Record) - : {}; - for (const key of keys) { - resolvedProps[key] = obj[key]; - } - } + await assignDeferredGroup(resolvedProps, deferred, c); } catch (err) { (deferredErrors ??= {})[group] = deferredErrorMessage(err, options?.dev === true); - for (const key of keys) { + for (const key of deferred.keys) { delete resolvedProps[key]; } } @@ -894,6 +943,7 @@ async function runPageGet( renderMode, renderFn, getAssetTags, + options?.serverView, ); if (!hasDeferred) { @@ -1017,14 +1067,17 @@ async function runPageMutation( /** Re-run the GET loader and respond with the page, optionally carrying validation errors. */ async function respondWithPage(errors: Record | null): Promise { - if (needsPageReload(c)) { + if (!options?.serverView && needsPageReload(c)) { return legacyPageResponse(c, errors); } try { return await runLoader(getHandler, c, async (props) => { - const pageObj = buildMutationPageObj(stripDeferred(props), errors); + const pageObj = buildMutationPageObj( + options?.serverView ? await resolveServerViewProps(props, c) : stripDeferred(props), + errors, + ); varyPagesResponse(c); - if (isPagesRequest(c)) { + if (!options?.serverView && isPagesRequest(c)) { return pageJsonResponse(c, pageObj); } const { html, assetTags } = await renderPageHtml( @@ -1034,6 +1087,7 @@ async function runPageMutation( renderMode, renderFn, getAssetTags, + options?.serverView, ); return renderedResponse(c, html, 'text/html; charset=utf-8', assetTags); }); diff --git a/packages/void/src/pages/scan.ts b/packages/void/src/pages/scan.ts index c8478fa68..dd8b6e9d9 100644 --- a/packages/void/src/pages/scan.ts +++ b/packages/void/src/pages/scan.ts @@ -71,6 +71,17 @@ function warnPageSettings(pagesDir: string, warnings: ReadonlyArray): vo } } +function hasServerViewExport(pagesDir: string, file: string): boolean { + return deriveFromSource(join(pagesDir, file), 'server-view-default', (source) => + parseSync(file, source).module.staticExports.some(({ entries }) => + entries.some( + ({ isType, exportName }) => + !isType && (exportName.kind === 'Default' || exportName.name === 'default'), + ), + ), + ); +} + type PageRenderingSource = { componentPath: string; island?: boolean; @@ -346,8 +357,10 @@ export async function scanPages(root: string, options?: PageScanOptions): Promis return { pages: [], layouts: [], namedLayouts: [] }; } - const pattern = `**/*.{${COMPONENT_EXTENSIONS.join(',')}}`; - const files = await glob(pattern, { cwd: pagesDir, absolute: false }); + const files = await glob( + [`**/*.{${COMPONENT_EXTENSIONS.join(',')}}`, `**/*.server.{${ROUTE_EXTENSIONS.join(',')}}`], + { cwd: pagesDir, absolute: false }, + ); const pages: Array = []; const layouts: Array = []; @@ -357,9 +370,28 @@ export async function scanPages(root: string, options?: PageScanOptions): Promis // Glob traversal order can vary between identical scans. Keep layout inventories stable too. for (const file of files.sort()) { const segments = file.split('/'); - const boundary = /^_(error|not-found)(?:\.(dev|prod))?(\.island)?\.(tsx|jsx|vue|svelte)$/.exec( - segments.at(-1)!, - ); + const ext = extname(file); + const stem = basename(file, ext); + const serverView = stem.endsWith('.server') && ROUTE_EXTENSIONS_SET.has(ext); + let base = serverView ? stem.slice(0, -'.server'.length) : stem; + if (serverView) { + if (options?.checkRoutes === false || base.endsWith('.island')) { + continue; + } + const environment = /\.(dev|prod)$/.exec(base)?.[1]; + if (options?.environment && environment && environment !== options.environment) { + continue; + } + if ( + (base.startsWith('_') && !/^_not-found(?:\.(?:dev|prod))?$/.test(base)) || + !hasServerViewExport(pagesDir, file) + ) { + continue; + } + } + const boundary = + (serverView || /\.(tsx|jsx|vue|svelte)$/.test(file)) && + /^_(error|not-found)(?:\.(dev|prod))?(\.island)?$/.exec(base); if (boundary && !segments.slice(0, -1).some((segment) => segment.startsWith('_'))) { const env = boundary[2] as RouteEnvironment | undefined; if (options?.environment && env && env !== options.environment) { @@ -368,7 +400,14 @@ export async function scanPages(root: string, options?: PageScanOptions): Promis const base = file.slice(0, -extname(file).length); if ( boundary[3] || - ROUTE_EXTENSIONS.some((ext) => existsSync(join(pagesDir, `${base}.server.${ext}`))) || + (!serverView && + ROUTE_EXTENSIONS.some((ext) => { + const candidate = `${base}.server.${ext}`; + return ( + existsSync(join(pagesDir, candidate)) && + (boundary[1] === 'error' || !hasServerViewExport(pagesDir, candidate)) + ); + })) || deriveFromSource(join(pagesDir, file), 'page-boundary-layout', (source) => scriptBlocks(source, file).some((script) => readStaticExports(script.filename, script.source, new Set(['layout'])).initializers.has( @@ -387,6 +426,7 @@ export async function scanPages(root: string, options?: PageScanOptions): Promis if ( prior.directory === directory && prior.kind === boundary[1] && + Boolean(prior.serverView) === serverView && (!env || !priorEnv || env === priorEnv) ) { throw new Error(`pages: Ambiguous boundary files '${prior.filePath}' and '${file}'.`); @@ -397,6 +437,7 @@ export async function scanPages(root: string, options?: PageScanOptions): Promis directory, componentId: base, filePath: file, + ...(serverView && { serverView }), }); continue; } @@ -405,12 +446,6 @@ export async function scanPages(root: string, options?: PageScanOptions): Promis continue; } - const ext = extname(file); - let base = basename(file, ext); - if (base.endsWith('.server') && ROUTE_EXTENSIONS_SET.has(ext)) { - continue; - } - // Detect island suffix (.island.tsx, .island.vue, etc.) let island: boolean | undefined; let hasIslandSuffix = false; @@ -434,6 +469,7 @@ export async function scanPages(root: string, options?: PageScanOptions): Promis directory: segments.slice(0, layoutsDirIdx).join('/'), filePath: file, island, + ...(serverView && { serverView }), }); } continue; @@ -445,6 +481,7 @@ export async function scanPages(root: string, options?: PageScanOptions): Promis directory: dir === '.' ? '' : dir, filePath: file, island, + ...(serverView && { serverView }), }); continue; } @@ -452,17 +489,19 @@ export async function scanPages(root: string, options?: PageScanOptions): Promis // Page files — parse as route // Convert component extensions to .ts so the route parser handles them uniformly. // Strip .island suffix before parsing so route patterns are clean. - const parseName = hasIslandSuffix - ? file.replace(`.island${ext}`, '.ts') - : file.replace(ext, '.ts'); + const parseName = serverView + ? file.slice(0, -`.server${ext}`.length) + '.ts' + : hasIslandSuffix + ? file.replace(`.island${ext}`, '.ts') + : file.replace(ext, '.ts'); const route = parseRouteFilename(parseName); // Skip pages for the other environment before reading their companion. if (!isRouteEnabledForEnvironment(route, options?.environment)) { continue; } + const viewStem = file.slice(0, -(serverView ? `.server${ext}` : ext).length); const componentId = - file - .replace(ext, '') + viewStem .replace(/\.island$/, '') .replace(/\/index$/, '') .replace(/^index$/, '') || 'index'; @@ -474,10 +513,10 @@ export async function scanPages(root: string, options?: PageScanOptions): Promis let prerender: ExplicitBoolean; let ssr: ExplicitBoolean; let hasGetPrerenderPaths: boolean | undefined; - const serverBase = hasIslandSuffix ? file.replace(`.island${ext}`, '') : file.replace(ext, ''); + const serverBase = viewStem.replace(/\.island$/, ''); for (const serverExt of ROUTE_EXTENSIONS) { const candidate = `${serverBase}.server.${serverExt}`; - if (existsSync(join(pagesDir, candidate))) { + if (serverView ? candidate === file : existsSync(join(pagesDir, candidate))) { serverPath = candidate; const metadata = deriveFromSource(join(pagesDir, candidate), 'page-server', (source) => @@ -507,6 +546,9 @@ export async function scanPages(root: string, options?: PageScanOptions): Promis }, options, ); + if (serverView && ssr === false) { + throw new Error(`pages: Server component '${file}' cannot set ssr = false.`); + } // Prerender → max revalidate (applies to all pages) if (rendering.shouldPrerender && revalidate === undefined) { @@ -537,6 +579,7 @@ export async function scanPages(root: string, options?: PageScanOptions): Promis params: route.params, catchAll: route.catchAll, componentPath: file, + ...(serverView && { serverView }), serverPath, methods, componentId, @@ -569,7 +612,7 @@ export async function scanPages(root: string, options?: PageScanOptions): Promis // Validate: throw when regular pages are under island layouts for (const page of pages) { - if (page.island) { + if (page.island || page.serverView) { continue; } const dir = dirname(page.componentPath); @@ -599,9 +642,16 @@ export async function scanPages(root: string, options?: PageScanOptions): Promis } continue; } - if (!resolveNamedLayout(name, page.componentId, namedLayouts, page.componentPath)) { + if ( + !resolveNamedLayout( + name, + page.componentId, + namedLayouts.filter((l) => Boolean(l.serverView) === Boolean(page.serverView)), + page.componentPath, + ) + ) { throw new Error( - `pages: Page '${page.componentPath}' specifies layout '${page.layout}', but _layouts/${name}.vue was not found in any ancestor directory.`, + `pages: Page '${page.componentPath}' specifies layout '${page.layout}', but ${page.serverView ? `_layouts/${name}.server.*` : `_layouts/${name}.vue`} was not found in any ancestor directory.`, ); } } diff --git a/packages/void/src/pages/server-components-plugin.ts b/packages/void/src/pages/server-components-plugin.ts new file mode 100644 index 000000000..a8aed6a1d --- /dev/null +++ b/packages/void/src/pages/server-components-plugin.ts @@ -0,0 +1,295 @@ +import { existsSync } from 'node:fs'; +import { readFile } from 'node:fs/promises'; +import MagicString from 'magic-string'; +import { isAbsolute, join, relative } from 'pathslash'; +import { normalizePath, parseSync, transformWithOxc, type Plugin } from 'vite'; +import { staticModuleReferences } from '../shared/module-references.ts'; +import { scanPages } from './scan.ts'; + +export const SERVER_VIEW_QUERY = '?void-server-view'; +const STYLE_QUERY = '?void-server-view-styles'; +const SCRIPT = /\.(?:[cm]?[jt]s|[jt]sx)$/; +const STYLE = /\.(?:css|pcss|postcss|less|sass|scss|styl|stylus|sss)(?:$|\?)/; +const GUARD = 'virtual:void-server-hook:'; +const STYLE_ENTRY = 'virtual:void-server-view-styles'; +const PROJECTED_CSS = '?void-projected-css'; + +export function serverViewStyleId(file: string): string { + return normalizePath(file) + STYLE_QUERY; +} + +const frameworkHooks: Record> = { + react: [ + 'use', + 'useActionState', + 'useCallback', + 'useContext', + 'useDebugValue', + 'useDeferredValue', + 'useEffect', + 'useEffectEvent', + 'useId', + 'useImperativeHandle', + 'useInsertionEffect', + 'useLayoutEffect', + 'useMemo', + 'useOptimistic', + 'useReducer', + 'useRef', + 'useState', + 'useSyncExternalStore', + 'useTransition', + ], + 'react-dom': ['useFormState', 'useFormStatus'], + 'solid-js': [ + 'createComputed', + 'createDeferred', + 'createEffect', + 'createMemo', + 'createReaction', + 'createRenderEffect', + 'createResource', + 'createSelector', + 'createSignal', + 'onCleanup', + 'onMount', + 'useContext', + 'useTransition', + ], + 'solid-js/store': ['createMutable', 'createStore'], + vue: [ + 'computed', + 'inject', + 'onMounted', + 'onUnmounted', + 'provide', + 'reactive', + 'ref', + 'shallowRef', + 'watch', + 'watchEffect', + ], + svelte: ['afterUpdate', 'beforeUpdate', 'getContext', 'onDestroy', 'onMount', 'setContext'], +}; + +/** Keep adapter transforms and styles-only client entries separate from the server import graph. */ +export function serverComponentsPlugin(root: string, pagesDir: string): Array { + async function styleEntries() { + if (!existsSync(pagesDir)) { + return []; + } + const scan = await scanPages(root, { pagesDir, environment: 'prod' }); + return [ + ...scan.pages.filter((page) => page.serverView).map((page) => page.componentPath), + ...[...scan.layouts, ...scan.namedLayouts, ...(scan.boundaries ?? [])] + .filter((view) => view.serverView) + .map((view) => view.filePath), + ].map((file) => serverViewStyleId(join(pagesDir, file))); + } + + return [ + { + name: 'void:server-components', + enforce: 'pre', + + configEnvironment: { + order: 'post', + async handler(name, config, env) { + if (env.command === 'serve' && name !== 'client') { + // Keep hono/jsx, its automatic runtimes and hono/html on the same + // module graph as the renderer. Optimizing a bare JSX subpath + // separately creates incompatible JSX nodes and context stores. + return { optimizeDeps: { exclude: ['hono'] } }; + } + if ( + name !== 'client' || + env.command !== 'build' || + config.build?.rollupOptions?.input || + existsSync(join(root, 'index.html')) || + !(await styleEntries()).length + ) { + return; + } + return { build: { rollupOptions: { input: STYLE_ENTRY } } }; + }, + }, + + async options(options) { + if (this.environment.name !== 'client') { + return; + } + const styles = await styleEntries(); + if (!styles.length) { + return; + } + const input = options.input; + if ( + !input || + input === STYLE_ENTRY || + (input === join(root, 'index.html') && !existsSync(input)) + ) { + return { ...options, input: styles }; + } + return { + ...options, + input: + typeof input === 'string' || Array.isArray(input) + ? [...(typeof input === 'string' ? [input] : input), ...styles] + : { ...input, ...Object.fromEntries(styles.map((id) => [relative(root, id), id])) }, + }; + }, + + async resolveId(source, importer) { + if (source.startsWith(GUARD)) { + if (this.environment.name === 'client') { + this.error('Void server hook guards cannot be imported by client code.'); + } + return '\0' + source; + } + const styles = source.endsWith(STYLE_QUERY) || importer?.endsWith(STYLE_QUERY); + const server = source.endsWith(SERVER_VIEW_QUERY) || importer?.endsWith(SERVER_VIEW_QUERY); + if (!styles && !server) { + return; + } + if (server && this.environment.name === 'client') { + this.error('Void server components cannot be imported by client code.'); + } + const query = styles ? STYLE_QUERY : SERVER_VIEW_QUERY; + const request = source.endsWith(query) ? source.slice(0, -query.length) : source; + const from = importer?.endsWith(query) ? importer.slice(0, -query.length) : importer; + const resolved = await this.resolve(request, from, { skipSelf: true }); + if ( + !resolved || + !isAbsolute(resolved.id) || + resolved.external || + !SCRIPT.test(resolved.id) || + resolved.id.includes('/node_modules/') + ) { + if (styles && !STYLE.test(resolved?.id ?? request)) { + return '\0void:empty-server-view-style'; + } + if ( + styles && + this.environment.mode === 'build' && + resolved && + /\.module\.[^?]+$/.test(resolved.id) + ) { + return { ...resolved, id: resolved.id + PROJECTED_CSS }; + } + return resolved; + } + return { ...resolved, id: normalizePath(resolved.id) + query }; + }, + + async load(id) { + if (id === '\0void:empty-server-view-style') { + return ''; + } + if (id.startsWith('\0' + GUARD)) { + const [framework, importer] = JSON.parse( + decodeURIComponent(id.slice(GUARD.length + 1)), + ) as [string, string]; + const resolved = await this.resolve(framework, importer); + const source = JSON.stringify(resolved && !resolved.external ? resolved.id : framework); + const hooks = frameworkHooks[framework]; + return ` + import * as original from ${source}; + export * from ${source}; + ${hooks + .map( + (hook) => `export function ${hook}() { + throw new Error(${JSON.stringify(`Void server component ${relative(root, importer)} cannot call ${framework}.${hook}(). Use void/jsx for server JSX or move the hook into a client page.`)}); + }`, + ) + .join('\n')} + const hooks = { ${hooks.join(', ')} }; + export default new Proxy(original.default ?? original, { + get(target, name) { return Object.hasOwn(hooks, name) ? hooks[name] : Reflect.get(target, name); } + }); + `; + } + if (id.endsWith(SERVER_VIEW_QUERY) && this.environment.name === 'client') { + this.error('Void server components cannot be loaded by client code.'); + } + if (!id.endsWith(STYLE_QUERY)) { + return; + } + const filename = id.slice(0, -STYLE_QUERY.length); + this.addWatchFile(filename); + const code = await readFile(filename, 'utf8'); + const parsed = parseSync(filename, code); + const imports = [ + ...staticModuleReferences(parsed, code), + ...parsed.module.dynamicImports.flatMap(({ start, moduleRequest }) => + moduleRequest && 'value' in moduleRequest && typeof moduleRequest.value === 'string' + ? [{ start, source: moduleRequest.value }] + : [], + ), + ].sort((a, b) => a.start - b.start); + return [...new Set(imports.map((item) => item.source))] + .map((value) => `import ${JSON.stringify(value)};`) + .join('\n'); + }, + + async transform(code, id) { + if (!id.endsWith(SERVER_VIEW_QUERY)) { + return; + } + const filename = id.slice(0, -SERVER_VIEW_QUERY.length); + const { module } = parseSync(filename, code); + const guard = new MagicString(code); + const redirect = (request: { start: number; end: number; value: string }) => { + if (Object.hasOwn(frameworkHooks, request.value)) { + guard.overwrite( + request.start, + request.end, + JSON.stringify(GUARD + encodeURIComponent(JSON.stringify([request.value, filename]))), + ); + } + }; + // SSR can externalize a bare package before resolveId sees it. Redirect + // these imports in source, while leaving adapter imports untouched. + for (const item of module.staticImports) { + if (!item.entries.length || item.entries.some((entry) => !entry.isType)) { + redirect(item.moduleRequest); + } + } + for (const item of module.staticExports) { + const request = item.entries.find( + (entry) => !entry.isType && entry.moduleRequest, + )?.moduleRequest; + if (request) { + redirect(request); + } + } + for (const { moduleRequest } of module.dynamicImports) { + if ( + moduleRequest && + 'value' in moduleRequest && + typeof moduleRequest.value === 'string' + ) { + redirect({ ...moduleRequest, value: moduleRequest.value }); + } + } + return transformWithOxc( + guard.toString(), + filename, + { + jsx: { runtime: 'automatic', importSource: 'void/jsx' }, + }, + guard.hasChanged() ? guard.generateMap({ hires: true, source: filename }) : undefined, + ); + }, + }, + { + name: 'void:server-component-css', + enforce: 'post', + transform(_code, id) { + if (id.endsWith(PROJECTED_CSS)) { + // Vite normally drops unused CSS module exports and their stylesheet. + return { moduleSideEffects: 'no-treeshake' }; + } + }, + }, + ]; +} diff --git a/packages/void/src/pages/types.ts b/packages/void/src/pages/types.ts index ce3cbdaba..46d7f81c3 100644 --- a/packages/void/src/pages/types.ts +++ b/packages/void/src/pages/types.ts @@ -9,6 +9,7 @@ export type PrerenderMode = 'auto' | 'force' | 'disabled'; export type PageRenderMode = 'server' | 'client' | 'island'; export type PageDefinition = { + serverView?: boolean; /** URL pattern, e.g. "/users/:id" */ pattern: string; /** Route params, e.g. ["id"] */ @@ -47,6 +48,7 @@ export type PageDefinition = { }; export type LayoutDefinition = { + serverView?: boolean; /** Directory path relative to pages/, e.g. "" (root) or "users" */ directory: string; /** Layout file relative path, e.g. "layout.vue" or "users/layout.vue" */ @@ -56,6 +58,7 @@ export type LayoutDefinition = { }; export type NamedLayoutDefinition = { + serverView?: boolean; name: string; /** Directory containing _layouts/, e.g. "" (root) or "guide" */ directory: string; @@ -72,6 +75,7 @@ export type PageScanResult = { }; export type PageBoundaryDefinition = { + serverView?: boolean; kind: 'error' | 'not-found'; directory: string; componentId: string; diff --git a/packages/void/src/router/compile.ts b/packages/void/src/router/compile.ts index dd16e55bf..4f27f43d2 100644 --- a/packages/void/src/router/compile.ts +++ b/packages/void/src/router/compile.ts @@ -5,8 +5,13 @@ import type { DevRedirectRule, HeaderRule } from '../cli/types.ts'; import type { NotFoundHandling } from '../config.ts'; import type { MigrationPlanBundle } from '../migrations/plan.ts'; import { createBoundaryManifest } from '../pages/boundary-plans.ts'; -import { resolveLayoutIds } from '../pages/layout-resolution.ts'; +import { + resolveEffectiveLayoutChain, + resolveLayoutIds, + toLayoutId, +} from '../pages/layout-resolution.ts'; import { patternToRegex } from '../pages/manifest.ts'; +import { SERVER_VIEW_QUERY, serverViewStyleId } from '../pages/server-components-plugin.ts'; import { cloudflareQueueName, type CloudflareQueueNames } from '../queues/cloudflare-names.ts'; import { generateQueueResolverSource } from '../queues/dispatch.ts'; import { INTERNAL_BINDING_EXACT_NAMES, INTERNAL_BINDING_PREFIXES } from '../runtime/env/raw.ts'; @@ -998,7 +1003,13 @@ function compilePageRoutes( options: CompileOptions, pageNames: (componentId: string) => string, ): void { - lines.push(`import { renderPage } from "virtual:void-pages-renderer";`); + const boundaryManifest = createBoundaryManifest(scan.pages); + const rootPlan = boundaryManifest.root && boundaryManifest.plans[boundaryManifest.root]; + const serverPages = scan.pages.pages.filter((page) => page.serverView); + const serverPlans = Object.values(boundaryManifest.plans).filter((plan) => plan.serverView); + if (scan.pages.pages.some((page) => !page.serverView) || (rootPlan && !rootPlan.serverView)) { + lines.push(`import { renderPage } from "virtual:void-pages-renderer";`); + } if (options.dev) { lines.push(`import { getVoidPagesDevCss } from "virtual:void-pages-dev-assets";`); } @@ -1017,12 +1028,64 @@ function compilePageRoutes( const relPagesDir = pages.pagesDirRelative; const pageCssKeys: Record> = {}; const pageDevRootPhases: Record>> = {}; - const boundaryManifest = createBoundaryManifest(scan.pages); const projectRoot = options.projectRoot; const toDevRootUrl = (absolutePath: string): string => '/' + absolutePath.replaceAll('\\', '/').slice(projectRoot.replaceAll('\\', '/').length + 1); const virtualDevUrl = (id: string): string => '/@id/__x00__' + id; + const serverLayouts = scan.pages.layouts.filter((layout) => layout.serverView); + const serverNamedLayouts = scan.pages.namedLayouts.filter((layout) => layout.serverView); + const serverCssKeys: Record> = {}; + const serverDevRoots: Record>> = {}; + if (serverPages.length || serverPlans.length) { + lines.push( + `import { createServerViewRenderer as __createServerViewRenderer } from ${JSON.stringify(ROUTING_RUNTIME_PATH)};`, + ); + const load = (file: string) => + `() => import(${JSON.stringify(`${pages.pagesDir}/${file}${SERVER_VIEW_QUERY}`)})`; + const serverLayoutPaths = new Map( + [...serverLayouts, ...serverNamedLayouts].map((layout) => { + const id = toLayoutId(layout); + return [ + scan.pages.pages.some((page) => page.componentId === id) + ? id.replace(/(^|\/)([^/]+)$/, '$1_$2') + : id, + layout.filePath, + ]; + }), + ); + const entry = (id: string, file: string, layouts: Array, boundary = false) => { + const styles = [...layouts, file].map((path) => + serverViewStyleId(`${pages.pagesDir}/${path}`), + ); + serverCssKeys[id] = styles.map((path) => relative(projectRoot, path).replaceAll('\\', '/')); + serverDevRoots[id] = styles.map((path) => [toDevRootUrl(path)]); + return `[${JSON.stringify(id)}]: { load: ${load(file)}, layouts: [${layouts.map(load).join(', ')}]${boundary ? ', boundary: true' : ''} }`; + }; + const entries = serverPages.map((page) => + entry( + page.componentId, + page.componentPath, + resolveEffectiveLayoutChain(page, serverLayouts, serverNamedLayouts).map( + (layout) => layout.filePath, + ), + ), + ); + entries.push( + ...serverPlans.map((plan) => + entry( + plan.id, + plan.filePath, + plan.layouts.flatMap((id) => serverLayoutPaths.get(id) ?? []), + true, + ), + ), + ); + lines.push(`const renderServerView = __createServerViewRenderer({ ${entries.join(', ')} });`); + } for (const page of scan.pages.pages) { + if (page.serverView) { + continue; + } const keys: Array = []; const routeRootPhases: Array> = [ [ @@ -1034,12 +1097,14 @@ function compilePageRoutes( if (page.island && pages.mdClientEntryId) { routeRootPhases[0].push(virtualDevUrl(pages.mdClientEntryId)); } - const layoutIds = resolveLayoutIds(page, scan.pages.layouts, scan.pages.namedLayouts); + const layoutIds = resolveLayoutIds( + page, + scan.pages.layouts.filter((l) => !l.serverView), + scan.pages.namedLayouts.filter((l) => !l.serverView), + ); const layoutRoots: Array = []; for (const layoutId of layoutIds) { - const layout = scan.pages.layouts.find( - (l) => (l.directory ? `${l.directory}/layout` : 'layout') === layoutId, - ); + const layout = scan.pages.layouts.find((l) => !l.serverView && toLayoutId(l) === layoutId); if (layout) { keys.push(`${relPagesDir}/${layout.filePath}`); layoutRoots.push(toDevRootUrl(`${pages.pagesDir}/${layout.filePath}`)); @@ -1047,7 +1112,7 @@ function compilePageRoutes( } const named = scan.pages.namedLayouts.find((nl) => { const id = nl.directory ? `${nl.directory}/_layouts/${nl.name}` : `_layouts/${nl.name}`; - return id === layoutId; + return !nl.serverView && id === layoutId; }); if (named) { keys.push(`${relPagesDir}/${named.filePath}`); @@ -1061,8 +1126,14 @@ function compilePageRoutes( pageDevRootPhases[page.componentId] = routeRootPhases.filter((phase) => phase.length > 0); } for (const plan of Object.values(boundaryManifest.plans)) { + if (plan.serverView) { + continue; + } const files = [...scan.pages.layouts, ...scan.pages.namedLayouts] .filter((layout) => { + if (layout.serverView) { + return false; + } const id = 'name' in layout ? layout.directory @@ -1091,6 +1162,11 @@ function compilePageRoutes( dev: options.dev === true, }; const devCssOption = options.dev ? ', devCss: getVoidPagesDevCss' : ''; + if (serverPages.length || serverPlans.length) { + lines.push( + `const getServerViewAssets = __createClientAssetTags({ ...${JSON.stringify({ kind: 'server-view', pageCssKeys: serverCssKeys, devRootPhases: options.dev ? serverDevRoots : undefined, dev: options.dev === true })}${devCssOption} }, __loadPagesManifest);`, + ); + } lines.push( `const getPagesAssetTags = __createClientAssetTags({ ...${JSON.stringify({ ...assetMetadata, entryId: pages.clientEntryId, entryUrl: '/@id/__x00__' + pages.clientEntryId, kind: 'pages' })}${devCssOption} }, __loadPagesManifest);`, ); @@ -1102,8 +1178,15 @@ function compilePageRoutes( if (boundaryManifest.root) { const island = scan.pages.pages.length > 0 && scan.pages.pages.every((page) => page.island); + const serverView = !!(rootPlan && rootPlan.serverView); + const renderer = serverView ? 'renderServerView' : island ? 'renderIslandPage' : 'renderPage'; + const assets = serverView + ? 'getServerViewAssets' + : island && pages.islandClientEntryId + ? 'getIslandsAssetTags' + : 'getPagesAssetTags'; lines.push( - `const __voidRootNotFoundOptions = { componentId: ${JSON.stringify(boundaryManifest.root)}, load: async () => ({ loader: () => new Response(null, { status: 404 }) }), render: ${island ? 'renderIslandPage' : 'renderPage'}, assets: ${island && pages.islandClientEntryId ? 'getIslandsAssetTags' : 'getPagesAssetTags'}, headConfig: __voidHeadConfig, renderOptions: ${JSON.stringify({ renderMode: island ? 'island' : 'server', dev: options.dev === true, boundaries: { notFound: boundaryManifest.root, errors: boundaryManifest.rootErrors ?? [] } })} }; const __voidRootNotFound = __createPageGetHandler(__voidRootNotFoundOptions); export const __voidRenderStaticNotFound = __createStaticNotFound({ ...__voidRootNotFoundOptions, render: renderPage, assets: getPagesAssetTags });`, + `const __voidRootNotFoundOptions = { componentId: ${JSON.stringify(boundaryManifest.root)}, load: async () => ({ loader: () => new Response(null, { status: 404 }) }), render: ${renderer}, assets: ${assets}, headConfig: __voidHeadConfig, renderOptions: ${JSON.stringify({ ...(serverView && { serverView }), renderMode: island ? 'island' : 'server', dev: options.dev === true, boundaries: { notFound: boundaryManifest.root, errors: boundaryManifest.rootErrors ?? [] } })} }; const __voidRootNotFound = __createPageGetHandler(__voidRootNotFoundOptions); export const __voidRenderStaticNotFound = __createStaticNotFound({ ...__voidRootNotFoundOptions, render: ${serverView ? renderer : 'renderPage'}, assets: ${serverView ? assets : 'getPagesAssetTags'} });`, ); } @@ -1113,7 +1196,7 @@ function compilePageRoutes( let serverImportPath: string | null = null; if (page.serverPath) { - serverImportPath = `${pages.pagesDir}/${page.serverPath}`; + serverImportPath = `${pages.pagesDir}/${page.serverPath}${page.serverView ? SERVER_VIEW_QUERY : ''}`; } if (serverImportPath && !seenServerFiles.has(serverImportPath)) { @@ -1140,16 +1223,25 @@ function compilePageRoutes( } // Choose renderer and asset tags based on normalized render mode - const renderer = page.renderMode === 'island' ? 'renderIslandPage' : 'renderPage'; - const assetTags = - page.renderMode === 'island' && pages.islandClientEntryId + const renderer = page.serverView + ? 'renderServerView' + : page.renderMode === 'island' + ? 'renderIslandPage' + : 'renderPage'; + const assetTags = page.serverView + ? 'getServerViewAssets' + : page.renderMode === 'island' && pages.islandClientEntryId ? 'getIslandsAssetTags' : 'getPagesAssetTags'; const trailingCatchAll = options.trailingSlash && page.catchAll; const pattern = trailingCatchAll ? page.pattern.slice(0, -1) : page.pattern; const catchAllParam = page.pattern.match(/:([^/{}]+)\{\.\+\}\/$/)?.[1]; - const middlewareBoundaries = `middlewareBoundaries: ${JSON.stringify({ notFound: boundaryManifest.root, errors: (boundaryManifest.pages[page.componentId]?.errors ?? []).filter((id) => !boundaryManifest.plans[id].directory) })}, `; - const routeOptions = `{ ${serverImportPath ? 'load: _pload_' + safeId + ', ' : ''}${mdHeadRef ? 'head: ' + mdHeadRef + ', ' : ''}${trailingCatchAll ? `trailingSlash: true, catchAllParam: ${JSON.stringify(catchAllParam)}, ` : ''}${middlewareBoundaries}componentId: ${JSON.stringify(page.componentId)}, render: ${renderer}, assets: ${assetTags}, headConfig: __voidHeadConfig, renderOptions: ${JSON.stringify({ renderMode: page.renderMode, ...(options.dev === true ? { dev: true } : {}), ...(boundaryManifest.pages[page.componentId] && { boundaries: boundaryManifest.pages[page.componentId] }) })} }`; + const middlewareNotFound = + rootPlan && Boolean(rootPlan.serverView) === Boolean(page.serverView) + ? boundaryManifest.root + : undefined; + const middlewareBoundaries = `middlewareBoundaries: ${JSON.stringify({ notFound: middlewareNotFound, errors: (boundaryManifest.pages[page.componentId]?.errors ?? []).filter((id) => !boundaryManifest.plans[id].directory) })}, `; + const routeOptions = `{ ${serverImportPath ? 'load: _pload_' + safeId + ', ' : ''}${mdHeadRef ? 'head: ' + mdHeadRef + ', ' : ''}${trailingCatchAll ? `trailingSlash: true, catchAllParam: ${JSON.stringify(catchAllParam)}, ` : ''}${middlewareBoundaries}componentId: ${JSON.stringify(page.componentId)}, render: ${renderer}, assets: ${assetTags}, headConfig: __voidHeadConfig, renderOptions: ${JSON.stringify({ ...(page.serverView && { serverView: true }), renderMode: page.renderMode, ...(options.dev === true ? { dev: true } : {}), ...(boundaryManifest.pages[page.componentId] && { boundaries: boundaryManifest.pages[page.componentId] }) })} }`; lines.push(`app.get(${JSON.stringify(pattern)}, __createPageGetHandler(${routeOptions}));`); if (page.methods.includes('action') || page.methods.includes('actions')) { lines.push( diff --git a/packages/void/src/runtime/handler/index.ts b/packages/void/src/runtime/handler/index.ts index 46a33d497..0fbf7c7f7 100644 --- a/packages/void/src/runtime/handler/index.ts +++ b/packages/void/src/runtime/handler/index.ts @@ -514,4 +514,4 @@ export function defineQueue(handler: QueueFn): TypedQueueHandler export type { ValidatorSlots, HandlerInput } from './validator.ts'; export { ValidationError } from '../../pages/validation-error.ts'; export { defer } from '../../pages/defer.ts'; -export type { Deferred, InferProps } from '../../pages/defer.ts'; +export type { Deferred, InferProps, InferServerProps } from '../../pages/defer.ts'; diff --git a/packages/void/src/runtime/jsx/index.ts b/packages/void/src/runtime/jsx/index.ts new file mode 100644 index 000000000..37d876c7c --- /dev/null +++ b/packages/void/src/runtime/jsx/index.ts @@ -0,0 +1,2 @@ +export * from 'hono/jsx'; +export { default } from 'hono/jsx'; diff --git a/packages/void/src/runtime/jsx/jsx-dev-runtime.ts b/packages/void/src/runtime/jsx/jsx-dev-runtime.ts new file mode 100644 index 000000000..970b142e6 --- /dev/null +++ b/packages/void/src/runtime/jsx/jsx-dev-runtime.ts @@ -0,0 +1 @@ +export * from 'hono/jsx/jsx-dev-runtime'; diff --git a/packages/void/src/runtime/jsx/jsx-runtime.ts b/packages/void/src/runtime/jsx/jsx-runtime.ts new file mode 100644 index 000000000..e1a2eaaf2 --- /dev/null +++ b/packages/void/src/runtime/jsx/jsx-runtime.ts @@ -0,0 +1 @@ +export * from 'hono/jsx/jsx-runtime'; diff --git a/packages/void/src/runtime/routing/assets.ts b/packages/void/src/runtime/routing/assets.ts index b84c7cdff..88fb0bf4e 100644 --- a/packages/void/src/runtime/routing/assets.ts +++ b/packages/void/src/runtime/routing/assets.ts @@ -93,7 +93,7 @@ export type ClientAssetOptions = { extraEntryUrl?: string; pageCssKeys?: Record>; devRootPhases?: Record>>; - kind: 'ssr' | 'pages' | 'islands'; + kind: 'ssr' | 'pages' | 'islands' | 'server-view'; dev?: boolean; reactRefresh?: boolean; devCss?: ( @@ -168,6 +168,24 @@ export function createClientAssetTags( ): (request: Request, env: RuntimeEnvironment, componentId?: string) => Promise { return async (request, env, componentId = '') => { const empty = { css: '', preloads: '', body: '' }; + if (options.kind === 'server-view') { + if (options.dev) { + const devCss = await options.devCss?.(request, env, { + kind: 'pages', + componentId, + rootPhases: options.devRootPhases?.[componentId] ?? [], + }); + return { ...empty, devCss: Array.isArray(devCss) ? (devCss as Array) : [] }; + } + const manifest = await loadManifest(request, env); + const css = collectRouteCss(manifest ?? {}, options.pageCssKeys?.[componentId] ?? []); + return { + ...empty, + css: [...css] + .map((file) => ``) + .join('\n'), + }; + } const manifest = await loadManifest(request, env); if (!manifest || typeof manifest !== 'object') { if (!options.dev) { diff --git a/packages/void/src/runtime/routing/index.ts b/packages/void/src/runtime/routing/index.ts index 0e7791768..3e5d7c76f 100644 --- a/packages/void/src/runtime/routing/index.ts +++ b/packages/void/src/runtime/routing/index.ts @@ -602,3 +602,4 @@ export { export { createClientAssetTags, createManifestLoader } from './assets.ts'; export { createSsrFallback, createAssetNotFound } from './pages.ts'; export { buildPrerenderPath } from './prerender-path.ts'; +export { createServerViewRenderer } from './server-components.ts'; diff --git a/packages/void/src/runtime/routing/pages.ts b/packages/void/src/runtime/routing/pages.ts index fe77579cb..3423462f2 100644 --- a/packages/void/src/runtime/routing/pages.ts +++ b/packages/void/src/runtime/routing/pages.ts @@ -195,8 +195,13 @@ export function createStaticNotFound( const handle = createPageGetHandler({ ...options, renderOptions: { ...options.renderOptions, renderMode: 'server' }, - render: (page, assets, url) => - options.render({ ...page, documentOnly: true }, { ...assets, body: '', preloads: '' }, url), + render: (page, assets, url, c) => + options.render( + { ...page, documentOnly: true }, + { ...assets, body: '', preloads: '' }, + url, + c, + ), }); return (request, env) => handle(new Context(new Request(new URL('/404', request.url)), { env })); } diff --git a/packages/void/src/runtime/routing/server-components.ts b/packages/void/src/runtime/routing/server-components.ts new file mode 100644 index 000000000..cc9019f0d --- /dev/null +++ b/packages/void/src/runtime/routing/server-components.ts @@ -0,0 +1,74 @@ +import { html } from 'hono/html'; +import { jsx, type Child } from 'hono/jsx'; +import { renderBodyAttrs, renderHeadToString, renderHtmlAttrs } from '../../pages/head.ts'; +import type { PageObject } from '../../pages/protocol.ts'; +import type { CloudContext } from '../handler/index.ts'; +import type { ClientAssetTags } from './assets.ts'; + +type PageView = (props: PageObject['props']) => Child | Promise; +type ContextView = (c: CloudContext) => Child | Promise; +type PageModule = + | { loader?: undefined; default: ContextView } + | { loader: (c: CloudContext) => unknown; default: PageView }; +type LayoutView = (c: CloudContext, children: Child) => Child | Promise; +type ViewPlan = { + layouts: Array<() => Promise<{ default: LayoutView }>>; +} & ( + | { boundary: true; load: () => Promise<{ default: ContextView }> } + | { boundary?: false; load: () => Promise } +); + +async function bindView( + plan: ViewPlan, + page: PageObject, + c: CloudContext, +): Promise<() => Child | Promise> { + if (plan.boundary) { + const { default: view } = await plan.load(); + assertView(view, page.component); + return () => view(c); + } + const module = await plan.load(); + assertView(module.default, page.component); + if (module.loader) { + return () => module.default(page.props); + } + return () => module.default(c); +} + +function assertView(view: unknown, component: string): void { + if (typeof view !== 'function') { + throw new Error(`Expected a default component export for ${component}`); + } +} + +export function createServerViewRenderer( + plans: Record, +): (page: PageObject, assets: ClientAssetTags, url: string, c?: CloudContext) => Promise { + return async (page: PageObject, assets: ClientAssetTags, _url: string, c?: CloudContext) => { + if (!c) { + throw new Error('Void server views need a request context.'); + } + const plan = plans[page.component]; + if (!plan) { + throw new Error(`Unknown Void server view: ${page.component}`); + } + const [view, ...layouts] = await Promise.all([ + bindView(plan, page, c), + ...plan.layouts.map((load) => load()), + ]); + // Lazy nodes let Hono evaluate descendants inside a layout's context provider. + let content: Child = jsx(view, {}); + for (const { default: Layout } of layouts.reverse()) { + if (typeof Layout !== 'function') { + throw new Error(`Expected a default component export in a layout for ${page.component}`); + } + const children = content; + content = jsx(() => Layout(c, children), {}); + } + // Hono's html helper resolves promises anywhere in the JSX tree and escapes text. + const body = (await html`${content}`).toString(); + const head = page.head; + return `${head ? renderHeadToString(head) : ''}${assets.css}${body}`; + }; +} diff --git a/packages/void/test/integration/server-components.test.ts b/packages/void/test/integration/server-components.test.ts new file mode 100644 index 000000000..20a88dbe7 --- /dev/null +++ b/packages/void/test/integration/server-components.test.ts @@ -0,0 +1,334 @@ +import { execFileSync } from 'node:child_process'; +import { existsSync, readFileSync, writeFileSync } from 'node:fs'; +import { join } from 'node:path'; +import spawn from 'cross-spawn'; +import { chromium } from 'playwright'; +import { describe, expect, it } from 'vite-plus/test'; +import { + createIsolatedPlayground, + killChild, + startServer, +} from '../../../../test/integration-helpers.ts'; + +const repository = join(import.meta.dirname, '../../../..'); + +describe('built-in JSX Pages', () => { + it('keeps an adapter active and rejects an aliased React hook only when the server component calls it', async () => { + const fixture = createIsolatedPlayground(repository, 'playground/node-app'); + let server: Awaited> | undefined; + try { + writeFileSync( + join(fixture.root, 'shared-button.tsx'), + ` + import React, { useState as reactState } from 'react'; + export function Button({ useHook = false }: { useHook?: boolean }) { + const label = useHook ? reactState('React state')[0] : 'Shared button'; + return ; + } + `, + ); + writeFileSync( + join(fixture.root, 'pages/about.tsx'), + ` + import { Button } from '../shared-button.tsx'; + export default function About() { return '); + const invalid = await fetch(`${server.base}/native?hook=1`); + expect(invalid.status).toBe(500); + expect(await invalid.text()).toContain('cannot call react.useState()'); + } finally { + if (server) { + await killChild(server.child); + } + fixture.cleanup(); + } + }, 30_000); + + it.each([ + ['Cloudflare', 'dev'], + ['Cloudflare', 'preview'], + ['Node', 'dev'], + ['Node', 'preview'], + ])( + 'renders HTML and CSS on %s in %s without JavaScript', + async (target, command) => { + const fixture = createIsolatedPlayground(repository, 'playground/server-components'); + let server: Awaited> | undefined; + try { + writeFileSync( + join(fixture.root, 'pages/empty-loader.server.tsx'), + ` + export const loader = () => ({}); + export default function Page(props) { + return

{'req' in props ? 'Received context' : 'Received empty props'}

; + } + `, + ); + const weatherPage = join(fixture.root, 'pages/weather.server.tsx'); + const weatherData = (temperature: number) => + 'data:application/json,' + + encodeURIComponent(JSON.stringify({ current: { temperature_2m: temperature } })); + writeFileSync( + weatherPage, + readFileSync(weatherPage, 'utf8').replace( + 'fetch(forecastUrl,', + `fetch(forecastUrl.searchParams.get('latitude') === '1.29' && + forecastUrl.searchParams.get('longitude') === '103.85' + ? '${weatherData(29)}' + : '${weatherData(12)}',`, + ), + ); + if (target === 'Node') { + writeFileSync(join(fixture.root, 'void.config.ts'), `export default { target: 'node' };`); + } + if (command === 'preview') { + execFileSync('vp', ['build'], { cwd: fixture.root, stdio: 'pipe' }); + } + server = await startServer( + (port) => + target === 'Node' && command === 'preview' + ? spawn(process.execPath, ['dist/ssr/index.js'], { + cwd: fixture.root, + stdio: ['ignore', 'pipe', 'pipe'], + env: { ...process.env, PORT: String(port) }, + }) + : spawn( + 'vp', + [ + command, + ...(command === 'dev' ? ['--force'] : []), + '--strictPort', + '--port', + String(port), + ], + { cwd: fixture.root, stdio: ['ignore', 'pipe', 'pipe'] }, + ), + 20_000, + ); + const base = server.base; + const [home, escapedGreeting, asyncContext, about, post, missing] = await Promise.all([ + fetch(base, { headers: { 'X-VoidPages': 'true' } }), + fetch(`${base}/greeting?name=%3Cscript%3E`), + fetch(`${base}/async-context?greeting=Welcome`), + fetch(`${base}/about`), + fetch(`${base}/posts/42`), + fetch(`${base}/missing`), + ]); + expect(home.headers.get('content-type')).toContain('text/html'); + expect(home.headers.has('x-voidpages')).toBe(false); + const document = await home.text(); + expect(document).toContain('

Server Component Examples

'); + expect(await asyncContext.text()).toContain('Welcome, reader!'); + const githubSource = + 'https://github.com/voidzero-dev/void/blob/server-components/playground/server-components/'; + const sourceBase = + command === 'dev' + ? `vscode://file${new URL('file://' + fixture.root + '/').pathname}` + : githubSource; + expect(document).toContain(`${sourceBase}pages/posts/%5Bid%5D/index.server.tsx`); + expect(document).not.toContain(command === 'dev' ? githubSource : 'vscode://file'); + expect(document).not.toContain('Received empty props'); + const aboutDocument = await about.text(); + expect(aboutDocument).toContain('About | Server Components'); + expect(aboutDocument).toContain('About this playground'); + expect(aboutDocument).not.toContain('Main navigation'); + const postDocument = await post.text(); + expect(postDocument).toContain('Post 42'); + expect(postDocument).toContain('

Post 42

'); + expect(postDocument).toContain( + ' getComputedStyle(element).display)).toBe( + 'grid', + ); + } + const cards = await page.locator('.example').all(); + expect(cards).toHaveLength(14); + expect((await page.locator('.example h3').allTextContents()).slice(1, 3)).toEqual([ + 'Async component fetches weather', + 'Render a page with a loader', + ]); + for (const card of cards) { + expect(await card.getByRole('heading').count()).toBe(1); + expect(await card.locator('.source-link').getAttribute('href')).toMatch( + command === 'dev' ? /^vscode:\/\/file/ : /^https:\/\/github\.com\//, + ); + expect( + await card.getByRole('link', { name: 'See example' }).getAttribute('href'), + ).toMatch(/^\/.+/); + } + await page + .locator('.example') + .filter({ hasText: 'Render a page with a loader' }) + .getByRole('link', { name: 'See example' }) + .click(); + await page.getByLabel('Name').fill('playground reader'); + await page.getByRole('button', { name: 'Update greeting' }).click(); + await page.getByText('Hello, playground reader!').waitFor(); + await page.goto(`${base}/custom-layout`); + await page.getByRole('heading', { name: 'Use a custom layout' }).waitFor(); + await page.getByRole('navigation', { name: 'Main navigation' }).waitFor(); + await page.getByText('Current path: /custom-layout').waitFor(); + await page.getByText('End of the field guide').waitFor(); + expect( + await page + .getByRole('link', { name: 'pages/custom-layout/layout.server.tsx' }) + .getAttribute('href'), + ).toBe(`${sourceBase}pages/custom-layout/layout.server.tsx`); + await page.goto(`${base}/css`); + expect(await page.getByRole('navigation').count()).toBe(0); + expect( + await page.locator('.examples').evaluate((grid) => getComputedStyle(grid).display), + ).toBe('grid'); + await page.goto(`${base}/weather`); + await page.getByText('Temperature: 29 °C').waitFor(); + await page.getByRole('heading', { name: 'Current weather in Singapore' }).waitFor(); + const location = page.getByLabel('Location'); + expect(await location.locator('option').allTextContents()).toEqual([ + 'Singapore', + 'Austin', + 'Lisbon', + 'London', + 'San Francisco', + ]); + expect(await location.inputValue()).toBe('singapore'); + await location.selectOption({ label: 'London' }); + expect(new URL(page.url()).search).toBe(''); + await page.getByRole('button', { name: 'Show' }).click(); + await page.getByRole('heading', { name: 'Current weather in London' }).waitFor(); + await page.getByText('Temperature: 12 °C').waitFor(); + expect(new URL(page.url()).searchParams.get('location')).toBe('london'); + expect(await location.inputValue()).toBe('london'); + expect(await page.locator('script').count()).toBe(0); + await page.goto(`${base}/weather?location=unknown`); + await page.getByRole('heading', { name: 'Current weather in Singapore' }).waitFor(); + expect(await location.inputValue()).toBe('singapore'); + await page.goto(`${base}/preview`); + await page.getByLabel('Draft title').fill('A draft '); + await page.getByRole('button', { name: 'Preview draft' }).click(); + await page.getByRole('heading', { name: 'A draft <title>' }).waitFor(); + expect(await page.title()).toBe('A draft <title>'); + await page.goto(`${base}/preview`); + expect(await page.title()).toBe('Untitled draft'); + } finally { + await browser.close(); + } + if (target === 'Cloudflare' && command === 'dev') { + // Readiness can retry a failed request, so check the cold-start logs too. + expect(server.output()).not.toMatch( + /\(void_worker\).*dependency optimized:.*\bhono\/jsx/, + ); + expect(server.output()).not.toContain('Cannot convert object to primitive value'); + } + } finally { + if (server) { + await killChild(server.child); + } + fixture.cleanup(); + } + }, + 45_000, + ); + + it('prerenders loader props and head for selected paths in static output', () => { + const fixture = createIsolatedPlayground(repository, 'playground/server-components'); + try { + writeFileSync( + join(fixture.root, 'void.config.ts'), + `export default { target: 'node', output: 'static' };`, + ); + execFileSync('vp', ['build'], { cwd: fixture.root, stdio: 'pipe' }); + const document = readFileSync(join(fixture.root, 'dist/client/posts/42.html'), 'utf8'); + expect(document).toContain('<title>Post 42'); + expect(document).toContain('

Post 42

'); + expect(document).toContain('Nested posts layout'); + expect(document).not.toContain(' { deploy: undefined, }); expect(() => parseInitArgs(['--framework', 'angular'])).toThrow( - 'init: --framework must be one of react, vue, svelte, solid.', + 'init: --framework must be one of none, react, vue, svelte, solid.', ); }); @@ -190,7 +190,7 @@ describe('init scaffold arguments', () => { try { Object.defineProperty(process.stdin, 'isTTY', { configurable: true, get: () => false }); await expect(runInitCommand(root, parseInitArgs(['--toolchain', 'vite']))).rejects.toThrow( - 'init: Pass --framework (react, vue, svelte, solid) when running without an interactive terminal.', + 'init: Pass --framework (none, react, vue, svelte, solid) when running without an interactive terminal.', ); expect(mockSelect).not.toHaveBeenCalled(); expect(readdirSync(root)).toEqual([]); @@ -1607,6 +1607,11 @@ describe('isScaffoldableEmptyProject', () => { const frameworkPrompt = mockSelect.mock.calls[1]?.[0]; expect(frameworkPrompt.message).toBe('Choose a Pages framework to scaffold:'); expect(frameworkPrompt.options).toEqual([ + { + value: 'none', + label: 'None', + hint: 'Server-rendered JSX Pages without a framework adapter.', + }, { value: 'react', label: 'React', @@ -1658,6 +1663,32 @@ describe('isScaffoldableEmptyProject', () => { } }); + it('scaffolds built-in JSX Pages with --framework none', async () => { + const root = mkdtempSync(join(tmpdir(), 'void-init-')); + try { + await runInitCommand(root, { + tsconfig: false, + github: false, + toolchain: 'vite', + framework: 'none', + starter: 'static', + deploy: 'none', + git: false, + }); + + const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8')); + expect(pkg.devDependencies['@void/react']).toBeUndefined(); + expect(readFileSync(join(root, 'pages/index.server.tsx'), 'utf-8')).toContain( + 'export default function Page', + ); + expect(readFileSync(join(root, 'tsconfig.json'), 'utf-8')).toContain( + '"jsxImportSource": "void/jsx"', + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } + }); + it('scaffolds a static Pages starter without database files', async () => { const root = mkdtempSync(join(tmpdir(), 'void-init-')); try { diff --git a/packages/void/test/unit/pages-protocol.test.ts b/packages/void/test/unit/pages-protocol.test.ts index 38eac035b..a6a5d1c0f 100644 --- a/packages/void/test/unit/pages-protocol.test.ts +++ b/packages/void/test/unit/pages-protocol.test.ts @@ -1279,6 +1279,57 @@ describe('handlePageMutation', () => { }); describe('handlePageGet with deferred props', () => { + it.each(['GET', 'POST'])( + 'resolves server view deferred props before head and rendering on %s', + async (method) => { + const c = await createTestContext(method, '/'); + const grouped = vi.fn(async () => ({ first: 'one', second: 'two' })); + const loader = vi.fn(() => ({ + title: defer(async () => 'Resolved title'), + first: defer('pair', grouped), + second: defer('pair', grouped), + })); + const head = vi.fn((_c: CloudContext, props: Record) => ({ + title: String(props.title), + })); + const render = vi.fn(async () => '
Server page
'); + const assets = async () => ({ css: '', preloads: '', body: '' }); + const options = { serverView: true }; + const response = + method === 'GET' + ? await handlePageGet(loader, head, c, 'index', render, assets, undefined, options) + : await handlePageMutation( + () => undefined, + loader, + head, + c, + 'index', + render, + assets, + undefined, + options, + ); + + expect(await response.text()).toBe('
Server page
'); + expect(loader).toHaveBeenCalledTimes(1); + expect(grouped).toHaveBeenCalledTimes(1); + expect(head).toHaveBeenCalledWith(c, { + title: 'Resolved title', + first: 'one', + second: 'two', + }); + expect(render).toHaveBeenCalledWith( + expect.objectContaining({ + props: head.mock.calls[0][1], + head: expect.objectContaining({ title: 'Resolved title' }), + }), + expect.anything(), + expect.anything(), + c, + ); + }, + ); + it('SPA — streams NDJSON with immediate props first, then deferred', async () => { const c = await createTestContext('GET', '/dashboard', { headers: { 'x-voidpages': 'true', 'X-VoidPages-Version': PAGES_PROTOCOL_VERSION }, diff --git a/packages/void/test/unit/pages-scan.test.ts b/packages/void/test/unit/pages-scan.test.ts index b4cae53c9..82b39e255 100644 --- a/packages/void/test/unit/pages-scan.test.ts +++ b/packages/void/test/unit/pages-scan.test.ts @@ -27,6 +27,66 @@ function writeFile(relativePath: string, content: string): void { } describe('scanPages', () => { + it('discovers standalone server views without promoting handler-only companions', async () => { + writeFile('index.server.tsx', 'export default function () { return

Home

; }'); + writeFile( + 'posts/[id]/index.server.tsx', + 'export default async function Post() { return

Post

; }', + ); + writeFile('about.dev.server.ts', 'const view = () => "About"; export { view as default };'); + writeFile('layout.server.tsx', 'export default () =>
;'); + writeFile( + '_not-found.server.tsx', + 'export default function Missing() { return

Missing

; }', + ); + writeFile('unused.server.ts', 'export function loader() {}'); + writeFile('named.server.tsx', 'export function Page() { return

Not a route

; }'); + writeFile('type-only.server.ts', 'export default interface View {}'); + writeFile('type-alias.server.ts', 'interface View {} export type { View as default };'); + const prod = await scanPages(TMP, { environment: 'prod' }); + expect(prod.pages.map(({ pattern, serverView }) => [pattern, serverView])).toEqual([ + ['/', true], + ['/posts/:id', true], + ]); + expect(prod.layouts).toMatchObject([{ filePath: 'layout.server.tsx', serverView: true }]); + expect(prod.boundaries).toMatchObject([{ kind: 'not-found', serverView: true }]); + expect( + (await scanPages(TMP, { environment: 'dev' })).pages.map((page) => page.pattern), + ).toContain('/about'); + }); + + it('reports a server view and adapter view that claim the same route', async () => { + writeFile('about.server.tsx', 'export default () =>

About

;'); + writeFile('about/index.vue', ''); + await expect(scanPages(TMP)).rejects.toThrow(/about\.server\.tsx.*about\/index\.vue/); + }); + + it('rejects client-only rendering on server pages', async () => { + writeFile('about.server.tsx', 'export const ssr = false; export default () =>

About

;'); + await expect(scanPages(TMP)).rejects.toThrow( + "pages: Server component 'about.server.tsx' cannot set ssr = false.", + ); + }); + + it('reads the same layout metadata on server pages as on adapter pages', async () => { + writeFile('layout.server.tsx', 'export default () =>
;'); + writeFile('_layouts/landing.server.tsx', 'export default () =>