@octanejs/vite-plugin 0.1.1

package/src/load-config.js

@@ -0,0 +1,240 @@
+/**
+ * Shared utility for loading and resolving octane.config.ts.
+ *
+ * `resolveOctaneConfig` is the single source of truth for all config
+ * validation and default values. Every consumer should receive a
+ * `ResolvedOctaneConfig` rather than applying ad-hoc defaults.
+ *
+ * `loadOctaneConfig` is the single entry point for loading the config
+ * file.  It accepts an optional Vite dev server — when provided the
+ * config is loaded via `ssrLoadModule` (no temp server overhead,
+ * HMR-aware). Otherwise a temporary Vite server is spun up, used to
+ * transpile the TypeScript config, and immediately shut down.
+ *
+ * Used by the Vite plugin (during dev + build), the preview CLI script,
+ * and the generated production server entry.
+ */
+
+/** @import { OctaneConfigOptions, ResolvedOctaneConfig } from '@octanejs/vite-plugin' */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { compile } from 'octane/compiler';
+import { DEFAULT_OUTDIR } from './constants.js';
+
+const OCTANE_EXTENSION_PATTERN = /\.tsrx$/;
+
+/**
+ * @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.');
+	}
+}
+
+/**
+ * @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) {
+		if (!raw.adapter) {
+			throw new Error(
+				'[@octanejs/vite-plugin] Production builds require an `adapter` in octane.config.ts. ' +
+					'Install an adapter package (e.g. @ripple-ts/adapter-node) and set the `adapter` property.',
+			);
+		}
+
+		if (!raw.adapter.runtime) {
+			throw new Error(
+				'[@octanejs/vite-plugin] The adapter in octane.config.ts is missing the `runtime` property. ' +
+					'Make sure your adapter exports runtime primitives.',
+			);
+		}
+	}
+
+	if (raw.router?.routes !== undefined && !Array.isArray(raw.router.routes)) {
+		throw new Error('[@octanejs/vite-plugin] router.routes must be an array.');
+	}
+
+	for (const route of raw.router?.routes ?? []) {
+		validate_render_route(route);
+	}
+
+	validate_root_boundary(raw.rootBoundary);
+
+	// ------------------------------------------------------------------
+	// 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 ?? [],
+		},
+		rootBoundary: raw.rootBoundary ?? {},
+		middlewares: raw.middlewares ?? [],
+		platform: {
+			env: raw.platform?.env ?? {},
+		},
+		server: {
+			trustProxy: raw.server?.trustProxy ?? false,
+		},
+	};
+}
+
+/**
+ * Return the absolute path to octane.config.ts for the given project root.
+ *
+ * This is the single source of truth for the config file name / location.
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ * @returns {string}
+ */
+export function getOctaneConfigPath(projectRoot) {
+	return path.join(projectRoot, 'octane.config.ts');
+}
+
+/**
+ * Check whether a octane.config.ts file exists in the given root.
+ *
+ * Use this before calling `loadOctaneConfig` when the absence of a
+ * config is a valid state (e.g. the Vite plugin running in SPA mode).
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ * @returns {boolean}
+ */
+export function octaneConfigExists(projectRoot) {
+	return fs.existsSync(getOctaneConfigPath(projectRoot));
+}
+
+/**
+ * Load octane.config.ts, validate, and apply defaults via `resolveOctaneConfig`.
+ *
+ * When a Vite dev server is provided via `options.vite`, the config is loaded
+ * through its `ssrLoadModule` — avoiding the cost of spinning up a temporary
+ * server and enabling HMR-aware reloads.
+ *
+ * When no dev server is available (build / preview), a temporary Vite server
+ * is created in middleware mode, used to transpile the config, then shut down.
+ *
+ * Throws if the config file does not exist or is invalid.
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ * @param {{ vite?: import('vite').ViteDevServer, requireAdapter?: boolean }} [options]
+ * @returns {Promise<ResolvedOctaneConfig>}
+ */
+export async function loadOctaneConfig(projectRoot, options = {}) {
+	const { vite, requireAdapter } = options;
+	const configPath = getOctaneConfigPath(projectRoot);
+
+	if (!fs.existsSync(configPath)) {
+		throw new Error(`[@octanejs/vite-plugin] octane.config.ts not found in ${projectRoot}`);
+	}
+
+	// When a running Vite dev server is available, use it directly.
+	if (vite) {
+		const configModule = await vite.ssrLoadModule(configPath);
+		return resolveOctaneConfig(configModule.default, { requireAdapter });
+	}
+
+	// Otherwise spin up a temporary Vite server (build / preview).
+	// The temp server only transpiles octane.config.ts (plain TypeScript) —
+	// no .tsrx compilation plugin is needed beyond config-referenced helpers.
+	const { createServer } = await import('vite');
+
+	const tempVite = await createServer({
+		root: projectRoot,
+		configFile: false,
+		appType: 'custom',
+		server: { middlewareMode: true },
+		plugins: [
+			{
+				name: 'octane-config-tsrx-loader',
+				transform(source, id) {
+					if (!OCTANE_EXTENSION_PATTERN.test(id)) return null;
+					const filename = id.replace(projectRoot, '');
+					return compile(source, filename, {
+						mode: 'server',
+						hmr: false,
+					});
+				},
+			},
+		],
+		logLevel: 'silent',
+	});
+
+	try {
+		const configModule = await tempVite.ssrLoadModule(configPath);
+		return resolveOctaneConfig(configModule.default, { requireAdapter });
+	} finally {
+		await tempVite.close();
+	}
+}

package/src/project-codegen.js

@@ -0,0 +1,158 @@
+/** @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';
+export const SERVER_ONLY_ADAPTER_IDS = new Set([
+	'@ripple-ts/adapter-node',
+	'@ripple-ts/adapter-bun',
+	'@ripple-ts/adapter-vercel',
+]);
+
+/** @type {Map<string, string>} */
+const generated_file_cache = new Map();
+
+/**
+ * @returns {string}
+ */
+export function create_adapter_browser_stub_source() {
+	return `export const runtime = undefined;
+export function serve() {
+  throw new Error('[octane] Server adapters cannot run in the browser.');
+}
+export function nodeRequestToWebRequest() {
+  throw new Error('[octane] Node request helpers cannot run in the browser.');
+}
+export function webResponseToNodeResponse() {
+  throw new Error('[octane] Node response helpers cannot run in the browser.');
+}
+`;
+}
+
+/**
+ * @param {ResolvedConfig} viteConfig
+ * @returns {string}
+ */
+export function get_project_generated_dir(viteConfig) {
+	return path.join(viteConfig.cacheDir, 'project');
+}
+
+/**
+ * @param {ResolvedConfig} viteConfig
+ * @param {string} name
+ * @param {string} source
+ * @returns {string}
+ */
+export function write_project_generated_file(viteConfig, name, source) {
+	const dir = get_project_generated_dir(viteConfig);
+	const file = path.join(dir, name);
+
+	if (generated_file_cache.get(file) === source && fs.existsSync(file)) {
+		return file;
+	}
+
+	fs.mkdirSync(dir, { recursive: true });
+	if (!fs.existsSync(file) || fs.readFileSync(file, 'utf-8') !== source) {
+		fs.writeFileSync(file, source);
+	}
+	generated_file_cache.set(file, source);
+	return file;
+}
+
+/**
+ * Generate the client hydration entry (served at virtual:octane-hydrate).
+ *
+ * CONFIG-FREE: it does NOT import octane.config.ts. Importing the config into
+ * 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.)
+ *
+ * octane specifics:
+ *   - `import { hydrateRoot } from 'octane'` (NO `mount`).
+ *   - `hydrateRoot(container, body, props)` signature (container FIRST, React-18
+ *     shape) — no `{ target, props }` wrapper.
+ *   - The layout `children` is a ComponentBody `(s) => Page(s, { params })`,
+ *     NOT a 0-arg thunk: octane's `childSlot` invokes a bare function child
+ *     as a ComponentBody (block first arg, `{}` props), so page data rides the
+ *     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.
+ *
+ * `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]
+ * @returns {string}
+ */
+export function create_client_entry_source(_options) {
+	return `// Auto-generated by @octanejs/vite-plugin.
+// This file is written to Vite's cacheDir/project folder.
+
+import { hydrateRoot } from 'octane';
+
+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.
+  if (exportName) return typeof module[exportName] === 'function' ? module[exportName] : undefined;
+  if (typeof module.default === 'function') return module.default;
+  return Object.entries(module).find(([key, value]) => typeof value === 'function' && /^[A-Z]/.test(key))?.[1];
+}
+
+(async () => {
+  try {
+    const el = document.getElementById('__octane_data');
+    const target = document.getElementById('root');
+    if (!el || !target) {
+      console.error('[octane] Unable to hydrate: missing #__octane_data or #root.');
+      return;
+    }
+    const data = JSON.parse(el.textContent || '{}'); // { entry, exportName, layout, params }
+    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 Component = getComponentExport(pageMod, data.exportName ?? undefined);
+    if (!Component) {
+      console.error('[octane] Unable to hydrate: no component export for', data.entry);
+      return;
+    }
+
+    const params = data.params;
+
+    if (data.layout) {
+      const layoutMod = await import(/* @vite-ignore */ 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 });
+        return;
+      }
+    }
+
+    hydrateRoot(target, Component, { params });
+  } catch (error) {
+    console.error('[octane] Failed to bootstrap client hydration.', error);
+  }
+})();
+`;
+}
+
+/**
+ * @param {string} filename
+ * @param {string} root
+ * @returns {string}
+ */
+export function to_vite_root_import(filename, root) {
+	return '/' + path.relative(root, filename).split(path.sep).join('/');
+}

package/src/routes.js

@@ -0,0 +1,127 @@
+/**
+ * @typedef {import('@octanejs/vite-plugin').Context} Context
+ * @typedef {import('@octanejs/vite-plugin').Middleware} Middleware
+ * @typedef {import('@octanejs/vite-plugin').RenderRouteOptions} RenderRouteOptions
+ * @typedef {import('@octanejs/vite-plugin').ServerRouteOptions} ServerRouteOptions
+ */
+
+/**
+ * @typedef {string | readonly [string, string]} RenderRouteEntry
+ */
+
+/**
+ * @param {RenderRouteEntry | undefined} entry
+ * @returns {string | undefined}
+ */
+export function get_route_entry_path(entry) {
+	return typeof entry === 'string' ? entry : entry?.[1];
+}
+
+/**
+ * @param {RenderRouteEntry | undefined} entry
+ * @returns {string | undefined}
+ */
+export function get_route_entry_export_name(entry) {
+	return typeof entry === 'string' ? undefined : entry?.[0];
+}
+
+/**
+ * @param {RenderRouteEntry | undefined} entry
+ * @returns {string | undefined}
+ */
+export function get_route_entry_id(entry) {
+	const path = get_route_entry_path(entry);
+	const export_name = get_route_entry_export_name(entry);
+	return path && export_name ? `${path}#${export_name}` : path;
+}
+
+/**
+ * @param {Record<string, unknown>} module
+ * @param {string | undefined} export_name
+ * @returns {Function | null}
+ */
+export function get_component_export(module, export_name) {
+	// When an explicit export name is given, require an exact match. Do NOT fall
+	// back to default/first-PascalCase — a typo'd route tuple should fail loudly
+	// rather than silently render the wrong component.
+	if (export_name) {
+		return typeof module[export_name] === 'function' ? module[export_name] : null;
+	}
+	if (typeof module.default === 'function') {
+		return module.default;
+	}
+	for (const [key, value] of Object.entries(module)) {
+		if (typeof value === 'function' && /^[A-Z]/.test(key)) {
+			return value;
+		}
+	}
+	return null;
+}
+
+/**
+ * Route for rendering octane components with SSR
+ */
+export class RenderRoute {
+	/** @type {'render'} */
+	type = 'render';
+
+	/** @type {string} */
+	path;
+
+	/** @type {RenderRouteEntry | undefined} */
+	entry;
+
+	/** @type {string | undefined} */
+	layout;
+
+	/** @type {Middleware[]} */
+	before;
+
+	/**
+	 * @param {RenderRouteOptions} options
+	 */
+	constructor(options) {
+		if (!options.entry) {
+			throw new Error('RenderRoute requires an `entry`.');
+		}
+
+		this.path = options.path;
+		this.entry = options.entry;
+		this.layout = options.layout;
+		this.before = options.before ?? [];
+	}
+}
+
+/**
+ * Route for API endpoints (returns Response directly)
+ */
+export class ServerRoute {
+	/** @type {'server'} */
+	type = 'server';
+
+	/** @type {string} */
+	path;
+
+	/** @type {string[]} */
+	methods;
+
+	/** @type {(context: Context) => Response | Promise<Response>} */
+	handler;
+
+	/** @type {Middleware[]} */
+	before;
+
+	/** @type {Middleware[]} */
+	after;
+
+	/**
+	 * @param {ServerRouteOptions} options
+	 */
+	constructor(options) {
+		this.path = options.path;
+		this.methods = options.methods ?? ['GET'];
+		this.handler = options.handler;
+		this.before = options.before ?? [];
+		this.after = options.after ?? [];
+	}
+}

package/src/server/component-wrappers.js

@@ -0,0 +1,55 @@
+/**
+ * Server component composition for the octane renderer.
+ *
+ * octane's server ABI is PROPS-FIRST (matching the client): a component body is
+ * `(props, scope, extra) => string`. `render(Component, props)` invokes the ROOT
+ * directly as `Component(props, rootScope, undefined)` and does NOT wrap it in
+ * block markers — and `hydrateRoot()` adopts the container's FIRST CHILD as the
+ * root's own node. So the wrapper must call the top-level component DIRECTLY
+ * (wrapping it in `ssrComponent` would add an extra `<!--[-->…<!--]-->` layer that
+ * `clone()` then mis-adopts on hydrate).
+ *
+ * Only the layout's `{children}` is a nested hole: the compiled layout emits
+ * `ssrChild(props.children, scope)`, and `ssrChild` invokes a FUNCTION child as
+ * `children({}, scope, undefined)` wrapped in one `<!--[-->…<!--]-->` range. So
+ * `children` is a ComponentBody that calls the page directly, and any page data
+ * (params) rides its CLOSURE — `ssrChild` supplies only `{}`. The client
+ * `childSlot` applies the identical rule (bare function = ComponentBody, `{}`
+ * props, one marker range), so server markers and client adoption line up.
+ *
+ * @typedef {(props?: any, scope?: any, extra?: any) => string} ServerComponent
+ */
+
+/**
+ * Wrap a page component, baking in its route props.
+ *
+ * @param {ServerComponent} Page
+ * @param {Record<string, unknown>} pageProps
+ * @returns {ServerComponent}
+ */
+export function createPropsWrapper(Page, pageProps) {
+	return function Root(_props, scope) {
+		return Page(pageProps, scope, undefined);
+	};
+}
+
+/**
+ * Compose a layout with a page: the layout's `{children}` renders the page.
+ *
+ * @param {ServerComponent} Layout
+ * @param {ServerComponent} Page
+ * @param {Record<string, unknown>} pageProps
+ * @returns {ServerComponent}
+ */
+export function createLayoutWrapper(Layout, Page, pageProps) {
+	return function Root(_props, scope) {
+		// `children` is a ComponentBody closing over pageProps; the layout's
+		// `{children}` hole runs it via ssrChild (which supplies `{}` props and
+		// wraps the output in one block range), so the page still gets its real
+		// route props through the closure. PROPS-FIRST: childSlot/ssrChild call it
+		// as `({}, scope, extra)`, so the page's real props are passed explicitly.
+		const children = (/** @type {any} */ _cprops, /** @type {any} */ cscope) =>
+			Page(pageProps, cscope, undefined);
+		return Layout({ ...pageProps, children }, scope, undefined);
+	};
+}

package/src/server/middleware.js

@@ -0,0 +1,126 @@
+/**
+ * @typedef {import('@octanejs/vite-plugin').Context} Context
+ * @typedef {import('@octanejs/vite-plugin').Middleware} Middleware
+ * @typedef {import('@octanejs/vite-plugin').NextFunction} NextFunction
+ */
+
+/**
+ * Compose multiple middlewares into a single middleware
+ * Follows Koa-style execution: request flows down, response flows back up
+ *
+ * @param {Middleware[]} middlewares
+ * @returns {(context: Context, finalHandler: () => Promise<Response>) => Promise<Response>}
+ */
+export function compose(middlewares) {
+	return function composed(context, finalHandler) {
+		let index = -1;
+
+		/**
+		 * @param {number} i
+		 * @returns {Promise<Response>}
+		 */
+		function dispatch(i) {
+			if (i <= index) {
+				return Promise.reject(new Error('next() called multiple times'));
+			}
+			index = i;
+
+			/** @type {Middleware | (() => Promise<Response>) | undefined} */
+			let fn;
+
+			if (i < middlewares.length) {
+				fn = middlewares[i];
+			} else if (i === middlewares.length) {
+				fn = finalHandler;
+			}
+
+			if (!fn) {
+				return Promise.reject(new Error('No handler provided'));
+			}
+
+			try {
+				// For the final handler, we don't pass next
+				if (i === middlewares.length) {
+					return Promise.resolve(/** @type {() => Promise<Response>} */ (fn)());
+				}
+				// For middlewares, pass context and next
+				return Promise.resolve(/** @type {Middleware} */ (fn)(context, () => dispatch(i + 1)));
+			} catch (err) {
+				return Promise.reject(err);
+			}
+		}
+
+		return dispatch(0);
+	};
+}
+
+/**
+ * Create a context object for the request
+ * @param {Request} request
+ * @param {Record<string, string>} params
+ * @returns {Context}
+ */
+export function createContext(request, params) {
+	return {
+		request,
+		params,
+		url: new URL(request.url),
+		state: new Map(),
+	};
+}
+
+/**
+ * Run middlewares with a final handler
+ * Combines global middlewares, route-level before/after, and the handler
+ *
+ * @param {Context} context
+ * @param {Middleware[]} globalMiddlewares
+ * @param {Middleware[]} beforeMiddlewares
+ * @param {() => Promise<Response>} handler
+ * @param {Middleware[]} afterMiddlewares
+ * @returns {Promise<Response>}
+ */
+export async function runMiddlewareChain(
+	context,
+	globalMiddlewares,
+	beforeMiddlewares,
+	handler,
+	afterMiddlewares = [],
+) {
+	// Combine global + before middlewares
+	const allMiddlewares = [...globalMiddlewares, ...beforeMiddlewares];
+
+	// If there are after middlewares, wrap the handler to run them
+	const wrappedHandler =
+		afterMiddlewares.length > 0
+			? async () => {
+					const response = await handler();
+					// After middlewares can inspect/modify the response
+					// but have limited ability to change it in our model
+					// We run them for side-effects (logging, etc.)
+					return runAfterMiddlewares(context, afterMiddlewares, response);
+				}
+			: handler;
+
+	const composed = compose(allMiddlewares);
+	return composed(context, wrappedHandler);
+}
+
+/**
+ * Run after middlewares with the response
+ * After middlewares run in order and can intercept/modify the response
+ *
+ * @param {Context} context
+ * @param {Middleware[]} middlewares
+ * @param {Response} response
+ * @returns {Promise<Response>}
+ */
+async function runAfterMiddlewares(context, middlewares, response) {
+	let currentResponse = response;
+
+	for (const middleware of middlewares) {
+		currentResponse = await middleware(context, async () => currentResponse);
+	}
+
+	return currentResponse;
+}