@octanejs/vite-plugin 0.1.5 → 0.1.6

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@octanejs/vite-plugin",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "license": "MIT",
   "type": "module",
-  "description": "Vite metaframework plugin for the octane renderer (dev SSR + routing + hydrate)",
+  "engines": {
+    "node": ">=22"
+  },
+  "description": "Vite integration for Octane (SPA compilation plus optional routing, SSR, and hydration)",
   "author": {
     "name": "Dominic Gannaway",
     "email": "dg@domgan.com"
@@ -16,6 +19,10 @@
     "url": "git+https://github.com/octanejs/octane.git",
     "directory": "packages/vite-plugin-octane"
   },
+  "files": [
+    "src",
+    "types"
+  ],
   "module": "src/index.js",
   "main": "src/index.js",
   "bin": {
@@ -40,11 +47,16 @@
   },
   "dependencies": {
     "@ripple-ts/adapter": "^0.3.86",
-    "octane": "0.1.5"
+    "@octanejs/app-core": "0.0.2"
+  },
+  "peerDependencies": {
+    "vite": "^8.0.16",
+    "octane": "0.1.6"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
     "type-fest": "^5.6.0",
-    "vite": "^8.0.16"
+    "vite": "^8.0.16",
+    "octane": "0.1.6"
   }
 }

package/src/config-entry.js

@@ -13,6 +13,21 @@
 
 export { RenderRoute, ServerRoute } from './routes.js';
 export { resolveOctaneConfig } from './resolve-config.js';
+export { OCTANE_NONCE_STATE_KEY } from './constants.js';
+export {
+	DEFAULT_OUTDIR,
+	ENTRY_FILENAME,
+	compose,
+	createContext,
+	createRouter,
+	get_component_export,
+	get_route_entry_export_name,
+	get_route_entry_id,
+	get_route_entry_path,
+	handleServerRoute,
+	is_rpc_request,
+	runMiddlewareChain,
+} from '@octanejs/app-core';
 
 // Mirrors src/index.js — enforce types / DX only.
 export function defineConfig(/** @type {any} */ options) {

package/src/constants.js

@@ -1,3 +1 @@
-// @ts-check
-export const DEFAULT_OUTDIR = 'dist';
-export const ENTRY_FILENAME = 'entry.js';
+export { DEFAULT_OUTDIR, ENTRY_FILENAME, OCTANE_NONCE_STATE_KEY } from '@octanejs/app-core';

package/src/index.js

@@ -6,6 +6,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { createRequire } from 'node:module';
 
 import { octane as octaneCompiler } from 'octane/compiler/vite';
 
@@ -13,12 +14,14 @@ import { createRouter } from './server/router.js';
 import { createContext, runMiddlewareChain } from './server/middleware.js';
 import { handleRenderRoute } from './server/render-route.js';
 import { handleServerRoute } from './server/server-route.js';
+import { HYDRATION_NONCE_PLACEHOLDER, injectHydrationEntry } from './server/html-template.js';
 import { generateServerEntry } from './server/virtual-entry.js';
 import { nodeRequestToWebRequest, sendWebResponse } from './server/node-http.js';
 import { ENTRY_FILENAME } from './constants.js';
 import {
 	getOctaneConfigPath,
 	loadOctaneConfig,
+	loadOctaneConfigWithMetadata,
 	resolveOctaneConfig,
 	octaneConfigExists,
 } from './load-config.js';
@@ -37,16 +40,35 @@ import { get_route_entry_path } from './routes.js';
 
 // Re-export route classes + config helpers (public API surface).
 export { RenderRoute, ServerRoute } from './routes.js';
+export { OCTANE_NONCE_STATE_KEY } from './constants.js';
+export {
+	DEFAULT_OUTDIR,
+	ENTRY_FILENAME,
+	compose,
+	createContext,
+	createRouter,
+	get_component_export,
+	get_route_entry_export_name,
+	get_route_entry_id,
+	get_route_entry_path,
+	handleServerRoute,
+	is_rpc_request,
+	runMiddlewareChain,
+} from '@octanejs/app-core';
 export {
 	getOctaneConfigPath,
 	loadOctaneConfig,
+	loadOctaneConfigWithMetadata,
 	resolveOctaneConfig,
 	octaneConfigExists,
 } from './load-config.js';
 
 const VIRTUAL_HYDRATE_ID = 'virtual:octane-hydrate';
 const RESOLVED_VIRTUAL_HYDRATE_ID = '\0virtual:octane-hydrate';
-const OCTANE_EXTENSIONS = ['.tsrx'];
+const requireFromPlugin = createRequire(import.meta.url);
+// Mirrors octane/compiler/vite's full-compiler surface. Keeping this list in
+// sync is especially important for production `module server` discovery.
+const OCTANE_EXTENSIONS = ['.tsrx', '.tsx'];
 
 /**
  * @param {string} file_name
@@ -147,7 +169,9 @@ function has_route_config(config) {
 }
 
 /**
- * The octane metaframework Vite plugin.
+ * The recommended Octane Vite integration. With no octane.config.ts it behaves
+ * as a compiler plugin inside a normal Vite SPA; configured routes activate the
+ * metaframework layer.
  *
  * Returns an ARRAY: `[octaneCompiler({ hmr }), metaPlugin]`. The first element is
  * octane/compiler's transform plugin — it owns ALL `.tsrx` compilation, picking
@@ -184,6 +208,8 @@ export function octane(inlineOptions = {}) {
 	let buildOctaneConfig = null;
 	/** @type {string[]} Module paths the generated client entry maps statically (build only) */
 	let staticEntries = [];
+	/** @type {Set<string>} Vite-root paths of modules containing `module server` */
+	const serverModuleModules = new Set();
 
 	/** @type {Plugin} */
 	const metaPlugin = {
@@ -196,33 +222,31 @@ export function octane(inlineOptions = {}) {
 		async config(userConfig, env) {
 			isBuild = env?.command === 'build';
 			isSSRBuild = !!userConfig.build?.ssr;
+			const projectRoot = userConfig.root ? path.resolve(userConfig.root) : process.cwd();
+			const hasOctaneConfig = octaneConfigExists(projectRoot);
 
 			const exclude = userConfig.optimizeDeps?.exclude || [];
 			const base = {
-				// SSR owns routing, so default appType to 'custom' (no SPA HTML
-				// fallback masking SSR routes). Respect an explicit user appType, and
-				// leave `vite preview` alone — the production SSR build is previewed
+				// A zero-config project is a normal Vite SPA: leave appType unset so
+				// Vite retains its HTML transform and history fallback. An Octane app
+				// config opts into framework routing, where SSR owns navigation and the
+				// SPA fallback must not mask unmatched routes. Respect an explicit user
+				// appType, and leave `vite preview` alone — production SSR is previewed
 				// with `octane-preview` (it serves dist/server), not `vite preview`.
-				...(userConfig.appType === undefined && !env?.isPreview
+				...(hasOctaneConfig && userConfig.appType === undefined && !env?.isPreview
 					? { appType: /** @type {const} */ ('custom') }
 					: {}),
 				optimizeDeps: {
 					exclude: [
-						// `@octanejs/tanstack-query` ships a `.tsrx` provider component, so it must NOT
-						// be esbuild-prebundled — the octane transform owns `.tsrx` compilation.
-						...new Set([
-							...exclude,
-							'octane',
-							'octane/compiler',
-							'@octanejs/tanstack-query',
-							...SERVER_ONLY_ADAPTER_IDS,
-						]),
+						// The compiler plugin has already added every manifest-discovered
+						// raw Octane dependency to `exclude`; preserve that list here.
+						...new Set([...exclude, 'octane', 'octane/compiler', ...SERVER_ONLY_ADAPTER_IDS]),
 					],
 				},
-				// Workspace packages with TS source must be transformed by Vite's SSR
-				// pipeline (not require()'d raw) so ssrLoadModule gets transpiled code.
+				// Raw binding packages are supplied recursively by the compiler plugin;
+				// these core entrypoints remain explicit metaframework dependencies.
 				ssr: {
-					noExternal: ['octane', 'octane/compiler', '@octanejs/tanstack-query'],
+					noExternal: ['octane', 'octane/compiler'],
 				},
 			};
 
@@ -230,8 +254,7 @@ export function octane(inlineOptions = {}) {
 			// build.ssr, so it skips this): route the client bundle to
 			// `{outDir}/client` and emit a manifest for the server's asset map.
 			if (isBuild && !isSSRBuild) {
-				const projectRoot = userConfig.root ? path.resolve(userConfig.root) : process.cwd();
-				if (octaneConfigExists(projectRoot)) {
+				if (hasOctaneConfig) {
 					buildOctaneConfig = await loadOctaneConfig(projectRoot);
 					if (has_route_config(buildOctaneConfig)) {
 						if (!fs.existsSync(path.join(projectRoot, 'index.html'))) {
@@ -267,11 +290,16 @@ export function octane(inlineOptions = {}) {
 		 */
 		buildStart() {
 			if (!isBuild || isSSRBuild || !has_route_config(buildOctaneConfig)) return;
+			serverModuleModules.clear();
 			const cfg = /** @type {ResolvedOctaneConfig} */ (buildOctaneConfig);
 			const entries = cfg.router.routes
 				.filter((r) => r.type === 'render')
 				.flatMap((r) => [get_route_entry_path(/** @type {RenderRoute} */ (r).entry), r.layout]);
 			if (cfg.router.preHydrate) entries.push(cfg.router.preHydrate);
+			entries.push(
+				get_route_entry_path(cfg.rootBoundary.pending),
+				get_route_entry_path(cfg.rootBoundary.catch),
+			);
 			staticEntries = [...new Set(entries.filter((e) => typeof e === 'string'))];
 		},
 
@@ -313,6 +341,22 @@ export function octane(inlineOptions = {}) {
 			return null;
 		},
 
+		/**
+		 * Observe the compiler's client output after the pre-transform. A generated
+		 * __serverRpc call is an exact, syntax-level signal that this source owns a
+		 * `module server`; production uses the collected paths as static SSR imports.
+		 */
+		transform(code, id, options) {
+			if (!isBuild || options?.ssr || !is_octane_module_path(id.split('?')[0])) return null;
+			if (!code.includes('_$__serverRpc(')) return null;
+			const file = id.split('?')[0];
+			const relative = path.relative(root, file);
+			const isWithinRoot =
+				relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative);
+			serverModuleModules.add(isWithinRoot ? '/' + relative.split(path.sep).join('/') : file);
+			return null;
+		},
+
 		/**
 		 * Dev SSR middleware. Registered as a pre-hook (no return) so it runs
 		 * BEFORE Vite's HTML fallback. Config is loaded lazily on first request
@@ -521,8 +565,7 @@ export function octane(inlineOptions = {}) {
 			order: 'pre',
 			handler(html) {
 				if (!isBuild || isSSRBuild || !has_route_config(buildOctaneConfig)) return html;
-				const hydrationScript = `<script type="module" src="${VIRTUAL_HYDRATE_ID}"></script>`;
-				return html.replace('</body>', `${hydrationScript}\n</body>`);
+				return injectHydrationEntry(html, VIRTUAL_HYDRATE_ID, HYDRATION_NONCE_PLACEHOLDER);
 			},
 		},
 
@@ -605,7 +648,14 @@ export function octane(inlineOptions = {}) {
 				generateServerEntry({
 					routes: cfg.router.routes,
 					octaneConfigPath: getOctaneConfigPath(root),
+					rootBoundary: cfg.rootBoundary,
+					rpcModulePaths: [...serverModuleModules],
 					clientAssetMap,
+					// The virtual entry has no filesystem importer, so resolve app-core
+					// from this package before handing source to Vite. This also works
+					// when app-core is nested under the plugin by a package manager.
+					productionModuleId: requireFromPlugin.resolve('@octanejs/app-core/production'),
+					nodeModuleId: requireFromPlugin.resolve('@octanejs/app-core/node'),
 				}),
 			);
 
@@ -700,8 +750,8 @@ export function octane(inlineOptions = {}) {
 	// compiler's `.ts`/`.js` hook-slotting pass must skip. Hand-slot-forwarding
 	// bindings should not need it: they declare
 	// `"octane": { "hookSlots": { "manual": ["src"] } }` in their own package.json and the
-	// compiler plugin skips them via a nearest-manifest lookup (published
-	// bindings live in node_modules and are skipped outright).
+	// compiler plugin skips those directories via a nearest-manifest lookup.
+	// Other installed raw-source Octane packages are transformed automatically.
 	const compilerOptions = {};
 	if (inlineOptions.hmr !== undefined) compilerOptions.hmr = inlineOptions.hmr;
 	if (inlineOptions.exclude !== undefined) compilerOptions.exclude = inlineOptions.exclude;

package/src/load-config.js

@@ -1,95 +1,62 @@
 // @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 {
+	getOctaneConfigPath,
+	loadOctaneConfig as loadCoreOctaneConfig,
+	loadOctaneConfigWithMetadata as loadCoreOctaneConfigWithMetadata,
+	octaneConfigExists,
+	resolveOctaneConfig,
+} from '@octanejs/app-core/config-loader';
 import { compile } from 'octane/compiler';
-import { resolveOctaneConfig } from './resolve-config.js';
 
-const OCTANE_EXTENSION_PATTERN = /\.tsrx$/;
-
-// 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.
- *
- * This is the single source of truth for the config file name / location.
+ * 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.
  *
- * @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 +66,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 +76,25 @@ export async function loadOctaneConfig(projectRoot, options = {}) {
 	});
 
 	try {
-		const configModule = await tempVite.ssrLoadModule(configPath);
-		return resolveOctaneConfig(configModule.default, { requireAdapter });
+		return await loader(projectRoot, {
+			...options,
+			moduleRunner: {
+				loadModule: (/** @type {string} */ id) => tempVite.ssrLoadModule(id),
+			},
+		});
 	} 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: {
+			loadModule: (/** @type {string} */ id) => vite.ssrLoadModule(id),
+		},
+	};
+}