@ripple-ts/vite-plugin 0.3.65 → 0.3.66

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @ripple-ts/vite-plugin
 
+## 0.3.66
+
+### Patch Changes
+
+- [#1168](https://github.com/Ripple-TS/ripple/pull/1168)
+  [`146cbf5`](https://github.com/Ripple-TS/ripple/commit/146cbf58120aad05161d503118a47bdc566ba869)
+  Thanks [@leonidaz](https://github.com/leonidaz)! - Add global root pending/catch
+  boundary support and allow Ripple config routes to reference named entry
+  exports.
+
+  Refactor vite-plugin to keep code generation in one place, produce cache as
+  necessary and generate actual files for inspection.
+
+- Updated dependencies
+  [[`1dc0331`](https://github.com/Ripple-TS/ripple/commit/1dc0331f7b7296545ee459dc31a92057871cbb0d),
+  [`bf1cb96`](https://github.com/Ripple-TS/ripple/commit/bf1cb96f2ea9b325e30f5a051c451f92659d20f9)]:
+  - @tsrx/ripple@0.1.14
+  - @ripple-ts/adapter@0.3.66
+
 ## 0.3.65
 
 ### Patch Changes

package/package.json

@@ -3,7 +3,7 @@
   "description": "Vite plugin for Ripple",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.3.65",
+  "version": "0.3.66",
   "type": "module",
   "module": "src/index.js",
   "main": "src/index.js",
@@ -32,14 +32,14 @@
     "url": "https://github.com/Ripple-TS/ripple/issues"
   },
   "dependencies": {
-    "@tsrx/ripple": "0.1.13",
-    "@ripple-ts/adapter": "0.3.65"
+    "@ripple-ts/adapter": "0.3.66",
+    "@tsrx/ripple": "0.1.14"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
     "type-fest": "^5.6.0",
     "vite": "^8.0.12",
-    "ripple": "0.3.65"
+    "ripple": "0.3.66"
   },
   "publishConfig": {
     "access": "public"

package/src/index.js

@@ -22,8 +22,20 @@ import {
 	rippleConfigExists,
 } from './load-config.js';
 import { ENTRY_FILENAME } from './constants.js';
+import {
+	RESOLVED_ADAPTER_BROWSER_STUB_ID,
+	RESOLVED_VIRTUAL_COMPAT_ID,
+	SERVER_ONLY_ADAPTER_IDS,
+	VIRTUAL_COMPAT_ID,
+	create_adapter_browser_stub_source,
+	create_client_entry_source,
+	create_compat_virtual_module,
+	to_vite_root_import,
+	write_project_generated_file,
+} from './project-codegen.js';
 
 import { patch_global_fetch, is_rpc_request, handle_rpc_request } from '@ripple-ts/adapter/rpc';
+import { get_route_entry_path } from './routes.js';
 
 // Re-export route classes
 export { RenderRoute, ServerRoute } from './routes.js';
@@ -38,8 +50,6 @@ 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';
 const RIPPLE_EXTENSIONS = ['.tsrx'];
 const RIPPLE_EXTENSION_PATTERN = /\.tsrx$/;
 
@@ -87,52 +97,6 @@ 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}
@@ -464,7 +428,12 @@ export function ripple(inlineOptions = {}) {
 							(/** @type {Route} */ r) => r.type === 'render',
 						);
 						const uniqueEntries = [
-							...new Set(renderRoutes.map((/** @type {RenderRoute} */ r) => r.entry)),
+							...new Set(
+								renderRoutes
+									.map((/** @type {RenderRoute} */ r) => r.entry)
+									.map(get_route_entry_path)
+									.filter((entry) => typeof entry === 'string'),
+							),
 						];
 						for (const entry of uniqueEntries) {
 							const sourcePath = entry.startsWith('/') ? entry.slice(1) : entry;
@@ -563,7 +532,9 @@ export function ripple(inlineOptions = {}) {
 
 				renderRouteEntries = loadedRippleConfig.router.routes
 					.filter((/** @type {Route} */ r) => r.type === 'render')
-					.map((/** @type {RenderRoute} */ r) => r.entry);
+					.map((/** @type {RenderRoute} */ r) => r.entry)
+					.map(get_route_entry_path)
+					.filter((entry) => typeof entry === 'string');
 
 				// Deduplicate entries (multiple routes can share the same component)
 				renderRouteEntries = [...new Set(renderRouteEntries)];
@@ -761,7 +732,12 @@ export function ripple(inlineOptions = {}) {
 									globalMiddlewares,
 									freshMatch.route.before || [],
 									async () =>
-										handleRenderRoute(/** @type {RenderRoute} */ (freshMatch.route), context, vite),
+										handleRenderRoute(
+											/** @type {RenderRoute} */ (freshMatch.route),
+											context,
+											vite,
+											rippleConfig ?? undefined,
+										),
 									[],
 								);
 							} else {
@@ -956,7 +932,12 @@ export function ripple(inlineOptions = {}) {
 					(/** @type {Route} */ r) => r.type === 'render',
 				);
 				const uniqueEntries = [
-					...new Set(renderRoutes.map((/** @type {RenderRoute} */ r) => r.entry)),
+					...new Set(
+						renderRoutes
+							.map((/** @type {RenderRoute} */ r) => r.entry)
+							.map(get_route_entry_path)
+							.filter((entry) => typeof entry === 'string'),
+					),
 				];
 
 				for (const entry of uniqueEntries) {
@@ -1009,6 +990,11 @@ export function ripple(inlineOptions = {}) {
 					rpcModulePaths: [...serverModuleModules],
 					clientAssetMap,
 				});
+				const serverEntryFile = write_project_generated_file(
+					config,
+					'server-entry.js',
+					serverEntryCode,
+				);
 
 				const VIRTUAL_SERVER_ENTRY_ID = 'virtual:ripple-server-entry';
 				const RESOLVED_VIRTUAL_SERVER_ENTRY_ID = '\0' + VIRTUAL_SERVER_ENTRY_ID;
@@ -1020,7 +1006,9 @@ export function ripple(inlineOptions = {}) {
 						if (id === VIRTUAL_SERVER_ENTRY_ID) return RESOLVED_VIRTUAL_SERVER_ENTRY_ID;
 					},
 					load(id) {
-						if (id === RESOLVED_VIRTUAL_SERVER_ENTRY_ID) return serverEntryCode;
+						if (id === RESOLVED_VIRTUAL_SERVER_ENTRY_ID) {
+							return fs.readFileSync(serverEntryFile, 'utf-8');
+						}
 					},
 				};
 
@@ -1086,6 +1074,10 @@ export function ripple(inlineOptions = {}) {
 			},
 
 			async resolveId(id, importer, options) {
+				if (!options?.ssr && SERVER_ONLY_ADAPTER_IDS.has(id)) {
+					return RESOLVED_ADAPTER_BROWSER_STUB_ID;
+				}
+
 				// Handle virtual hydrate module
 				if (id === VIRTUAL_HYDRATE_ID) {
 					return RESOLVED_VIRTUAL_HYDRATE_ID;
@@ -1135,6 +1127,10 @@ export function ripple(inlineOptions = {}) {
 			},
 
 			async load(id, opts) {
+				if (id === RESOLVED_ADAPTER_BROWSER_STUB_ID) {
+					return create_adapter_browser_stub_source();
+				}
+
 				if (id === RESOLVED_VIRTUAL_COMPAT_ID) {
 					const compat_config = await get_current_ripple_config();
 					return create_compat_virtual_module(compat_config);
@@ -1142,102 +1138,15 @@ export function ripple(inlineOptions = {}) {
 
 				// Handle virtual hydrate module
 				if (id === RESOLVED_VIRTUAL_HYDRATE_ID) {
-					if (isBuild && renderRouteEntries.length > 0) {
-						// Production: generate static import map so Vite bundles page components
-						const importMapLines = renderRouteEntries
-							.map((entry) => `  ${JSON.stringify(entry)}: () => import(${JSON.stringify(entry)}),`)
-							.join('\n');
-
-						// IMPORTANT: Use async IIFE instead of top-level await.
-						// The page modules statically import from the main bundle (which contains
-						// the runtime). If we used top-level await here, it would deadlock:
-						// 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 = {
-${importMapLines}
-};
-
-(async () => {
-  try {
-    const data = JSON.parse(document.getElementById('__ripple_data').textContent);
-    const target = document.getElementById('root');
-    const loadModule = routeModules[data.entry];
-
-    if (!loadModule) {
-      console.error('[ripple] No client module for route:', data.entry);
-      return;
-    }
-
-    const module = await loadModule();
-    const Component =
-      module.default ||
-      Object.entries(module).find(([key, value]) => typeof value === 'function' && /^[A-Z]/.test(key))?.[1];
-
-    if (!Component || !target) {
-      console.error('[ripple] Unable to hydrate route: missing component export or #root target.');
-      return;
-    }
-
-    try {
-      hydrate(Component, {
-        target,
-        props: { params: data.params }
-      });
-    } catch (error) {
-      console.warn('[ripple] Hydration failed, falling back to mount.', error);
-      mount(Component, {
-        target,
-        props: { params: data.params }
-      });
-    }
-  } catch (error) {
-    console.error('[ripple] Failed to bootstrap client hydration.', error);
-  }
-})();
-`;
-					}
-
-					// 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 () => {
-  try {
-    const data = JSON.parse(document.getElementById('__ripple_data').textContent);
-    const target = document.getElementById('root');
-    const module = await import(/* @vite-ignore */ data.entry);
-    const Component =
-      module.default ||
-      Object.entries(module).find(([key, value]) => typeof value === 'function' && /^[A-Z]/.test(key))?.[1];
-
-    if (!Component || !target) {
-      console.error('[ripple] Unable to hydrate route: missing component export or #root target.');
-      return;
-    }
-
-    try {
-      hydrate(Component, {
-        target,
-        props: { params: data.params }
-      });
-    } catch (error) {
-      console.warn('[ripple] Hydration failed, falling back to mount.', error);
-      mount(Component, {
-        target,
-        props: { params: data.params }
-      });
-    }
-  } catch (error) {
-    console.error('[ripple] Failed to bootstrap client hydration.', error);
-  }
-})();
-`;
+					const file = write_project_generated_file(
+						config,
+						'client-entry.js',
+						create_client_entry_source({
+							configPath: to_vite_root_import(getRippleConfigPath(root), root),
+							staticEntries: isBuild ? renderRouteEntries : [],
+						}),
+					);
+					return fs.readFileSync(file, 'utf-8');
 				}
 
 				if (cssCache.has(id)) {

package/src/load-config.js

@@ -19,8 +19,11 @@
 
 import path from 'node:path';
 import fs from 'node:fs';
+import { compile } from '@tsrx/ripple';
 import { DEFAULT_OUTDIR } from './constants.js';
 
+const RIPPLE_EXTENSION_PATTERN = /\.tsrx$/;
+
 /**
  * @param {unknown} entry
  * @returns {entry is CompatFactoryConfig}
@@ -76,6 +79,57 @@ function normalize_compat_entry(kind, entry) {
 	};
 }
 
+/**
+ * @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('[@ripple-ts/vite-plugin] RenderRoute requires a string/tuple `entry`.');
+	}
+
+	if (render_route.layout !== undefined && typeof render_route.layout !== 'string') {
+		throw new Error('[@ripple-ts/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('[@ripple-ts/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('[@ripple-ts/vite-plugin] rootBoundary.pending must be a component function.');
+	}
+	if (boundary.catch !== undefined && typeof boundary.catch !== 'function') {
+		throw new Error('[@ripple-ts/vite-plugin] rootBoundary.catch must be a component function.');
+	}
+}
+
 /**
  * Validate a raw ripple config and apply all defaults.
  *
@@ -117,6 +171,16 @@ export function resolveRippleConfig(raw, options = {}) {
 		}
 	}
 
+	if (raw.router?.routes !== undefined && !Array.isArray(raw.router.routes)) {
+		throw new Error('[@ripple-ts/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
 	// ------------------------------------------------------------------
@@ -130,6 +194,7 @@ export function resolveRippleConfig(raw, options = {}) {
 		router: {
 			routes: raw.router?.routes ?? [],
 		},
+		rootBoundary: raw.rootBoundary ?? {},
 		middlewares: raw.middlewares ?? [],
 		compat: Object.fromEntries(
 			Object.entries(raw.compat ?? {}).map(([kind, entry]) => [
@@ -211,12 +276,20 @@ export async function loadRippleConfig(projectRoot, options = {}) {
 		configFile: false,
 		appType: 'custom',
 		server: { middlewareMode: true },
-		// We don't need to load the ripple plugin for now
-		// but if we start using references to components in router.routes
-		// then we'll need to add the plugin here to handle the .tsrx imports.
-		// But this will cause a circular references warning
-		// that we should resolve when we implement references to components.
-		// plugins: [ripple({ excludeRippleExternalModules: true })],
+		plugins: [
+			{
+				name: 'ripple-config-tsrx-loader',
+				transform(source, id) {
+					if (!RIPPLE_EXTENSION_PATTERN.test(id)) return null;
+					const filename = id.replace(projectRoot, '');
+					return compile(source, filename, {
+						mode: 'server',
+						dev: true,
+						hmr: false,
+					});
+				},
+			},
+		],
 		logLevel: 'silent',
 	});
 

package/src/project-codegen.js

@@ -0,0 +1,201 @@
+/** @import { ResolvedConfig } from 'vite' */
+/** @import { ResolvedRippleConfig } from '@ripple-ts/vite-plugin' */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const VIRTUAL_COMPAT_ID = 'virtual:ripple-compat';
+export const RESOLVED_VIRTUAL_COMPAT_ID = '\0virtual:ripple-compat';
+export const RESOLVED_ADAPTER_BROWSER_STUB_ID = '\0ripple: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();
+
+/**
+ * @param {ResolvedRippleConfig | null} config
+ * @returns {string}
+ */
+export 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;
+`;
+}
+
+/**
+ * @returns {string}
+ */
+export function create_adapter_browser_stub_source() {
+	return `export const runtime = undefined;
+export function serve() {
+  throw new Error('[ripple] Server adapters cannot run in the browser.');
+}
+export function nodeRequestToWebRequest() {
+  throw new Error('[ripple] Node request helpers cannot run in the browser.');
+}
+export function webResponseToNodeResponse() {
+  throw new Error('[ripple] 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;
+}
+
+/**
+ * @param {{ configPath: string, staticEntries: string[] }} options
+ * @returns {string}
+ */
+export function create_client_entry_source(options) {
+	const static_imports = options.staticEntries
+		.map((entry) => `  ${JSON.stringify(entry)}: () => import(${JSON.stringify(entry)}),`)
+		.join('\n');
+
+	return `// Auto-generated by @ripple-ts/vite-plugin.
+// This file is written to Vite's cacheDir/project folder.
+
+import ${JSON.stringify(VIRTUAL_COMPAT_ID)};
+import { hydrate, mount } from 'ripple';
+import rippleConfig from ${JSON.stringify(options.configPath)};
+
+const routeModules = {
+${static_imports}
+};
+
+const renderRoutes = (rippleConfig.router?.routes ?? []).filter((route) => route.type === 'render');
+const rootBoundary = rippleConfig.rootBoundary;
+
+function getRouteEntryPath(entry) {
+  return Array.isArray(entry) ? entry[1] : entry;
+}
+
+function getRouteEntryExportName(entry) {
+  return Array.isArray(entry) ? entry[0] : undefined;
+}
+
+function getComponentExport(module, exportName) {
+  if (exportName && typeof module[exportName] === 'function') return module[exportName];
+  if (typeof module.default === 'function') return module.default;
+  return Object.entries(module).find(([key, value]) => typeof value === 'function' && /^[A-Z]/.test(key))?.[1];
+}
+
+async function resolveRouteComponent(data) {
+  const route =
+    typeof data.routeIndex === 'number' ? renderRoutes[data.routeIndex] : undefined;
+
+  const entry = route?.entry ?? data.entry;
+  const entryPath = getRouteEntryPath(entry);
+  const exportName = getRouteEntryExportName(entry);
+  if (!entryPath) return null;
+
+  const loadModule = routeModules[entryPath] ?? (() => import(/* @vite-ignore */ entryPath));
+  return getComponentExport(await loadModule(), exportName);
+}
+
+(async () => {
+  try {
+    const data = JSON.parse(document.getElementById('__ripple_data').textContent);
+    const target = document.getElementById('root');
+    const Component = await resolveRouteComponent(data);
+
+    if (!Component || !target) {
+      console.error('[ripple] Unable to hydrate route: missing component export or #root target.');
+      return;
+    }
+
+    try {
+      hydrate(Component, {
+        target,
+        props: { params: data.params },
+        rootBoundary,
+      });
+    } catch (error) {
+      console.warn('[ripple] Hydration failed, falling back to mount.', error);
+      mount(Component, {
+        target,
+        props: { params: data.params },
+        rootBoundary,
+      });
+    }
+  } catch (error) {
+    console.error('[ripple] 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('/');
+}