@ripple-ts/vite-plugin 0.3.10 → 0.3.11

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @ripple-ts/vite-plugin
 
+## 0.3.11
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @ripple-ts/adapter@0.3.11
+
 ## 0.3.10
 
 ### Patch Changes

package/package.json

@@ -3,7 +3,7 @@
   "description": "Vite plugin for Ripple",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "type": "module",
   "module": "src/index.js",
   "main": "src/index.js",
@@ -32,13 +32,13 @@
     "url": "https://github.com/Ripple-TS/ripple/issues"
   },
   "dependencies": {
-    "@ripple-ts/adapter": "0.3.10"
+    "@ripple-ts/adapter": "0.3.11"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
     "type-fest": "^5.4.4",
     "vite": "^8.0.0",
-    "ripple": "0.3.10"
+    "ripple": "0.3.11"
   },
   "publishConfig": {
     "access": "public"

package/src/index.js

@@ -27,9 +27,19 @@ import { patch_global_fetch, is_rpc_request, handle_rpc_request } from '@ripple-
 
 // Re-export route classes
 export { RenderRoute, ServerRoute } from './routes.js';
+export {
+	getRippleConfigPath,
+	loadRippleConfig,
+	resolveRippleConfig,
+	rippleConfigExists,
+} from './load-config.js';
 
 const VITE_FS_PREFIX = '/@fs/';
 const IS_WINDOWS = process.platform === 'win32';
+const VIRTUAL_HYDRATE_ID = 'virtual:ripple-hydrate';
+const RESOLVED_VIRTUAL_HYDRATE_ID = '\0virtual:ripple-hydrate';
+const VIRTUAL_COMPAT_ID = 'virtual:ripple-compat';
+const RESOLVED_VIRTUAL_COMPAT_ID = '\0virtual:ripple-compat';
 
 // Dev server always runs in Node — use node:async_hooks as default runtime
 // If the user provides adapter.runtime in their config, that will be used instead.
@@ -67,6 +77,60 @@ function getDevAsyncContext(config) {
 	return devAsyncContext;
 }
 
+/**
+ * @param {ResolvedRippleConfig | null} config
+ * @returns {string}
+ */
+function create_compat_virtual_module(config) {
+	const compat_entries = Object.entries(config?.compat ?? {});
+
+	if (compat_entries.length === 0) {
+		return `const compat = undefined;
+globalThis.__RIPPLE_COMPAT__ = compat;
+export { compat };
+export default compat;
+`;
+	}
+
+	const imports = [];
+	const properties = [];
+
+	for (let i = 0; i < compat_entries.length; i++) {
+		const [kind, entry] = compat_entries[i];
+		const local_name = `__ripple_compat_factory_${i}`;
+
+		if (entry.factory) {
+			imports.push(
+				`import { ${entry.factory} as ${local_name} } from ${JSON.stringify(entry.from)};`,
+			);
+		} else {
+			imports.push(`import ${local_name} from ${JSON.stringify(entry.from)};`);
+		}
+
+		properties.push(`  ${JSON.stringify(kind)}: ${local_name}(),`);
+	}
+
+	return `${imports.join('\n')}
+
+const compat = {
+${properties.join('\n')}
+};
+
+globalThis.__RIPPLE_COMPAT__ = compat;
+
+export { compat };
+export default compat;
+`;
+}
+
+/**
+ * @param {ResolvedRippleConfig | null} config
+ * @returns {boolean}
+ */
+function has_route_config(config) {
+	return (config?.router.routes.length ?? 0) > 0;
+}
+
 /**
  * @param {string} filename
  * @param {ResolvedConfig['root']} root
@@ -327,6 +391,18 @@ export function ripple(inlineOptions = {}) {
 	/** @type {Set<string>} File paths (relative to root) of .ripple modules with #server blocks */
 	const serverBlockModules = new Set();
 
+	/**
+	 * @returns {Promise<ResolvedRippleConfig | null>}
+	 */
+	async function get_current_ripple_config() {
+		if (loadedRippleConfig) return loadedRippleConfig;
+		if (rippleConfig) return rippleConfig;
+		if (!root || !rippleConfigExists(root)) return null;
+
+		loadedRippleConfig = await loadRippleConfig(root);
+		return loadedRippleConfig;
+	}
+
 	/** @type {Plugin[]} */
 	const plugins = [
 		{
@@ -344,6 +420,12 @@ export function ripple(inlineOptions = {}) {
 					const projectRoot = userConfig.root || process.cwd();
 
 					if (rippleConfigExists(projectRoot)) {
+						loadedRippleConfig = await loadRippleConfig(projectRoot);
+
+						if (!has_route_config(loadedRippleConfig)) {
+							return null;
+						}
+
 						const htmlInput = path.join(projectRoot, 'index.html');
 						if (!fs.existsSync(htmlInput)) {
 							throw new Error(
@@ -356,11 +438,9 @@ export function ripple(inlineOptions = {}) {
 							'[@ripple-ts/vite-plugin] Detected ripple.config.ts — configuring client build',
 						);
 
-						// Load ripple.config.ts early so build options (e.g. minify) can
+						// The config was loaded above so build options (e.g. minify) can
 						// influence the client build config returned from this hook.
-						// The loaded config is cached and reused by
-						// buildStart and closeBundle.
-						loadedRippleConfig = await loadRippleConfig(projectRoot);
+						// The loaded config is cached and reused by buildStart/closeBundle.
 
 						const outDir = loadedRippleConfig.build.outDir;
 
@@ -408,9 +488,11 @@ export function ripple(inlineOptions = {}) {
 				}
 
 				if (excludeRippleExternalModules) {
+					/** @type {string[]} */
+					const excluded = userConfig.optimizeDeps?.exclude || [];
 					return {
 						optimizeDeps: {
-							exclude: userConfig.optimizeDeps?.exclude || [],
+							exclude: excluded,
 						},
 					};
 				}
@@ -421,6 +503,7 @@ export function ripple(inlineOptions = {}) {
 				detectedPackages.forEach((pkg) => {
 					ripplePackages.add(pkg);
 				});
+				/** @type {string[]} */
 				const existingExclude = userConfig.optimizeDeps?.exclude || [];
 				console.log('[@ripple-ts/vite-plugin] Scan complete. Found:', detectedPackages);
 				console.log(
@@ -428,7 +511,9 @@ export function ripple(inlineOptions = {}) {
 					existingExclude,
 				);
 				// Merge with existing exclude list
-				const allExclude = [...new Set([...existingExclude, ...ripplePackages])];
+				const ripple_package_list = /** @type {string[]} */ (Array.from(ripplePackages));
+				/** @type {string[]} */
+				const allExclude = [...new Set([...existingExclude, ...ripple_package_list])];
 
 				console.log(`[@ripple-ts/vite-plugin] Merged 'optimizeDeps.exclude':`, allExclude);
 				console.log(
@@ -464,6 +549,8 @@ export function ripple(inlineOptions = {}) {
 					loadedRippleConfig = await loadRippleConfig(root);
 				}
 
+				if (!has_route_config(loadedRippleConfig)) return;
+
 				renderRouteEntries = loadedRippleConfig.router.routes
 					.filter((/** @type {Route} */ r) => r.type === 'render')
 					.map((/** @type {RenderRoute} */ r) => r.entry);
@@ -488,6 +575,10 @@ export function ripple(inlineOptions = {}) {
 					try {
 						rippleConfig = await loadRippleConfig(root, { vite });
 
+						if (!has_route_config(rippleConfig)) {
+							return;
+						}
+
 						// Create router from config
 						router = createRouter(rippleConfig.router.routes);
 						console.log(
@@ -687,7 +778,7 @@ export function ripple(inlineOptions = {}) {
 			transformIndexHtml: {
 				order: 'pre',
 				handler(html) {
-					if (!isBuild || isSSRBuild) return html;
+					if (!isBuild || isSSRBuild || !has_route_config(loadedRippleConfig)) return html;
 
 					// Inject the hydration client entry script before </body>
 					const hydrationScript = `<script type="module" src="virtual:ripple-hydrate"></script>`;
@@ -708,6 +799,8 @@ export function ripple(inlineOptions = {}) {
 					loadedRippleConfig = await loadRippleConfig(root);
 				}
 
+				if (!has_route_config(loadedRippleConfig)) return;
+
 				console.log('[@ripple-ts/vite-plugin] Client build done. Starting server build...');
 
 				// Re-resolve with adapter validation for production builds.
@@ -897,8 +990,12 @@ export function ripple(inlineOptions = {}) {
 
 			async resolveId(id, importer, options) {
 				// Handle virtual hydrate module
-				if (id === 'virtual:ripple-hydrate') {
-					return '\0virtual:ripple-hydrate';
+				if (id === VIRTUAL_HYDRATE_ID) {
+					return RESOLVED_VIRTUAL_HYDRATE_ID;
+				}
+
+				if (id === VIRTUAL_COMPAT_ID) {
+					return RESOLVED_VIRTUAL_COMPAT_ID;
 				}
 
 				// Skip non-package imports (relative/absolute paths)
@@ -941,8 +1038,13 @@ export function ripple(inlineOptions = {}) {
 			},
 
 			async load(id, opts) {
+				if (id === RESOLVED_VIRTUAL_COMPAT_ID) {
+					const compat_config = await get_current_ripple_config();
+					return create_compat_virtual_module(compat_config);
+				}
+
 				// Handle virtual hydrate module
-				if (id === '\0virtual:ripple-hydrate') {
+				if (id === RESOLVED_VIRTUAL_HYDRATE_ID) {
 					if (isBuild && renderRouteEntries.length > 0) {
 						// Production: generate static import map so Vite bundles page components
 						const importMapLines = renderRouteEntries
@@ -955,6 +1057,7 @@ export function ripple(inlineOptions = {}) {
 						// main bundle awaits page module import → page module awaits main bundle's
 						// TLA to complete → circular wait.
 						return `
+import ${JSON.stringify(VIRTUAL_COMPAT_ID)};
 import { hydrate, mount } from 'ripple';
 
 const routeModules = {
@@ -1004,6 +1107,7 @@ ${importMapLines}
 					// Dev mode: use async IIFE to avoid top-level await deadlock
 					// (same reason as production — page modules import from the main bundle)
 					return `
+import ${JSON.stringify(VIRTUAL_COMPAT_ID)};
 import { hydrate, mount } from 'ripple';
 
 (async () => {
@@ -1052,11 +1156,16 @@ import { hydrate, mount } from 'ripple';
 					const ssr = opts?.ssr === true || this.environment.config.consumer === 'server';
 
 					const is_dev = config?.command === 'serve';
+					const current_ripple_config = await get_current_ripple_config();
 
 					const { js, css } = await compile(code, filename, {
 						mode: ssr ? 'server' : 'client',
 						dev: is_dev,
 						hmr: is_dev && !ssr,
+						compat_kinds:
+							current_ripple_config === null
+								? undefined
+								: Object.keys(current_ripple_config.compat),
 					});
 
 					// Track modules with #server blocks for RPC (client build only)

package/src/load-config.js

@@ -15,12 +15,67 @@
  * and the generated production server entry.
  */
 
-/** @import { RippleConfigOptions, ResolvedRippleConfig } from '@ripple-ts/vite-plugin' */
+/** @import { CompatFactoryConfig, RippleConfigOptions, ResolvedRippleConfig } from '@ripple-ts/vite-plugin' */
 
 import path from 'node:path';
 import fs from 'node:fs';
 import { DEFAULT_OUTDIR } from './constants.js';
 
+/**
+ * @param {unknown} entry
+ * @returns {entry is CompatFactoryConfig}
+ */
+function is_compat_descriptor(entry) {
+	return !!entry && typeof entry === 'object' && 'from' in entry;
+}
+
+/**
+ * @param {unknown} entry
+ * @returns {entry is { __ripple_compat__: CompatFactoryConfig }}
+ */
+function is_compat_branded_entry(entry) {
+	return (
+		!!entry &&
+		(typeof entry === 'function' || typeof entry === 'object') &&
+		'__ripple_compat__' in entry &&
+		is_compat_descriptor(entry.__ripple_compat__)
+	);
+}
+
+/**
+ * @param {string} kind
+ * @param {unknown} entry
+ * @returns {CompatFactoryConfig}
+ */
+function normalize_compat_entry(kind, entry) {
+	if (is_compat_branded_entry(entry)) {
+		entry = entry.__ripple_compat__;
+	}
+
+	if (!is_compat_descriptor(entry)) {
+		throw new Error(
+			`[@ripple-ts/vite-plugin] ripple.config.ts compat.${kind} must be either a compat descriptor, a compat factory, or an invoked compat entry.`,
+		);
+	}
+
+	if (typeof entry.from !== 'string' || entry.from.length === 0) {
+		throw new Error(
+			`[@ripple-ts/vite-plugin] ripple.config.ts compat.${kind}.from must be a non-empty string.`,
+		);
+	}
+
+	if (entry.factory !== undefined && typeof entry.factory !== 'string') {
+		throw new Error(
+			`[@ripple-ts/vite-plugin] ripple.config.ts compat.${kind}.factory must be a string when provided.`,
+		);
+	}
+
+	return {
+		from: entry.from,
+		...(entry.factory ? { factory: entry.factory } : {}),
+	};
+}
+
 /**
  * Validate a raw ripple config and apply all defaults.
  *
@@ -46,10 +101,6 @@ export function resolveRippleConfig(raw, options = {}) {
 		);
 	}
 
-	if (!raw.router?.routes) {
-		throw new Error('[@ripple-ts/vite-plugin] ripple.config.ts must define `router.routes`.');
-	}
-
 	if (requireAdapter) {
 		if (!raw.adapter) {
 			throw new Error(
@@ -77,9 +128,15 @@ export function resolveRippleConfig(raw, options = {}) {
 		},
 		adapter: raw.adapter,
 		router: {
-			routes: raw.router.routes,
+			routes: raw.router?.routes ?? [],
 		},
 		middlewares: raw.middlewares ?? [],
+		compat: Object.fromEntries(
+			Object.entries(raw.compat ?? {}).map(([kind, entry]) => [
+				kind,
+				normalize_compat_entry(kind, entry),
+			]),
+		),
 		platform: {
 			env: raw.platform?.env ?? {},
 		},

package/types/index.d.ts

@@ -99,6 +99,26 @@ declare module '@ripple-ts/vite-plugin' {
 		excludeRippleExternalModules?: boolean;
 	}
 
+	export interface CompatFactoryConfig {
+		/** Module specifier that exports the compat factory */
+		from: string;
+		/** Named export to call. Omit to use the module's default export. */
+		factory?: string;
+	}
+
+	export interface CompatFactory<T = unknown> {
+		(): T;
+		__ripple_compat__: CompatFactoryConfig;
+	}
+
+	export interface CompatEntryValue {
+		__ripple_compat__: CompatFactoryConfig;
+	}
+
+	export type CompatConfigEntry = CompatFactoryConfig | CompatFactory | CompatEntryValue;
+
+	export type CompatConfig = Record<string, CompatConfigEntry>;
+
 	export interface RippleConfigOptions {
 		build?: {
 			/** Output directory for the production build. @default 'dist' */
@@ -119,11 +139,21 @@ declare module '@ripple-ts/vite-plugin' {
 			 */
 			runtime: RuntimePrimitives;
 		};
-		router: {
+		router?: {
 			routes: Route[];
 		};
 		/** Global middlewares applied to all routes */
 		middlewares?: Middleware[];
+		/**
+		 * Client-side TSX compat integrations keyed by kind, e.g. `react` for `<tsx:react>`.
+		 *
+		 * You can either pass a descriptor object or import a compat factory directly,
+		 * as long as that factory export carries Ripple compat metadata.
+		 *
+		 * These are compiled into a browser-side compat registry by the Vite plugin,
+		 * allowing `mount()` / `hydrate()` to pick them up automatically.
+		 */
+		compat?: CompatConfig;
 		platform?: {
 			env: Record<string, string>;
 		};
@@ -163,6 +193,8 @@ declare module '@ripple-ts/vite-plugin' {
 		};
 		/** @default [] */
 		middlewares: Middleware[];
+		/** @default {} */
+		compat: Record<string, CompatFactoryConfig>;
 		platform: {
 			/** @default {} */
 			env: Record<string, string>;