@octanejs/vite-plugin 0.1.5 → 0.1.9

package/src/load-config.js

@@ -1,95 +1,64 @@
 // @ts-check
-/**
- * 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 { resolveOctaneConfig } from './resolve-config.js';
 
-const OCTANE_EXTENSION_PATTERN = /\.tsrx$/;
+import {
+	getOctaneConfigPath,
+	loadOctaneConfig as loadCoreOctaneConfig,
+	loadOctaneConfigWithMetadata as loadCoreOctaneConfigWithMetadata,
+	octaneConfigExists,
+	resolveOctaneConfig,
+} from '@octanejs/app-core/config-loader';
+import { compile } from 'octane/compiler';
 
-// Validation + defaults live in resolve-config.js (a module with no vite /
-// compiler imports) so the production server bundle can include it without
-// dragging the toolchain along. Re-exported here for existing importers.
-export { resolveOctaneConfig } from './resolve-config.js';
+export { getOctaneConfigPath, octaneConfigExists, resolveOctaneConfig };
 
 /**
- * Return the absolute path to octane.config.ts for the given project root.
+ * Vite compatibility facade over app-core's bundler-neutral config loader.
+ * A live dev server is adapted to the neutral module-runner contract. Build
+ * and preview calls use a temporary Vite module runner so lazy config imports
+ * keep Vite's transform semantics without making app-core depend on Vite.
  *
- * This is the single source of truth for the config file name / location.
- *
- * @param {string} projectRoot - Absolute path to the project root
- * @returns {string}
+ * @param {string} projectRoot
+ * @param {{
+ *   vite?: import('vite').ViteDevServer,
+ *   moduleRunner?: import('@octanejs/app-core').ConfigModuleRunner | import('@octanejs/app-core').ConfigModuleRunner['loadModule'],
+ *   requireAdapter?: boolean,
+ *   configFile?: string,
+ *   cacheDir?: string,
+ * }} [options]
  */
-export function getOctaneConfigPath(projectRoot) {
-	return path.join(projectRoot, 'octane.config.ts');
+export async function loadOctaneConfig(projectRoot, options = {}) {
+	return withDefaultViteRunner(projectRoot, options, loadCoreOctaneConfig);
 }
 
 /**
- * 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}
+ * @param {string} projectRoot
+ * @param {{
+ *   vite?: import('vite').ViteDevServer,
+ *   moduleRunner?: import('@octanejs/app-core').ConfigModuleRunner | import('@octanejs/app-core').ConfigModuleRunner['loadModule'],
+ *   requireAdapter?: boolean,
+ *   configFile?: string,
+ *   cacheDir?: string,
+ * }} [options]
  */
-export function octaneConfigExists(projectRoot) {
-	return fs.existsSync(getOctaneConfigPath(projectRoot));
+export async function loadOctaneConfigWithMetadata(projectRoot, options = {}) {
+	return withDefaultViteRunner(projectRoot, options, loadCoreOctaneConfigWithMetadata);
 }
 
 /**
- * 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>}
+ * @template T
+ * @param {string} projectRoot
+ * @param {Record<string, any>} options
+ * @param {(root: string, options: any) => Promise<T>} loader
+ * @returns {Promise<T>}
  */
-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}`);
+async function withDefaultViteRunner(projectRoot, options, loader) {
+	if (options.vite || options.moduleRunner) {
+		return loader(projectRoot, withViteModuleRunner(options));
 	}
 
-	// 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,
@@ -99,12 +68,9 @@ export async function loadOctaneConfig(projectRoot, options = {}) {
 			{
 				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,
-					});
+					const file = id.split('?')[0];
+					if (!file.endsWith('.tsrx')) return null;
+					return compile(source, file, { mode: 'server', hmr: false });
 				},
 			},
 		],
@@ -112,9 +78,66 @@ export async function loadOctaneConfig(projectRoot, options = {}) {
 	});
 
 	try {
-		const configModule = await tempVite.ssrLoadModule(configPath);
-		return resolveOctaneConfig(configModule.default, { requireAdapter });
+		return await loader(projectRoot, {
+			...options,
+			moduleRunner: viteConfigModuleRunner(tempVite),
+		});
 	} finally {
 		await tempVite.close();
 	}
 }
+
+/** @param {Record<string, any>} options */
+function withViteModuleRunner(options) {
+	if (!options.vite || options.moduleRunner) return options;
+	const { vite, ...rest } = options;
+	return {
+		...rest,
+		moduleRunner: viteConfigModuleRunner(vite),
+	};
+}
+
+/**
+ * Adapt Vite's SSR runner and module graph to app-core's config-loader
+ * contract. Config evaluation itself is not enough: integrations also need
+ * the transitive file set so edits to imported renderer rules/boundary tables
+ * invalidate the compiler snapshot.
+ *
+ * @param {import('vite').ViteDevServer} vite
+ * @returns {import('@octanejs/app-core').ConfigModuleRunner}
+ */
+function viteConfigModuleRunner(vite) {
+	return {
+		loadModule: (/** @type {string} */ id) => vite.ssrLoadModule(id),
+		getDependencies(id) {
+			const graph = vite.environments.ssr.moduleGraph;
+			const roots = new Set();
+			const candidates = new Set([id]);
+			try {
+				// Vite canonicalizes graph IDs through realpath. Preserve the
+				// config loader's lexical path in its own metadata, but use both
+				// forms to find the root (notably /var -> /private/var on macOS).
+				candidates.add(fs.realpathSync(id));
+			} catch {
+				// The config loader reports the useful missing-file error.
+			}
+			for (const candidate of candidates) {
+				const byId = graph.getModuleById(candidate);
+				if (byId) roots.add(byId);
+				for (const module of graph.getModulesByFile(candidate) ?? []) roots.add(module);
+			}
+
+			const seen = new Set();
+			const dependencies = new Set();
+			/** @param {import('vite').EnvironmentModuleNode} module */
+			function visit(module) {
+				if (seen.has(module)) return;
+				seen.add(module);
+				if (module.file) dependencies.add(module.file);
+				for (const imported of module.importedModules) visit(imported);
+			}
+			for (const root of roots) visit(root);
+			return [...dependencies];
+		},
+	};
+}

package/src/project-codegen.js

@@ -1,218 +1,10 @@
-// @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() {
-	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.');
-}
-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.');
-}
-`;
-}
-
-/**
- * @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, 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`).
- *   - `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.
- *   - `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]
- * @returns {string}
- */
-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.
-  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, url, preHydrate }
-    if (!data.entry) {
-      console.error('[octane] Unable to hydrate: no route entry in #__octane_data.');
-      return;
-    }
-
-    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);
-      return;
-    }
-
-    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 importModule(data.layout);
-      const Layout = getComponentExport(layoutMod);
-      if (Layout) {
-        // 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, url });
-  } 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('/');
-}
+export {
+	RESOLVED_ADAPTER_BROWSER_STUB_ID,
+	SERVER_ONLY_ADAPTER_IDS,
+	create_adapter_browser_stub_source,
+	create_client_entry_source,
+	get_project_generated_dir,
+	normalize_module_reference,
+	to_vite_root_import,
+	write_project_generated_file,
+} from '@octanejs/app-core/codegen';

package/src/resolve-config.js

@@ -1,171 +1 @@
-// @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',
-		},
-	};
-}
+export { resolveOctaneConfig } from '@octanejs/app-core/config';