vue-ssr-lite 0.0.3

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "vue-ssr-lite",
+  "version": "0.0.3",
+  "description": "Low-configuration Vue 3 + Vite server-side rendering: engine, standalone server, hydration runtime, Apollo SSR adapter, and Vite integration with virtual entries.",
+  "author": "safdar-azeem",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "vue-ssr-lite": "./bin/vue-ssr-lite.mjs"
+  },
+  "files": [
+    "bin",
+    "engine",
+    "server",
+    "runtime",
+    "apollo",
+    "vite",
+    "index.js",
+    "index.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./engine": {
+      "types": "./engine/index.d.ts",
+      "default": "./engine/index.js"
+    },
+    "./server": {
+      "types": "./server/index.d.ts",
+      "default": "./server/index.js"
+    },
+    "./runtime/server": {
+      "types": "./runtime/server.d.ts",
+      "default": "./runtime/SsrRuntimeServer.js"
+    },
+    "./runtime/client": {
+      "types": "./runtime/client.d.ts",
+      "default": "./runtime/SsrRuntimeClient.js"
+    },
+    "./apollo": {
+      "types": "./apollo/index.d.ts",
+      "default": "./apollo/SsrApolloAdapter.js"
+    },
+    "./vite": {
+      "types": "./vite/index.d.ts",
+      "default": "./vite/SsrVitePlugin.js"
+    }
+  },
+  "peerDependencies": {
+    "@apollo/client": ">=3.10.0 <4",
+    "@vue/server-renderer": "^3.5.0",
+    "vite": ">=5.0.0",
+    "vue": "^3.5.0",
+    "vue-router": ">=4.4.0 <6"
+  },
+  "peerDependenciesMeta": {
+    "@apollo/client": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    },
+    "vue-router": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "preversion": "npm test",
+    "prepublishOnly": "npm test",
+    "release:patch": "npm version patch && npm publish",
+    "release:minor": "npm version minor && npm publish",
+    "release:major": "npm version major && npm publish"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/safdar-azeem/vue-ssr-lite.git"
+  },
+  "keywords": [
+    "vue",
+    "vite",
+    "ssr",
+    "hydration",
+    "apollo"
+  ]
+}

package/runtime/SsrRuntimeApp.js

@@ -0,0 +1,94 @@
+// SsrRuntimeApp — shared application assembly for server render and browser
+// hydration. Both sides run this exact function with the same application
+// definition, so the server and client component trees cannot drift.
+
+import { createSSRApp } from 'vue'
+import { SSR_CONTEXT_KEY, createSsrRequestContext } from './SsrRuntimeContext.js'
+
+const resolveConfig = (definition, config) => {
+	if (config != null) return config
+	if (typeof definition.config === 'function') return definition.config()
+	return definition.config ?? {}
+}
+
+/**
+ * Build the app, optional router, optional Apollo clients, and request
+ * context from one application definition.
+ *
+ * Integrations are loaded on demand: vue-router only when the definition
+ * declares routes or a router factory, the Apollo adapter only when the
+ * definition declares an apollo block. Applications without them never load
+ * either library through this path.
+ */
+export const createSsrRuntimeApp = async (definition, options) => {
+	const { server, url, host, cookie, state } = options
+	const config = resolveConfig(definition, options.config)
+	const context = createSsrRequestContext({
+		url,
+		host,
+		cookie,
+		config,
+		state,
+		server,
+	})
+
+	const app = createSSRApp(definition.root)
+	app.provide(SSR_CONTEXT_KEY, context)
+
+	let router = null
+	if (typeof definition.router === 'function') {
+		router = await definition.router({ server, context })
+		app.use(router)
+	} else if (Array.isArray(definition.routes)) {
+		const { createRouter, createMemoryHistory, createWebHistory } = await import(
+			'vue-router'
+		)
+		router = createRouter({
+			history: server ? createMemoryHistory() : createWebHistory(),
+			routes: definition.routes,
+			...(definition.scrollBehavior
+				? { scrollBehavior: definition.scrollBehavior }
+				: {}),
+		})
+		app.use(router)
+	}
+
+	let apollo = null
+	if (definition.apollo) {
+		const { createSsrApolloClients } = await import(
+			'../apollo/SsrApolloAdapter.js'
+		)
+		apollo = createSsrApolloClients(definition.apollo, {
+			server,
+			cookie: context.cookie,
+			config,
+			state: context.state,
+			context,
+		})
+		context.apollo = apollo.defaultClient
+		definition.apollo.install?.(app, apollo.clients, context)
+	}
+
+	if (typeof definition.setup === 'function') {
+		await definition.setup({
+			app,
+			router,
+			context,
+			apollo: apollo?.defaultClient ?? null,
+			apolloClients: apollo?.clients ?? null,
+			server,
+		})
+	}
+
+	return {
+		app,
+		router,
+		context,
+		config,
+		/** Assemble the final hydration state (Apollo extraction included). */
+		extractState: () => {
+			if (apollo) apollo.extractInto(context.state)
+			return context.state
+		},
+	}
+}

package/runtime/SsrRuntimeClient.js

@@ -0,0 +1,72 @@
+// SsrRuntimeClient — browser hydration bootstrap.
+//
+// Reads the serialized config and state globals, removes server-rendered head
+// tags (the client-side head/SEO layer re-creates them), rebuilds the exact
+// same application from the shared definition, replays the current route,
+// hydrates, and cleans the globals only after a successful mount so async
+// boundaries keep access while they resolve.
+
+import { createSsrRuntimeApp } from './SsrRuntimeApp.js'
+
+const DEFAULTS = {
+	configKey: '__SSR_CONFIG__',
+	stateKey: '__SSR_STATE__',
+	headAttribute: 'data-ssr-head',
+	mountSelector: '#app',
+}
+
+export const hydrateSsrApp = async (definition, options = {}) => {
+	const { configKey, stateKey, headAttribute, mountSelector } = {
+		...DEFAULTS,
+		...definition.hydration,
+		...options,
+	}
+
+	const config = window[configKey]
+	const state = window[stateKey] ?? {}
+
+	document.head
+		.querySelectorAll(`[${headAttribute}]`)
+		.forEach((element) => element.remove())
+
+	try {
+		const runtime = await createSsrRuntimeApp(definition, {
+			server: false,
+			url: window.location.href,
+			host: window.location.host,
+			config,
+			state,
+		})
+		const { app, router } = runtime
+
+		// Concise, structured runtime error reporting (kept in production).
+		app.config.errorHandler = (error, instance, info) => {
+			const component =
+				instance?.$?.type?.__name ?? instance?.$?.type?.name ?? 'anonymous'
+			console.error(`[vue-ssr-lite] error in <${component}> (${info}):`, error)
+		}
+
+		if (router) {
+			await router.push(
+				`${window.location.pathname}${window.location.search}${window.location.hash}`,
+			)
+			await router.isReady()
+		}
+
+		app.mount(mountSelector)
+
+		// Clean globals only after a successful mount. The runtime captured the
+		// state object by reference, so async setup keeps access while
+		// <Suspense> resolves.
+		delete window[configKey]
+		delete window[stateKey]
+
+		return runtime
+	} catch (error) {
+		console.error(
+			'[vue-ssr-lite] Hydration bootstrap failed; the server-rendered page may not be interactive:',
+			error,
+		)
+		throw error
+	}
+}

package/runtime/SsrRuntimeContext.js

@@ -0,0 +1,44 @@
+// SsrRuntimeContext — the per-request (and per-hydration) application context.
+//
+// One context is created for every server request and once in the browser at
+// hydration. Nothing here is module-scope: concurrent SSR requests can never
+// share URL, state, head, status, or data clients.
+
+import { inject, ref } from 'vue'
+
+export const SSR_CONTEXT_KEY = Symbol('vue-ssr-lite:context')
+
+export const createSsrRequestContext = ({
+	url,
+	host,
+	cookie,
+	config,
+	state,
+	server,
+}) => ({
+	/** Full request URL (server) or current location (browser). */
+	url: url instanceof URL ? url : new URL(url),
+	host,
+	/** Allowlist-filtered Cookie header. Server only; undefined in the browser. */
+	cookie: server ? cookie : undefined,
+	/** Serializable public configuration. Optional; empty object when unused. */
+	config: config ?? {},
+	/** Hydration state bag. Consumers may write fields; Apollo state is managed. */
+	state: state ?? {},
+	/** Head payload ref rendered into the HTML document on the server. */
+	head: ref(null),
+	/** Mutable response controls honored by the engine. */
+	response: { statusCode: 200, redirect: null },
+	server: Boolean(server),
+})
+
+/** Typed access to the request context from any component or composable. */
+export const useSsrContext = () => {
+	const context = inject(SSR_CONTEXT_KEY, null)
+	if (!context) {
+		throw new Error(
+			'vue-ssr-lite: the SSR request context is not installed. Components using useSsrContext must render inside an app created by vue-ssr-lite.',
+		)
+	}
+	return context
+}

package/runtime/SsrRuntimeServer.js

@@ -0,0 +1,63 @@
+// SsrRuntimeServer — server-side render orchestration.
+//
+// createSsrRender turns an application definition into the render function
+// the engine calls per request: fresh app, route replay and readiness,
+// render-to-string with teleport capture, state extraction, and status
+// resolution. This file is the server half of the runtime and is only ever
+// evaluated inside the SSR bundle.
+
+import { renderToString } from '@vue/server-renderer'
+import { createSsrRuntimeApp } from './SsrRuntimeApp.js'
+
+export const createSsrRender = (definition) => {
+	return async (request) => {
+		const url = new URL(request.url)
+		const runtime = await createSsrRuntimeApp(definition, {
+			server: true,
+			url,
+			host: request.host,
+			cookie: request.cookie,
+			config: request.config,
+			state: {},
+		})
+		const { app, router, context } = runtime
+
+		if (router) {
+			await router.push(`${url.pathname}${url.search}${url.hash}`)
+			await router.isReady()
+		}
+
+		const ssrContext = {}
+		const html = await renderToString(app, ssrContext)
+		const state = runtime.extractState()
+
+		return {
+			html,
+			head: context.head.value ?? definition.head ?? null,
+			state,
+			config: runtime.config,
+			statusCode: context.response.statusCode,
+			redirect: context.response.redirect,
+			/**
+			 * SSR markup for content teleported to <body> (closed panels and
+			 * modals render placeholders). Must be injected into the served
+			 * <body> or hydration reports a teleport mismatch.
+			 */
+			teleports: ssrContext.teleports?.body ?? '',
+		}
+	}
+}
+
+/**
+ * Startup probe used by server preflight: verifies the definition is loadable
+ * and structurally sound before the server accepts traffic.
+ */
+export const createSsrReadyProbe = (definition) => {
+	return async () => {
+		if (!definition || !definition.root) {
+			throw new Error(
+				'vue-ssr-lite: the application definition is missing its root component.',
+			)
+		}
+	}
+}

package/runtime/client.d.ts

@@ -0,0 +1,20 @@
+import type { App } from 'vue'
+import type { Router } from 'vue-router'
+import type { SsrAppDefinition, SsrRequestContext } from '../index'
+
+export interface SsrHydrateOptions {
+	configKey?: string
+	stateKey?: string
+	headAttribute?: string
+	mountSelector?: string
+}
+
+export declare const hydrateSsrApp: (
+	definition: SsrAppDefinition,
+	options?: SsrHydrateOptions,
+) => Promise<{
+	app: App
+	router: Router | null
+	context: SsrRequestContext
+	config: Record<string, unknown>
+}>

package/runtime/server.d.ts

@@ -0,0 +1,26 @@
+import type { SsrAppDefinition, SsrHeadPayload } from '../index'
+
+export interface SsrRenderRequest {
+	url: string
+	host: string
+	cookie?: string
+	config?: Record<string, unknown>
+}
+
+export interface SsrRenderResult {
+	html: string
+	head: SsrHeadPayload | null
+	state: Record<string, unknown>
+	config: Record<string, unknown>
+	statusCode: number
+	redirect: string | null
+	teleports: string
+}
+
+export declare const createSsrRender: (
+	definition: SsrAppDefinition,
+) => (request: SsrRenderRequest) => Promise<SsrRenderResult>
+
+export declare const createSsrReadyProbe: (
+	definition: SsrAppDefinition,
+) => () => Promise<void>