vue-ssr-lite 0.1.6 → 0.1.8

package/README.md

@@ -1,175 +1,938 @@
 # vue-ssr-lite
 
-`vue-ssr-lite` is a managed Vue 3 SSR runtime. A consumer supplies one application definition and a small Vite registration; the package owns the HTTP server, Vite middleware, per-request Vue/Router/Apollo lifecycle, server rendering, state transfer, browser hydration, static assets, health checks, errors, timeouts, instrumentation, startup, and graceful shutdown.
+A simple, production-ready SSR runtime for Vue 3 and Vite.
+
+Use it to run:
+
+- A server-rendered Vue website
+- A normal Vue SPA
+- Multiple SSR applications
+- SPA and SSR applications together
+- Applications on different domains or subdomains
+
+It includes routing, browser hydration, production builds, a managed Node server, health checks, custom endpoints, caching, timeouts, and Vue plugin support.
+
+## Features
+
+- Vue 3 server-side rendering
+- Normal Vue SPA support
+- SPA and SSR in one project
+- Vue Router support
+- Automatic browser hydration
+- Multiple applications and HTML entries
+- Domain and subdomain routing
+- Runtime roles for one image / many process modes
+- Apollo, GraphQL, REST, Pinia, and i18n support
+- SEO metadata and status codes
+- Custom server endpoints
+- Health and readiness checks
+- Request timeouts
+- Optional response caching
+- Cookie allowlists and denylists
+- Proxy-aware host and protocol resolution
+- Graceful shutdown
+- TypeScript support
+
+## Package Entry Points
+
+| Import | Purpose |
+| --- | --- |
+| `vue-ssr-lite` | `defineSsrApplication`, `defineSsrRuntime`, request context, hydration helpers |
+| `vue-ssr-lite/client` | Browser hydration only |
+| `vue-ssr-lite/server` | Managed Node server, host matching, cookies, response cache |
+| `vue-ssr-lite/vite` | Vite plugin that wires HTML templates and virtual client entries |
+
+CLI binary:
+
+```bash
+vue-ssr-lite <dev|build|start> [--root .] [--runtime src/SsrRuntime.ts] [--server-output dist/server/SsrRuntime.js]
+```
+
+Requires Node.js 20 or newer.
+
+## Installation
+
+```bash
+npm install vue-ssr-lite vue vue-router @vue/server-renderer
+npm install --save-dev vite @vitejs/plugin-vue
+```
+
+Using Yarn:
+
+```bash
+yarn add vue-ssr-lite vue vue-router @vue/server-renderer
+yarn add --dev vite @vitejs/plugin-vue
+```
+
+## Choose Your Application Type
+
+`vue-ssr-lite` supports two application types.
+
+### SPA
+
+Use `kind: 'spa'` for a normal Vue application that runs in the browser.
+
+Examples:
+
+- Admin dashboard
+- Internal application
+- Editor
+- Authenticated application
+- Client-side portal
+
+A SPA keeps its normal Vite `main.ts` entry.
+
+### SSR
 
-## Minimal integration
+Use `kind: 'ssr'` for a Vue application that should render on the server and hydrate in the browser.
 
-Create one application definition:
+Examples:
+
+- Public website
+- Storefront
+- Blog
+- Marketing website
+- Documentation website
+- SEO-focused application
+
+An SSR application is defined with `defineSsrApplication()`.
+
+## Quick Start: SPA and SSR Together
+
+The following example creates:
+
+- A dashboard SPA on `app.example.com`
+- A server-rendered website on all other hosts
+
+## 1. Create the SPA Application
+
+Create a normal Vue entry:
 
 ```ts
-// src/PublicSsrRuntime.ts
-import PublicApp from './PublicApp.vue'
-import { defineSsrApplication, defineSsrRuntime } from 'vue-ssr-lite'
+// src/spa/main.ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import router from './router'
+
+const app = createApp(App)
 
-export const publicApplication = defineSsrApplication({
-  id: 'public',
-  rootComponent: PublicApp,
-  routes: [
-    { path: '/:path(.*)*', component: PublicApp },
-  ],
-  apollo: ({ publicConfig }) => ({
-    endPoints: { default: publicConfig.graphqlEndpoint },
-  }),
+app.use(router)
+app.mount('#app')
+```
+
+Create the SPA root component:
+
+```vue
+<!-- src/spa/App.vue -->
+<script setup lang="ts">
+import { RouterView } from 'vue-router'
+</script>
+
+<template>
+	<RouterView />
+</template>
+```
+
+Create the SPA HTML entry:
+
+```html
+<!-- index.html -->
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta
+			name="viewport"
+			content="width=device-width, initial-scale=1" />
+		<title>Dashboard</title>
+	</head>
+
+	<body>
+		<div id="app"></div>
+
+		<script
+			type="module"
+			src="/src/spa/main.ts"></script>
+	</body>
+</html>
+```
+
+This remains a normal Vue and Vite SPA. No special SPA application definition is required.
+
+## 2. Create the SSR Application
+
+Create the SSR root component:
+
+```vue
+<!-- src/website/App.vue -->
+<script setup lang="ts">
+import { RouterView } from 'vue-router'
+</script>
+
+<template>
+	<RouterView />
+</template>
+```
+
+Create the SSR routes:
+
+```ts
+// src/website/routes.ts
+import type { RouteRecordRaw } from 'vue-router'
+
+import HomePage from './pages/HomePage.vue'
+import AboutPage from './pages/AboutPage.vue'
+import NotFoundPage from './pages/NotFoundPage.vue'
+
+export const websiteRoutes: RouteRecordRaw[] = [
+	{
+		path: '/',
+		component: HomePage,
+	},
+	{
+		path: '/about',
+		component: AboutPage,
+	},
+	{
+		path: '/:pathMatch(.*)*',
+		component: NotFoundPage,
+	},
+]
+```
+
+Define the SSR application:
+
+```ts
+// src/website/SsrApplication.ts
+import { defineSsrApplication } from 'vue-ssr-lite'
+
+import App from './App.vue'
+import { websiteRoutes } from './routes'
+
+export const websiteApplication = defineSsrApplication({
+	id: 'website',
+	rootComponent: App,
+	routes: websiteRoutes,
 })
+```
 
-export default () => defineSsrRuntime({
-  name: 'public-site',
-  entries: [{
-    id: 'public',
-    kind: 'ssr',
-    template: 'site.html',
-    hosts: ['*'],
-    application: publicApplication,
-  }],
-  server: {
-    host: process.env.HOST || '0.0.0.0',
-    port: Number(process.env.PORT || 4173),
-    trustProxy: process.env.TRUST_PROXY === 'true',
-    publicConfig: {
-      graphqlEndpoint: process.env.GRAPHQL_ENDPOINT || 'http://localhost:4000/graphql',
-    },
-  },
+Create its HTML template:
+
+```html
+<!-- site.html -->
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta
+			name="viewport"
+			content="width=device-width, initial-scale=1" />
+	</head>
+
+	<body>
+		<div id="app"></div>
+	</body>
+</html>
+```
+
+The SSR browser entry and hydration setup are added automatically.
+
+## 3. Create the Runtime
+
+The runtime tells the package which application should handle each host.
+
+```ts
+// src/SsrRuntime.ts
+import { defineSsrRuntime } from 'vue-ssr-lite'
+
+import { websiteApplication } from './website/SsrApplication'
+
+export default defineSsrRuntime({
+	name: 'my-platform',
+
+	entries: [
+		{
+			id: 'dashboard',
+			kind: 'spa',
+			template: 'index.html',
+			hosts: ['app.example.com', 'localhost'],
+		},
+		{
+			id: 'website',
+			kind: 'ssr',
+			template: 'site.html',
+			hosts: ['*'],
+			application: websiteApplication,
+		},
+	],
+
+	defaultEntryId: 'website',
+
+	server: {
+		host: '0.0.0.0',
+		port: Number(process.env.PORT || 4173),
+		role: process.env.APP_RUNTIME || 'unified',
+
+		publicConfig: {
+			apiUrl: process.env.PUBLIC_API_URL || 'http://localhost:4000',
+		},
+	},
 })
 ```
 
-Register its template and exported application in Vite:
+The specific SPA hostname is checked first. The `*` SSR entry handles all remaining hosts.
+`defaultEntryId` is used when no host pattern matches.
+
+When the server starts, the console prints a ready message with a clickable local URL and the active role:
+
+```text
+✓  Server Ready
+
+  ➜ Local:  http://localhost:4173/
+  ➜ Role:   unified
+```
+
+## 4. Configure Vite
+
+Register the SSR application and the normal SPA HTML entry:
 
 ```ts
+// vite.config.ts
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
+
 import { vueSsrLite } from 'vue-ssr-lite/vite'
 
 export default defineConfig({
-  plugins: [
-    vue(),
-    vueSsrLite({
-      applications: [{
-        id: 'public',
-        definition: 'src/PublicSsrRuntime.ts',
-        exportName: 'publicApplication',
-        template: 'site.html',
-      }],
-    }),
-  ],
+	plugins: [
+		vue(),
+
+		vueSsrLite({
+			applications: [
+				{
+					id: 'website',
+					definition: 'src/website/SsrApplication.ts',
+					exportName: 'websiteApplication',
+					template: 'site.html',
+				},
+			],
+
+			spaEntries: {
+				dashboard: 'index.html',
+			},
+		}),
+	],
 })
 ```
 
-The source `site.html` only needs a mount element:
+### `applications`
 
-```html
-<!doctype html>
-<html lang="en">
-  <head><meta charset="UTF-8"></head>
-  <body><div id="app"></div></body>
-</html>
-```
+Contains applications that use server-side rendering and browser hydration.
+
+### `spaEntries`
+
+Contains normal Vite SPA HTML entries.
 
-Use package-owned lifecycle commands:
+Do not add SPA applications to the `applications` array.
+
+## 5. Add Commands
 
 ```json
 {
-  "scripts": {
-    "dev": "vue-ssr-lite dev --runtime src/PublicSsrRuntime.ts",
-    "build": "vue-ssr-lite build --runtime src/PublicSsrRuntime.ts",
-    "start": "vue-ssr-lite start"
-  }
+	"scripts": {
+		"dev": "vue-ssr-lite dev --runtime src/SsrRuntime.ts",
+		"build": "vue-ssr-lite build --runtime src/SsrRuntime.ts",
+		"start": "vue-ssr-lite start"
+	}
 }
 ```
 
-## Runtime behavior
+## 6. Start Development
 
-- Every render creates a new Vue app, router, Apollo client set/cache, request context, application state, head state, response state, and abort signal.
-- Generated `vue-apollo-client` composables use native Vue server prefetch. After render, named caches are extracted into an inert `application/json` state element. The browser restores them before creating query composables or mounting.
-- Development runs Vite in middleware mode and loads the runtime module through Vite for safe hot updates. Production serves compiled client assets and imports `dist/server/SsrRuntime.js` without loading Vite.
-- Proxy host/protocol headers are ignored unless `trustProxy` is enabled. Cookie forwarding is deny-by-default and requires an allowlist.
-- Head values and JSON-LD are escaped, hydration JSON escapes `<` and Unicode separators, raw HTML templates are never exposed as static assets, and production error responses contain no stack trace or internal path.
-- The default response cache is disabled. An entry may opt into a bounded package memory cache or provide a distributed `SsrResponseCache`; the package owns the application + normalized host + route portion of every key, while `vary` adds publication/data version and locale. Requests with forwarded cookies bypass response caching, and `invalidate` supports key/tag invalidation. Apollo request caches are never reused as response caches.
+```bash
+npm run dev
+```
 
-## Public exports
+Build and run production:
 
-- `vue-ssr-lite`: isomorphic application/runtime definitions, request context, app creation, serialization, and public types.
-- `vue-ssr-lite/client`: browser hydration only; contains no Node server imports.
-- `vue-ssr-lite/server`: SSR renderer, Node HTTP lifecycle, host/proxy/cookie normalization, HTML/assets, health/readiness, response-cache controls, and graceful shutdown.
-- `vue-ssr-lite/vite`: HTML transformation, virtual hydration entries, framework deduplication, and SSR dependency handling.
-- `vue-ssr-lite` CLI: `dev`, `build`, and `start`.
+```bash
+npm run build
+npm run start
+```
 
-The build command produces:
+## SSR-Only Application
 
-```text
-dist/client/**                 compiled HTML, manifest, and hashed browser assets
-dist/server/SsrRuntime.js     consumer runtime/application server bundle
+For a project that only needs SSR:
+
+```ts
+export default defineSsrRuntime({
+	name: 'my-website',
+
+	entries: [
+		{
+			id: 'website',
+			kind: 'ssr',
+			template: 'site.html',
+			hosts: ['*'],
+			application: websiteApplication,
+		},
+	],
+
+	server: {
+		publicConfig: {},
+	},
+})
+```
+
+Vite configuration:
+
+```ts
+vueSsrLite({
+	applications: [
+		{
+			id: 'website',
+			definition: 'src/website/SsrApplication.ts',
+			exportName: 'websiteApplication',
+			template: 'site.html',
+		},
+	],
+})
+```
+
+## SPA-Only Application
+
+A runtime can also serve a normal SPA without an SSR application:
+
+```ts
+export default defineSsrRuntime({
+	name: 'my-dashboard',
+
+	entries: [
+		{
+			id: 'dashboard',
+			kind: 'spa',
+			template: 'index.html',
+			hosts: ['*'],
+		},
+	],
+
+	server: {
+		publicConfig: {},
+	},
+})
+```
+
+Vite configuration still requires at least one SSR application in the current `vueSsrLite()` API. For a completely SPA-only project, use normal Vite without the `vueSsrLite()` plugin.
+
+## Using the Same Vue Plugins
+
+You may use the same plugin configuration in your SPA and SSR applications.
+
+For example:
+
+```ts
+// src/config/apollo.ts
+import { defineApollo } from 'vue-apollo-client'
+
+export default defineApollo(({ publicConfig }) => ({
+	endPoints: {
+		default:
+			publicConfig?.graphqlEndpoint ||
+			import.meta.env.VITE_GRAPHQL_ENDPOINT,
+	},
+}))
 ```
 
-The package build itself produces separate `index.mjs`, `client.mjs`, `server.mjs`, `vite.mjs`, and `cli.mjs` entry points.
+Use it in the SPA:
+
+```ts
+// src/spa/main.ts
+import { createApp } from 'vue'
 
-## Extension points
+import apollo from '../config/apollo'
+import App from './App.vue'
+import router from './router'
 
-Application-specific behavior belongs in the consumer:
+const app = createApp(App)
 
-- `createInitialState` and `createExtension` for typed public/request data;
-- `routes` for static, nested, dynamic, or catch-all routing;
-- `apollo` for endpoints, named clients, cache policies, request-aware context, customer auth callbacks, and uploads;
-- `install` for application plugins and typed provides;
-- `resolveHead` and the request context response state for metadata, status codes, and redirects;
-- runtime `entries` for SPA/SSR host classification and deployment roles;
-- `endpoints` for application-specific robots, sitemaps, or other resources; endpoint tools create isolated Apollo clients and stop them automatically;
-- `readiness` for API/service probes;
-- `logger` and `onMetrics` for structured logging and performance collection.
-- `renderError` for a consumer-owned unavailable/error document while the package enforces an error status, security headers, no-store, and response-lifecycle ownership.
+app.use(apollo)
+app.use(router)
+app.mount('#app')
+```
 
-Anonymous response caching is explicit and remains off unless an SSR entry adds
-`responseCache`. A safe public entry sets a public `cacheControl`, chooses a
-short TTL, and provides publication/locale variation plus invalidation tags:
+Use the same configuration in SSR:
+
+```ts
+// src/website/SsrApplication.ts
+import { defineSsrApplication } from 'vue-ssr-lite'
+
+import apollo from '../config/apollo'
+import App from './App.vue'
+import { websiteRoutes } from './routes'
+
+export const websiteApplication = defineSsrApplication({
+	id: 'website',
+	rootComponent: App,
+	routes: websiteRoutes,
+	plugins: [apollo],
+})
+```
+
+This allows one plugin configuration to support both application types.
+
+You can use the same approach with:
+
+- Apollo and GraphQL
+- Pinia
+- i18n
+- Theme providers
+- REST clients
+- Authentication plugins
+- Analytics plugins
+- Custom Vue plugins
+
+## Using GraphQL in SSR
+
+Keep GraphQL operations in `.graphql` files:
+
+```graphql
+query GetPosts {
+	posts {
+		id
+		title
+	}
+}
+```
+
+Use the generated composable in the Vue page:
+
+```vue
+<script setup lang="ts">
+import { useGetPostsQuery } from '../graphql'
+
+const { result, loading, error } = useGetPostsQuery(
+	{},
+	{
+		ssr: true,
+		fetchPolicy: 'cache-first',
+	},
+)
+</script>
+
+<template>
+	<main>
+		<p v-if="loading">Loading...</p>
+
+		<p v-else-if="error">
+			{{ error.message }}
+		</p>
+
+		<article
+			v-for="post in result?.posts ?? []"
+			:key="post.id">
+			<h2>{{ post.title }}</h2>
+		</article>
+	</main>
+</template>
+```
+
+The same generated composable can also be used inside the SPA.
+
+Use `ssr: true` for public data that should be included in server-rendered HTML.
+
+Use `ssr: false` for browser-only or private queries.
+
+## Using REST APIs
+
+REST APIs can be used through:
+
+- Native `fetch`
+- Axios
+- Ky
+- A custom Vue plugin
+- Another SSR-compatible data package
+
+Example:
+
+```vue
+<script setup lang="ts">
+import { onServerPrefetch, ref } from 'vue'
+
+interface Post {
+	id: string
+	title: string
+}
+
+const posts = ref<Post[]>([])
+
+const loadPosts = async () => {
+	const response = await fetch('https://api.example.com/posts')
+
+	posts.value = await response.json()
+}
+
+onServerPrefetch(loadPosts)
+</script>
+
+<template>
+	<article
+		v-for="post in posts"
+		:key="post.id">
+		<h2>{{ post.title }}</h2>
+	</article>
+</template>
+```
+
+For reusable REST caching and hydration, register an SSR-compatible Vue plugin in the `plugins` array.
+
+## Public Configuration
+
+Pass public values from the runtime:
+
+```ts
+server: {
+  publicConfig: {
+    apiUrl:
+      'https://api.example.com',
+    graphqlEndpoint:
+      'https://api.example.com/graphql',
+  },
+}
+```
+
+Access them in an SSR component:
+
+```ts
+import { useSsrRequestContext } from 'vue-ssr-lite'
+
+const context = useSsrRequestContext()
+
+const apiUrl = context.publicConfig.apiUrl
+```
+
+Only include values that are safe to expose to the browser.
+
+## SEO
+
+Set page metadata from a component:
+
+```ts
+import { useSsrRequestContext } from 'vue-ssr-lite'
+
+const context = useSsrRequestContext()
+
+context.head.value = {
+	title: 'Products',
+	description: 'Browse our latest products.',
+	robots: 'index, follow',
+	canonicalUrl: 'https://example.com/products',
+	ogTitle: 'Products',
+	ogDescription: 'Browse our latest products.',
+	ogImage: 'https://example.com/social.jpg',
+	twitterCard: 'summary_large_image',
+}
+```
+
+## Status Codes
+
+```ts
+const context = useSsrRequestContext()
+
+context.response.statusCode = 404
+```
+
+## Redirects
+
+```ts
+const context = useSsrRequestContext()
+
+context.response.redirect = {
+	location: '/new-page',
+	statusCode: 307,
+}
+```
+
+## Domain Routing
+
+Exact hostname:
+
+```ts
+hosts: ['example.com']
+```
+
+Subdomains:
+
+```ts
+hosts: ['*.example.com']
+```
+
+Exact hostname and subdomains:
+
+```ts
+hosts: ['example.com', '*.example.com']
+```
+
+Catch-all:
+
+```ts
+hosts: ['*']
+```
+
+Do not include protocols or paths in host values.
+
+Set `server.trustProxy` to `true` only when the Node process sits behind a trusted reverse proxy. Then `X-Forwarded-Host` and `X-Forwarded-Proto` are used for host matching and absolute URLs. Leave it `false` for direct local traffic.
+
+## Runtime Roles
+
+Roles let one codebase and one Docker image run as different process modes.
+
+- Set `server.role` to the active mode for this process.
+- Set `roles` on each entry to list which modes may serve that entry.
+- Omit `roles` (or omit `server.role`) to keep an entry available in every mode.
+
+Role names are application-defined strings. Common patterns:
+
+| Mode | Typical use |
+| --- | --- |
+| `unified` | Local development or a single process that serves every entry |
+| A private role | SPA / admin / back-office only |
+| A public role | SSR website / marketing / storefront only |
+
+Example:
+
+```ts
+export default defineSsrRuntime({
+	name: 'my-platform',
+
+	entries: [
+		{
+			id: 'admin',
+			kind: 'spa',
+			template: 'index.html',
+			hosts: ['app.example.com', 'localhost'],
+			roles: ['unified', 'admin'],
+		},
+		{
+			id: 'website',
+			kind: 'ssr',
+			template: 'site.html',
+			hosts: ['*'],
+			roles: ['unified', 'website'],
+			application: websiteApplication,
+		},
+	],
+
+	server: {
+		role: process.env.APP_RUNTIME || 'unified',
+		publicConfig: {},
+	},
+})
+```
+
+With that setup:
+
+- `APP_RUNTIME=unified` serves both entries (host routing still applies).
+- `APP_RUNTIME=admin` serves only the SPA entry.
+- `APP_RUNTIME=website` serves only the SSR entry.
+
+If a host matches an entry that the current role does not allow, the server responds with `421`.
+
+You can also load role-specific code only when needed:
+
+```ts
+export default async () => {
+	const role = process.env.APP_RUNTIME || 'unified'
+	const websiteApplication =
+		role === 'admin'
+			? undefined
+			: (await import('./website/SsrApplication')).websiteApplication
+
+	return defineSsrRuntime({
+		name: 'my-platform',
+		entries: [
+			{
+				id: 'admin',
+				kind: 'spa',
+				template: 'index.html',
+				hosts: ['app.example.com'],
+				roles: ['unified', 'admin'],
+			},
+			{
+				id: 'website',
+				kind: 'ssr',
+				template: 'site.html',
+				hosts: ['*'],
+				roles: ['unified', 'website'],
+				application: websiteApplication,
+			},
+		],
+		server: {
+			role,
+			publicConfig: {},
+		},
+	})
+}
+```
+
+`defineSsrRuntime` accepts either a plain object or an async factory function.
+
+## Custom Endpoints
+
+```ts
+endpoints: [
+	{
+		id: 'robots',
+
+		match(request) {
+			return request.pathname === '/robots.txt'
+		},
+
+		handle() {
+			return {
+				statusCode: 200,
+				body: 'User-agent: *\nAllow: /',
+				headers: {
+					'content-type': 'text/plain; charset=utf-8',
+				},
+			}
+		},
+	},
+]
+```
+
+Custom endpoints can be used for:
+
+- `robots.txt`
+- `sitemap.xml`
+- Verification files
+- Public JSON endpoints
+
+## Health Checks
+
+The server includes:
+
+```text
+/healthz
+/readyz
+```
+
+Add readiness checks:
+
+```ts
+readiness: [
+	{
+		id: 'api',
+
+		async run() {
+			const response = await fetch('https://api.example.com/health')
+
+			if (!response.ok) {
+				throw new Error('API is unavailable.')
+			}
+		},
+	},
+]
+```
+
+## Response Caching
 
 ```ts
 import { createSsrMemoryResponseCache } from 'vue-ssr-lite/server'
 
-const publicPages = createSsrMemoryResponseCache({
-  maxEntries: 500,
-  maxBytes: 32 * 1024 * 1024,
+const responseCache = createSsrMemoryResponseCache({
+	maxEntries: 500,
 })
+```
 
-// In the SSR runtime entry:
-responseCache: {
-  store: publicPages,
-  ttlMs: 30_000,
-  vary: (request) => request.publicConfig.publicationVersion,
-  tags: (request) => [`host:${request.host}`],
-},
-cacheControl: 'public, max-age=30',
+Add it to an SSR entry:
 
-// On publication: publicPages.invalidate({ tags: [`host:${hostname}`] })
+```ts
+{
+  id: 'website',
+  kind: 'ssr',
+  template: 'site.html',
+  hosts: ['*'],
+  application: websiteApplication,
+
+  responseCache: {
+    store: responseCache,
+    ttlMs: 60_000,
+  },
+}
 ```
 
-For multi-process deployments, provide the same interface backed by a shared
-cache. Compression is intentionally integrated at the reverse-proxy/platform
-layer so precompressed hashed assets and dynamic HTML use one deployment-wide
-policy without buffering a second copy inside the Node process.
+## Cookie Filtering
+
+SSR requests can forward a filtered `Cookie` header to upstream APIs.
+
+```ts
+server: {
+  cookieAllowlist: ['session'],
+  cookieDenylist: ['admin_token', 'refresh_token'],
+  publicConfig: {},
+}
+```
+
+- If `cookieAllowlist` is non-empty, only listed cookies are forwarded.
+- `cookieDenylist` always removes matching cookies.
+- Leave both empty when the browser talks to the API directly and SSR needs no cookies.
+
+## Server Configuration
+
+```ts
+server: {
+  host: '0.0.0.0',
+  port: 4173,
+  role: 'unified',
+
+  publicConfig: {},
+
+  requestTimeoutMs: 15_000,
+  shutdownTimeoutMs: 10_000,
+
+  healthPath: '/healthz',
+  readinessPath: '/readyz',
+
+  trustProxy: false,
+
+  cookieAllowlist: [],
+  cookieDenylist: [],
+
+  logger: {
+    info: (event, details) => console.info(event, details ?? ''),
+    warn: (event, details) => console.warn(event, details ?? ''),
+    error: (event, details) => console.error(event, details ?? ''),
+  },
+}
+```
+
+`/healthz` and `/readyz` include the active `role` in their JSON responses.
+
+## Summary
 
-Endpoint handlers return plain response values; they never receive Node response objects. Application code never calls `renderToString`, extracts/restores Apollo state, injects HTML, serves assets, starts a server, or performs request cleanup.
+For a SPA:
 
-## Dependency and bundling contract
+1. Create a normal Vue `main.ts`.
+2. Create a normal HTML entry.
+3. Register the HTML file in `spaEntries`.
+4. Add a runtime entry with `kind: 'spa'`.
 
-Vue, Vue Router, `@vue/server-renderer`, Apollo Client, GraphQL, Vite, and `vue-apollo-client` are peers so the consumer owns one compatible runtime instance. The Vite plugin deduplicates them. The Apollo/GraphQL ESM/CJS cluster is inlined into the SSR consumer bundle; Vue, Vue Router, and the renderer remain external so Node resolves their official runtime exports. Application-specific browser-oriented UI dependencies remain the consumer's documented `ssr.noExternal` responsibility.
+For SSR:
 
-Node-only modules are reachable only from `/server`, `/vite`, and the CLI. Browser hydration imports `/client`, preventing `node:http`, filesystem, and Vite code from entering client output.
+1. Create the Vue root component and routes.
+2. Define it with `defineSsrApplication()`.
+3. Create an SSR HTML template.
+4. Register it in `applications`.
+5. Add a runtime entry with `kind: 'ssr'`.
 
-## Error and redirect contract
+Optional for multi-mode deployments:
 
-Consumers set `context.response.statusCode`, headers, or a redirect. Relative and same-origin redirects are allowed by default. A canonical-domain redirect must explicitly set `allowExternal: true`. Invalid configuration, hosts, templates, and application registrations fail predictably. Timeouts return 504; unhandled rendering failures return 500; non-HTML misses return JSON 404; disabled deployment-role entries return 421.
+1. Choose role names for your project.
+2. Set `server.role` from an environment variable.
+3. Restrict each entry with `roles`.
 
-## Validation
+Both application types can run from the same project, build process, and production server.
 
-Focused tests cover host/proxy/cookie behavior, safe state/head injection, concurrent request isolation, router/state/head separation, Apollo cache isolation/restoration, and server lifecycle. Consumer integrations must additionally validate their routes, domains, templates, SEO, GraphQL failures, real-browser hydration warnings and duplicate requests, Docker startup, reverse-proxy headers, and shutdown behavior.
+## License
 
-See [SsrPerformanceBaseline.md](./docs/SsrPerformanceBaseline.md) and [SsrBuiltoCompatibility.md](./docs/SsrBuiltoCompatibility.md).
+MIT