@octanejs/vite-plugin 0.1.3 → 0.1.5

package/src/project-codegen.js

@@ -1,19 +1,28 @@
+// @ts-check
 /** @import { ResolvedConfig } from 'vite' */
 
 import fs from 'node:fs';
 import path from 'node:path';
 
 export const RESOLVED_ADAPTER_BROWSER_STUB_ID = '\0octane:adapter-browser-stub';
+// Server-only deploy/adapter packages: client-side imports of these specifiers
+// resolve to the browser stub below instead of the real module (whose graph
+// pulls node builtins). Every published adapter package MUST be listed here,
+// and its public exports added to the stub.
 export const SERVER_ONLY_ADAPTER_IDS = new Set([
 	'@ripple-ts/adapter-node',
 	'@ripple-ts/adapter-bun',
 	'@ripple-ts/adapter-vercel',
+	'@octanejs/adapter-vercel',
 ]);
 
 /** @type {Map<string, string>} */
 const generated_file_cache = new Map();
 
 /**
+ * The browser stand-in shared by every SERVER_ONLY_ADAPTER_IDS package — it
+ * must export the UNION of their public names, each failing loudly on use
+ * (never at import, so merely reaching the module keeps the app alive).
  * @returns {string}
  */
 export function create_adapter_browser_stub_source() {
@@ -27,6 +36,12 @@ export function nodeRequestToWebRequest() {
 export function webResponseToNodeResponse() {
   throw new Error('[octane] Node response helpers cannot run in the browser.');
 }
+export function vercel() {
+  throw new Error('[octane] Deploy adapters cannot run in the browser.');
+}
+export function adapt() {
+  throw new Error('[octane] Deploy adapters cannot run in the browser.');
+}
 `;
 }
 
@@ -67,8 +82,15 @@ export function write_project_generated_file(viteConfig, name, source) {
  * the browser would drag the plugin (and the server adapter) — with their
  * `node:fs` imports — into the client graph and throw at module-eval. Instead
  * the server serializes everything needed into #__octane_data ({ entry,
- * exportName, layout, params }), and this entry dynamic-imports the page/layout
- * from there. (A static, build-analyzable import map is a Phase-2 concern.)
+ * exportName, layout, params, url, preHydrate }), and this entry
+ * dynamic-imports the page/layout from there.
+ *
+ * `staticEntries` (production builds) lists every module path the server can
+ * name in #__octane_data — page entries, layouts, and the preHydrate hook.
+ * Each becomes a STATIC `() => import('/src/…')` in a lookup map, so Rollup
+ * sees, chunks, and hashes them; the runtime falls back to the hidden dynamic
+ * import only for paths outside the map (the dev case, where the map is empty
+ * and Vite serves any module by URL).
  *
  * octane specifics:
  *   - `import { hydrateRoot } from 'octane'` (NO `mount`).
@@ -80,20 +102,47 @@ export function write_project_generated_file(viteConfig, name, source) {
  *     closure — mirroring the server `createLayoutWrapper`.
  *   - hydrateRoot() itself locates/consumes the <script data-octane-suspense>
  *     seed inside #root, so the entry does nothing special for suspense.
+ *   - `preHydrate` (config `router.preHydrate`, a Vite-root module path) is
+ *     imported and its default export awaited BEFORE hydrateRoot — the hook an
+ *     app-level client router uses to commit its match tree so the first
+ *     hydration pass adopts the same resolved tree the server rendered.
  *
  * `getComponentExport` mirrors routes.js `get_component_export` (route named
  * export > default > first PascalCase) so server and client pick the SAME
  * component.
  *
- * @param {{ configPath?: string, staticEntries?: string[] }} [_options]
+ * @param {{ configPath?: string, staticEntries?: string[] }} [options]
  * @returns {string}
  */
-export function create_client_entry_source(_options) {
+export function create_client_entry_source(options = {}) {
+	const staticEntries = [...new Set(options.staticEntries ?? [])];
+	const static_map_lines = staticEntries
+		.map((entry) => `  ${JSON.stringify(entry)}: () => import(${JSON.stringify(entry)}),`)
+		.join('\n');
+
 	return `// Auto-generated by @octanejs/vite-plugin.
 // This file is written to Vite's cacheDir/project folder.
 
 import { hydrateRoot } from 'octane';
 
+// Static import map (production): every module the server may name in
+// #__octane_data, as bundle-analyzable dynamic imports. Empty in dev.
+const routeModules = {
+${static_map_lines}
+};
+
+// Dynamic import Vite's import-analysis can NOT see: its rewrite appends
+// '?import' to variable dynamic imports, and a queried URL evaluates as a
+// SECOND browser module instance — so the page (or the preHydrate hook) would
+// no longer share module singletons with statically-imported copies of the
+// same files (e.g. a client router the app also imports directly).
+const dynamicImport = new Function('specifier', 'return import(specifier)');
+
+function importModule(path) {
+  const loader = routeModules[path];
+  return loader ? loader() : dynamicImport(path);
+}
+
 function getComponentExport(module, exportName) {
   // Explicit export name requires an exact match; do NOT fall back, so a
   // typo'd route renders nothing rather than the wrong component.
@@ -110,13 +159,13 @@ function getComponentExport(module, exportName) {
       console.error('[octane] Unable to hydrate: missing #__octane_data or #root.');
       return;
     }
-    const data = JSON.parse(el.textContent || '{}'); // { entry, exportName, layout, params }
+    const data = JSON.parse(el.textContent || '{}'); // { entry, exportName, layout, params, url, preHydrate }
     if (!data.entry) {
       console.error('[octane] Unable to hydrate: no route entry in #__octane_data.');
       return;
     }
 
-    const pageMod = await import(/* @vite-ignore */ data.entry);
+    const pageMod = await importModule(data.entry);
     const Component = getComponentExport(pageMod, data.exportName ?? undefined);
     if (!Component) {
       console.error('[octane] Unable to hydrate: no component export for', data.entry);
@@ -124,23 +173,34 @@ function getComponentExport(module, exportName) {
     }
 
     const params = data.params;
+    const url = data.url;
+
+    // Run the app's pre-hydrate hook (config \`router.preHydrate\`) before the
+    // first hydration render — e.g. a client router committing its match tree
+    // so hydration adopts the same resolved tree the server rendered.
+    if (data.preHydrate) {
+      const preMod = await importModule(data.preHydrate);
+      const hook = preMod.default;
+      if (typeof hook === 'function') await hook({ url, params });
+    }
 
+    // Props mirror the server render exactly: { params, url }.
     if (data.layout) {
-      const layoutMod = await import(/* @vite-ignore */ data.layout);
+      const layoutMod = await importModule(data.layout);
       const Layout = getComponentExport(layoutMod);
       if (Layout) {
-        // children is a ComponentBody closing over params; octane's childSlot
-        // invokes a function child PROPS-FIRST as \`({}, block, extra)\`, so we
-        // ignore the empty props and render the page with its real \`{ params }\`,
-        // threading the scope + extra — mirroring the server createLayoutWrapper
-        // (which is scope-first on the server ABI) so the markers line up.
-        const children = (_props, scope, extra) => Component({ params }, scope, extra);
-        hydrateRoot(target, Layout, { params, children });
+        // children is a ComponentBody closing over the page props; octane's
+        // childSlot invokes a function child PROPS-FIRST as \`({}, block, extra)\`,
+        // so we ignore the empty props and render the page with its real
+        // \`{ params, url }\`, threading the scope + extra — mirroring the server
+        // createLayoutWrapper so the markers line up.
+        const children = (_props, scope, extra) => Component({ params, url }, scope, extra);
+        hydrateRoot(target, Layout, { params, url, children });
         return;
       }
     }
 
-    hydrateRoot(target, Component, { params });
+    hydrateRoot(target, Component, { params, url });
   } catch (error) {
     console.error('[octane] Failed to bootstrap client hydration.', error);
   }

package/src/resolve-config.js

@@ -0,0 +1,171 @@
+// @ts-check
+/**
+ * Config validation + defaults — `resolveOctaneConfig` and its validators.
+ *
+ * Kept in a module with NO heavy imports (no vite, no octane/compiler) because
+ * it is part of the PRODUCTION server bundle's graph: the generated server
+ * entry re-resolves octane.config.ts through it at boot, and the whole
+ * `@octanejs/vite-plugin/production` graph is bundled into dist/server/entry.js.
+ * The file-loading half (`loadOctaneConfig`, which spins up Vite) lives in
+ * `load-config.js` and re-exports everything here.
+ */
+
+/** @import { OctaneConfigOptions, ResolvedOctaneConfig } from '@octanejs/vite-plugin' */
+
+import { DEFAULT_OUTDIR } from './constants.js';
+
+/**
+ * @param {unknown} route
+ * @returns {void}
+ */
+function validate_render_route(route) {
+	if (
+		!route ||
+		typeof route !== 'object' ||
+		/** @type {{ type?: unknown }} */ (route).type !== 'render'
+	) {
+		return;
+	}
+
+	const render_route = /** @type {{ entry?: unknown, layout?: unknown }} */ (route);
+	const has_entry =
+		typeof render_route.entry === 'string' ||
+		(Array.isArray(render_route.entry) &&
+			render_route.entry.length === 2 &&
+			typeof render_route.entry[0] === 'string' &&
+			typeof render_route.entry[1] === 'string');
+
+	if (!has_entry) {
+		throw new Error('[@octanejs/vite-plugin] RenderRoute requires a string/tuple `entry`.');
+	}
+
+	if (render_route.layout !== undefined && typeof render_route.layout !== 'string') {
+		throw new Error('[@octanejs/vite-plugin] RenderRoute `layout` must be a string path.');
+	}
+
+	const status = /** @type {{ status?: unknown }} */ (route).status;
+	if (status !== undefined && (typeof status !== 'number' || !Number.isInteger(status))) {
+		throw new Error('[@octanejs/vite-plugin] RenderRoute `status` must be an integer.');
+	}
+}
+
+/**
+ * @param {unknown} rootBoundary
+ * @returns {void}
+ */
+function validate_root_boundary(rootBoundary) {
+	if (rootBoundary === undefined) {
+		return;
+	}
+	if (!rootBoundary || typeof rootBoundary !== 'object') {
+		throw new Error('[@octanejs/vite-plugin] rootBoundary must be an object when provided.');
+	}
+
+	const boundary = /** @type {{ pending?: unknown, catch?: unknown }} */ (rootBoundary);
+	if (boundary.pending !== undefined && typeof boundary.pending !== 'function') {
+		throw new Error('[@octanejs/vite-plugin] rootBoundary.pending must be a component function.');
+	}
+	if (boundary.catch !== undefined && typeof boundary.catch !== 'function') {
+		throw new Error('[@octanejs/vite-plugin] rootBoundary.catch must be a component function.');
+	}
+}
+
+/**
+ * Validate a raw octane config and apply all defaults.
+ *
+ * After this function returns every optional field carries its default
+ * value so callers never need to use `??` / `||` fallbacks.
+ *
+ * The function is idempotent — passing an already-resolved config
+ * through it again is safe and produces the same result.
+ *
+ * @param {OctaneConfigOptions} raw - The user-provided config (from octane.config.ts)
+ * @param {{ requireAdapter?: boolean }} [options]
+ * @returns {ResolvedOctaneConfig}
+ */
+export function resolveOctaneConfig(raw, options = {}) {
+	const { requireAdapter = false } = options;
+
+	// ------------------------------------------------------------------
+	// Validate
+	// ------------------------------------------------------------------
+	if (!raw) {
+		throw new Error(
+			'[@octanejs/vite-plugin] octane.config.ts must export a default config object.',
+		);
+	}
+
+	if (requireAdapter && !raw.adapter) {
+		throw new Error(
+			'[@octanejs/vite-plugin] This build requires an `adapter` in octane.config.ts. ' +
+				'Install an adapter package (e.g. @octanejs/adapter-vercel) and set the `adapter` property.',
+		);
+	}
+
+	if (raw.adapter !== undefined) {
+		if (typeof raw.adapter !== 'object' || raw.adapter === null) {
+			throw new Error(
+				'[@octanejs/vite-plugin] adapter must be an adapter object (e.g. `adapter: vercel()`).',
+			);
+		}
+		if (raw.adapter.adapt !== undefined && typeof raw.adapter.adapt !== 'function') {
+			throw new Error('[@octanejs/vite-plugin] adapter.adapt must be a function.');
+		}
+		if (raw.adapter.serve !== undefined && typeof raw.adapter.serve !== 'function') {
+			throw new Error('[@octanejs/vite-plugin] adapter.serve must be a function.');
+		}
+	}
+
+	if (raw.router?.routes !== undefined && !Array.isArray(raw.router.routes)) {
+		throw new Error('[@octanejs/vite-plugin] router.routes must be an array.');
+	}
+
+	if (raw.router?.preHydrate !== undefined) {
+		// A Vite-root module path: the client hydrate entry dynamic-imports it in
+		// the browser, so it must be root-absolute ('/src/…'), not relative or fs.
+		if (typeof raw.router.preHydrate !== 'string' || !raw.router.preHydrate.startsWith('/')) {
+			throw new Error(
+				"[@octanejs/vite-plugin] router.preHydrate must be a Vite-root module path (e.g. '/src/pre-hydrate.ts').",
+			);
+		}
+	}
+
+	for (const route of raw.router?.routes ?? []) {
+		validate_render_route(route);
+	}
+
+	validate_root_boundary(raw.rootBoundary);
+
+	if (
+		raw.server?.render !== undefined &&
+		raw.server.render !== 'streaming' &&
+		raw.server.render !== 'buffered'
+	) {
+		throw new Error("[@octanejs/vite-plugin] server.render must be 'streaming' or 'buffered'.");
+	}
+
+	// ------------------------------------------------------------------
+	// Apply defaults
+	// ------------------------------------------------------------------
+	return {
+		build: {
+			outDir: raw.build?.outDir ?? DEFAULT_OUTDIR,
+			minify: raw.build?.minify,
+			target: raw.build?.target,
+		},
+		adapter: raw.adapter,
+		router: {
+			routes: raw.router?.routes ?? [],
+			preHydrate: raw.router?.preHydrate,
+		},
+		rootBoundary: raw.rootBoundary ?? {},
+		middlewares: raw.middlewares ?? [],
+		platform: {
+			env: raw.platform?.env ?? {},
+		},
+		server: {
+			trustProxy: raw.server?.trustProxy ?? false,
+			render: raw.server?.render ?? 'streaming',
+		},
+	};
+}

package/src/routes.js

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * @typedef {import('@octanejs/vite-plugin').Context} Context
  * @typedef {import('@octanejs/vite-plugin').Middleware} Middleware
@@ -68,7 +69,8 @@ export class RenderRoute {
 	/** @type {string} */
 	path;
 
-	/** @type {RenderRouteEntry | undefined} */
+	// Non-optional: the constructor throws without one (matches types/index.d.ts).
+	/** @type {RenderRouteEntry} */
 	entry;
 
 	/** @type {string | undefined} */
@@ -77,6 +79,9 @@ export class RenderRoute {
 	/** @type {Middleware[]} */
 	before;
 
+	/** @type {number | undefined} */
+	status;
+
 	/**
 	 * @param {RenderRouteOptions} options
 	 */
@@ -89,6 +94,7 @@ export class RenderRoute {
 		this.entry = options.entry;
 		this.layout = options.layout;
 		this.before = options.before ?? [];
+		this.status = options.status;
 	}
 }
 

package/src/server/component-wrappers.js

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * Server component composition for the octane renderer.
  *

package/src/server/middleware.js

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * @typedef {import('@octanejs/vite-plugin').Context} Context
  * @typedef {import('@octanejs/vite-plugin').Middleware} Middleware

package/src/server/node-http.js

@@ -0,0 +1,188 @@
+// @ts-check
+/**
+ * Node HTTP glue — shared by the dev middleware (src/index.js), the generated
+ * production server entry (its `nodeHandler` export for serverless wrappers),
+ * and the built-in production server (`createNodeServer`, the no-adapter
+ * default boot). Exported as '@octanejs/vite-plugin/node'.
+ *
+ * This module may import node builtins (unlike server/production.js, which is
+ * platform-agnostic) — it IS the Node platform layer.
+ */
+
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+
+/**
+ * Convert a Node.js IncomingMessage to a Web Request.
+ * @param {import('node:http').IncomingMessage} nodeRequest
+ * @returns {Request}
+ */
+export function nodeRequestToWebRequest(nodeRequest) {
+	const host = nodeRequest.headers.host || 'localhost';
+	const url = new URL(nodeRequest.url || '/', `http://${host}`);
+
+	const headers = new Headers();
+	for (const [key, value] of Object.entries(nodeRequest.headers)) {
+		if (value == null) continue;
+		if (Array.isArray(value)) {
+			for (const v of value) headers.append(key, v);
+		} else {
+			headers.set(key, value);
+		}
+	}
+
+	const method = (nodeRequest.method || 'GET').toUpperCase();
+	/** @type {RequestInit & { duplex?: 'half' }} */
+	const init = { method, headers };
+	if (method !== 'GET' && method !== 'HEAD') {
+		// node:stream/web's ReadableStream and the DOM lib's are structurally the
+		// same at runtime; the lib types disagree on BYOB details.
+		init.body = /** @type {ReadableStream} */ (
+			/** @type {unknown} */ (Readable.toWeb(nodeRequest))
+		);
+		init.duplex = 'half';
+	}
+	return new Request(url, init);
+}
+
+/**
+ * Pipe a Web Response to a Node.js ServerResponse. Streams chunk-by-chunk so a
+ * streaming SSR body flushes as it renders (no buffering).
+ *
+ * @param {import('node:http').ServerResponse} nodeResponse
+ * @param {Response} webResponse
+ */
+export async function sendWebResponse(nodeResponse, webResponse) {
+	nodeResponse.statusCode = webResponse.status;
+	if (webResponse.statusText) nodeResponse.statusMessage = webResponse.statusText;
+	webResponse.headers.forEach((value, key) => {
+		nodeResponse.setHeader(key, value);
+	});
+	if (webResponse.body) {
+		const reader = webResponse.body.getReader();
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				nodeResponse.write(value);
+			}
+		} finally {
+			reader.releaseLock();
+		}
+	}
+	nodeResponse.end();
+}
+
+// Static-file MIME map (the common web set; anything else falls back to
+// octet-stream, which is correct for downloads).
+/** @type {Record<string, string>} */
+const MIME_TYPES = {
+	'.html': 'text/html; charset=utf-8',
+	'.css': 'text/css; charset=utf-8',
+	'.js': 'text/javascript; charset=utf-8',
+	'.mjs': 'text/javascript; charset=utf-8',
+	'.json': 'application/json; charset=utf-8',
+	'.png': 'image/png',
+	'.jpg': 'image/jpeg',
+	'.jpeg': 'image/jpeg',
+	'.gif': 'image/gif',
+	'.svg': 'image/svg+xml',
+	'.ico': 'image/x-icon',
+	'.woff': 'font/woff',
+	'.woff2': 'font/woff2',
+	'.ttf': 'font/ttf',
+	'.otf': 'font/otf',
+	'.webp': 'image/webp',
+	'.avif': 'image/avif',
+	'.mp4': 'video/mp4',
+	'.webm': 'video/webm',
+	'.txt': 'text/plain; charset=utf-8',
+	'.xml': 'application/xml',
+	'.wasm': 'application/wasm',
+	'.map': 'application/json',
+};
+
+/**
+ * Serve a static file from `staticDir` if the request path maps to one.
+ * Hash-named build assets (everything under /assets/) get immutable caching;
+ * other files (favicon, robots.txt, …) revalidate.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {string} staticDir
+ * @returns {boolean} true when the request was handled as a static file
+ */
+export function serveStaticFile(req, res, staticDir) {
+	const method = (req.method || 'GET').toUpperCase();
+	if (method !== 'GET' && method !== 'HEAD') return false;
+
+	const pathname = decodeURIComponent(new URL(req.url || '/', 'http://localhost').pathname);
+	// Resolve inside staticDir only — a `..` escape must not leave the client dir.
+	const filePath = path.normalize(path.join(staticDir, pathname));
+	if (!filePath.startsWith(path.normalize(staticDir + path.sep))) return false;
+
+	/** @type {fs.Stats} */
+	let stat;
+	try {
+		stat = fs.statSync(filePath);
+	} catch {
+		return false;
+	}
+	if (!stat.isFile()) return false;
+
+	const ext = path.extname(filePath).toLowerCase();
+	res.statusCode = 200;
+	res.setHeader('Content-Type', MIME_TYPES[ext] || 'application/octet-stream');
+	res.setHeader('Content-Length', stat.size);
+	res.setHeader(
+		'Cache-Control',
+		pathname.startsWith('/assets/')
+			? 'public, max-age=31536000, immutable'
+			: 'public, max-age=0, must-revalidate',
+	);
+	if (method === 'HEAD') {
+		res.end();
+	} else {
+		fs.createReadStream(filePath).pipe(res);
+	}
+	return true;
+}
+
+/**
+ * Minimal production HTTP server: static files from `staticDir` first (built
+ * client assets), then the fetch-style SSR handler. This is the DEFAULT boot
+ * when octane.config.ts has no adapter — an adapter's `serve()` replaces it.
+ *
+ * @param {(request: Request) => Response | Promise<Response>} handler
+ * @param {{ staticDir?: string }} [options]
+ * @returns {{ listen: (port?: number) => import('node:http').Server, close: () => void }}
+ */
+export function createNodeServer(handler, options = {}) {
+	const staticDir = options.staticDir;
+
+	const server = http.createServer((req, res) => {
+		(async () => {
+			if (staticDir && serveStaticFile(req, res, staticDir)) return;
+			const response = await handler(nodeRequestToWebRequest(req));
+			await sendWebResponse(res, response);
+		})().catch((error) => {
+			console.error('[@octanejs/vite-plugin] Request error:', error);
+			if (!res.headersSent) {
+				res.statusCode = 500;
+				res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+			}
+			res.end('Internal Server Error');
+		});
+	});
+
+	return {
+		listen(port = 3000) {
+			return server.listen(port);
+		},
+		close() {
+			server.close();
+		},
+	};
+}