vue-ssr-lite 0.0.3

package/vite/SsrVitePlugin.js

@@ -0,0 +1,218 @@
+// SsrVitePlugin — the package's Vite integration (ships in version one).
+//
+// Owns everything a consumer would otherwise wire by hand: generated
+// (virtual) client and server entries, HTML marker management, client-entry
+// script injection, client/server build orchestration, and a serialized
+// runtime manifest so the production server starts without build tooling.
+//
+// A normal consumer's entire integration is:
+//   vueSsrLite({ app: './src/MySsrApp.ts' })
+// plus the package commands (vue-ssr-lite dev | build | start).
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { ensureSsrMarkers } from '../engine/SsrEngineHtml.js'
+
+export const SSR_VIRTUAL_CLIENT = 'virtual:vue-ssr-lite/client'
+export const SSR_VIRTUAL_SERVER = 'virtual:vue-ssr-lite/server'
+const RUNTIME_MANIFEST = '.vue-ssr-lite.json'
+
+const toPosix = (value) => value.replaceAll('\\', '/')
+
+export const vueSsrLite = (pluginOptions = {}) => {
+	if (!pluginOptions.app) {
+		throw new Error(
+			'vue-ssr-lite/vite: the "app" option (path to the application definition module) is required.',
+		)
+	}
+
+	let root = process.cwd()
+	let isSsrBuild = false
+	let command = 'serve'
+
+	const template = pluginOptions.template || 'index.html'
+	const ssrName = pluginOptions.name || 'ssr'
+	const mountSelector = pluginOptions.mountSelector || '#app'
+	const spaApps = (pluginOptions.spa || []).map((app) => ({
+		type: 'spa',
+		hosts: [],
+		...app,
+	}))
+
+	const appModulePath = () => toPosix(resolve(root, pluginOptions.app))
+
+	const serverOptions = () => ({
+		apps: [
+			{
+				name: ssrName,
+				type: 'ssr',
+				template,
+				hosts: pluginOptions.hosts || [],
+				default: true,
+			},
+			...spaApps.map(({ name, template: spaTemplate, hosts, localhost }) => ({
+				name,
+				type: 'spa',
+				template: spaTemplate,
+				hosts: hosts || [],
+				...(localhost ? { localhost } : {}),
+			})),
+		],
+		serverEntry: SSR_VIRTUAL_SERVER,
+		bundlePath: 'dist/server/entry.mjs',
+		clientDir: 'dist/client',
+		serviceName: pluginOptions.serviceName,
+		globals: pluginOptions.globals,
+		headAttribute: pluginOptions.headAttribute,
+		defaultHead: pluginOptions.defaultHead,
+		cookieAllowlist: pluginOptions.cookieAllowlist,
+		cookieDenylist: pluginOptions.cookieDenylist,
+		renderTimeoutMs: pluginOptions.renderTimeoutMs,
+		port: pluginOptions.port,
+	})
+
+	const clientEntryCode = () =>
+		[
+			`import definition from '${appModulePath()}'`,
+			`import { hydrateSsrApp } from 'vue-ssr-lite/runtime/client'`,
+			`hydrateSsrApp(definition, ${JSON.stringify({
+				...(pluginOptions.globals || {}),
+				...(pluginOptions.headAttribute
+					? { headAttribute: pluginOptions.headAttribute }
+					: {}),
+				mountSelector,
+			})})`,
+		].join('\n')
+
+	const serverEntryCode = () =>
+		[
+			`import definition from '${appModulePath()}'`,
+			`import { createSsrRender, createSsrReadyProbe } from 'vue-ssr-lite/runtime/server'`,
+			`export const render = createSsrRender(definition)`,
+			`export const assertReady = createSsrReadyProbe(definition)`,
+		].join('\n')
+
+	return {
+		name: 'vue-ssr-lite',
+		enforce: 'pre',
+
+		api: {
+			getServerOptions: serverOptions,
+		},
+
+		config(config, env) {
+			command = env.command
+			isSsrBuild = Boolean(env.isSsrBuild)
+			const configRoot = resolve(config.root || process.cwd())
+
+			if (command !== 'build') return undefined
+
+			if (isSsrBuild) {
+				return {
+					build: {
+						outDir: 'dist/server',
+						emptyOutDir: true,
+						ssr: true,
+						rollupOptions: {
+							input: { entry: SSR_VIRTUAL_SERVER },
+							output: { entryFileNames: '[name].mjs' },
+						},
+					},
+				}
+			}
+
+			const input = { [ssrName]: resolve(configRoot, template) }
+			for (const spa of spaApps) {
+				input[spa.name] = resolve(configRoot, spa.template)
+			}
+			return {
+				build: {
+					outDir: 'dist/client',
+					emptyOutDir: true,
+					manifest: true,
+					rollupOptions: { input },
+				},
+			}
+		},
+
+		configResolved(config) {
+			root = config.root
+		},
+
+		resolveId(id) {
+			if (id === SSR_VIRTUAL_CLIENT || id === SSR_VIRTUAL_SERVER) return id
+			// The SSR build's rollup input references the virtual id as a path.
+			if (id.endsWith(SSR_VIRTUAL_SERVER)) return SSR_VIRTUAL_SERVER
+			return undefined
+		},
+
+		load(id) {
+			if (id === SSR_VIRTUAL_CLIENT) return clientEntryCode()
+			if (id === SSR_VIRTUAL_SERVER) return serverEntryCode()
+			return undefined
+		},
+
+		transformIndexHtml: {
+			order: 'pre',
+			handler(html, context) {
+				const filename = toPosix(context.filename || '')
+				if (!filename.endsWith(`/${template}`) && filename !== toPosix(resolve(root, template))) {
+					return html
+				}
+				let transformed = ensureSsrMarkers(html, { mountSelector })
+				if (!transformed.includes(SSR_VIRTUAL_CLIENT)) {
+					const src = context.server
+						? `/@id/${SSR_VIRTUAL_CLIENT}`
+						: SSR_VIRTUAL_CLIENT
+					transformed = transformed.replace(
+						/<\/body>/i,
+						`\t<script type="module" src="${src}"></script>\n</body>`,
+					)
+				}
+				return transformed
+			},
+		},
+
+		writeBundle() {
+			// Emit the runtime manifest with the client build so the production
+			// server (`vue-ssr-lite start`) needs no build tooling and no Vite.
+			if (command !== 'build' || isSsrBuild) return
+			const outDir = resolve(root, 'dist/client')
+			if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true })
+			writeFileSync(
+				resolve(outDir, RUNTIME_MANIFEST),
+				JSON.stringify(serverOptions(), null, '\t'),
+			)
+		},
+	}
+}
+
+/**
+ * SSR dependency-inlining preset for the Apollo cluster. The @apollo/client
+ * subpaths expose CJS entries whose named exports Node cannot statically
+ * analyze; graphql without an exports map is a dual-package hazard. Consumers
+ * spread this into their Vite `ssr.noExternal` alongside their own UI
+ * libraries. (Knowledge ported from the audited ERP build configuration.)
+ */
+export const ssrApolloNoExternal = [
+	'@apollo/client',
+	'graphql',
+	'graphql-tag',
+	'optimism',
+	'ts-invariant',
+	'zen-observable-ts',
+	'zen-observable',
+	'symbol-observable',
+	/^@wry\//,
+]
+
+/** Read a template file and report whether it already carries SSR markers (debug aid). */
+export const inspectSsrTemplate = (templatePath) => {
+	const html = readFileSync(resolve(templatePath), 'utf8')
+	return {
+		hasMarkers: html.includes('<!--app-html-->'),
+		html: ensureSsrMarkers(html),
+	}
+}
+
+export default vueSsrLite

package/vite/index.d.ts

@@ -0,0 +1,37 @@
+import type { Plugin } from 'vite'
+
+export interface SsrSpaAppOptions {
+	name: string
+	template: string
+	hosts?: string[]
+	/** Serve this SPA for bare localhost hosts in development. */
+	localhost?: boolean
+}
+
+export interface SsrVitePluginOptions {
+	/** Path to the module default-exporting defineSsrApp(...). Required. */
+	app: string
+	/** SSR HTML template (default 'index.html'). */
+	template?: string
+	/** Name of the SSR app for classification and build entry (default 'ssr'). */
+	name?: string
+	/** Host patterns served by SSR; empty means every unmatched host. */
+	hosts?: string[]
+	/** Additional SPA entries (builder/admin applications). */
+	spa?: SsrSpaAppOptions[]
+	mountSelector?: string
+	serviceName?: string
+	globals?: { configKey?: string; stateKey?: string }
+	headAttribute?: string
+	defaultHead?: string
+	cookieAllowlist?: string[]
+	cookieDenylist?: string[]
+	renderTimeoutMs?: number
+	port?: number
+}
+
+export declare const SSR_VIRTUAL_CLIENT: string
+export declare const SSR_VIRTUAL_SERVER: string
+export declare const ssrApolloNoExternal: Array<string | RegExp>
+export declare const vueSsrLite: (options: SsrVitePluginOptions) => Plugin
+export default vueSsrLite