@ripple-ts/vite-plugin 0.2.213 → 0.2.214

package/src/load-config.js

@@ -0,0 +1,172 @@
+/**
+ * Shared utility for loading and resolving ripple.config.ts.
+ *
+ * `resolveRippleConfig` is the single source of truth for all config
+ * validation and default values. Every consumer should receive a
+ * `ResolvedRippleConfig` rather than applying ad-hoc defaults.
+ *
+ * `loadRippleConfig` 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 { RippleConfigOptions, ResolvedRippleConfig } from '@ripple-ts/vite-plugin' */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { DEFAULT_OUTDIR } from './constants.js';
+
+/**
+ * Validate a raw ripple 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 {RippleConfigOptions} raw - The user-provided config (from ripple.config.ts)
+ * @param {{ requireAdapter?: boolean }} [options]
+ * @returns {ResolvedRippleConfig}
+ */
+export function resolveRippleConfig(raw, options = {}) {
+	const { requireAdapter = false } = options;
+
+	// ------------------------------------------------------------------
+	// Validate
+	// ------------------------------------------------------------------
+	if (!raw) {
+		throw new Error(
+			'[@ripple-ts/vite-plugin] ripple.config.ts must export a default config object.',
+		);
+	}
+
+	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(
+				'[@ripple-ts/vite-plugin] Production builds require an `adapter` in ripple.config.ts. ' +
+					'Install an adapter package (e.g. @ripple-ts/adapter-node) and set the `adapter` property.',
+			);
+		}
+
+		if (!raw.adapter.runtime) {
+			throw new Error(
+				'[@ripple-ts/vite-plugin] The adapter in ripple.config.ts is missing the `runtime` property. ' +
+					'Make sure your adapter exports runtime primitives.',
+			);
+		}
+	}
+
+	// ------------------------------------------------------------------
+	// 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,
+		},
+		middlewares: raw.middlewares ?? [],
+		platform: {
+			env: raw.platform?.env ?? {},
+		},
+		server: {
+			trustProxy: raw.server?.trustProxy ?? false,
+		},
+	};
+}
+
+/**
+ * Return the absolute path to ripple.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 getRippleConfigPath(projectRoot) {
+	return path.join(projectRoot, 'ripple.config.ts');
+}
+
+/**
+ * Check whether a ripple.config.ts file exists in the given root.
+ *
+ * Use this before calling `loadRippleConfig` 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 rippleConfigExists(projectRoot) {
+	return fs.existsSync(getRippleConfigPath(projectRoot));
+}
+
+/**
+ * Load ripple.config.ts, validate, and apply defaults via `resolveRippleConfig`.
+ *
+ * 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<ResolvedRippleConfig>}
+ */
+export async function loadRippleConfig(projectRoot, options = {}) {
+	const { vite, requireAdapter } = options;
+	const configPath = getRippleConfigPath(projectRoot);
+
+	if (!fs.existsSync(configPath)) {
+		throw new Error(`[@ripple-ts/vite-plugin] ripple.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 resolveRippleConfig(configModule.default, { requireAdapter });
+	}
+
+	// Otherwise spin up a temporary Vite server (build / preview).
+	// The temp server only transpiles ripple.config.ts (plain TypeScript) —
+	// no .ripple compilation plugin is needed.
+	const { createServer } = await import('vite');
+
+	const tempVite = await createServer({
+		root: projectRoot,
+		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 .ripple imports.
+		// But this will cause a circular references warning
+		// that we should resolve when we implement references to components.
+		// plugins: [ripple({ excludeRippleExternalModules: true })],
+		logLevel: 'silent',
+	});
+
+	try {
+		const configModule = await tempVite.ssrLoadModule(configPath);
+		return resolveRippleConfig(configModule.default, { requireAdapter });
+	} finally {
+		await tempVite.close();
+	}
+}

package/src/server/production.js

@@ -1,10 +1,24 @@
 /**
- * Production server runtime for Ripple metaframework
- * This module is used in production builds to handle SSR + API routes
+ * Production server runtime for Ripple metaframework.
+ * This module is used in production builds to handle SSR + API routes + RPC.
+ *
+ * It is designed to be imported by the generated server entry and does NOT
+ * depend on Vite at runtime.
+ *
+ * Platform-agnostic — no Node.js-specific imports. Platform capabilities
+ * (hashing, async context) are provided via `manifest.runtime` from the adapter.
  */
 
 import { createRouter } from './router.js';
 import { createContext, runMiddlewareChain } from './middleware.js';
+import {
+	patch_global_fetch,
+	build_rpc_lookup,
+	is_rpc_request,
+	handle_rpc_request,
+} from '@ripple-ts/adapter/rpc';
+
+export { resolveRippleConfig } from '../load-config.js';
 
 /**
  * @typedef {import('@ripple-ts/vite-plugin').Route} Route
@@ -14,39 +28,62 @@ import { createContext, runMiddlewareChain } from './middleware.js';
  */
 
 /**
- * @typedef {Object} ServerManifest
- * @property {Route[]} routes - Array of route definitions
- * @property {Record<string, Function>} components - Map of entry path to component function
- * @property {Record<string, Function>} layouts - Map of layout path to layout function
- * @property {Middleware[]} middlewares - Global middlewares
+@import {
+	ServerManifest,
+	RenderResult,
+	HandlerOptions,
+	ClientAssetEntry,
+} from '@ripple-ts/vite-plugin/production';
  */
 
 /**
- * @typedef {Object} RenderResult
- * @property {string} head
- * @property {string} body
- * @property {Set<string>} css
- */
-
-/**
- * Create a production request handler from a manifest
+ * Create a production request handler from a manifest.
+ *
+ * The returned function is a standard Web `fetch`-style handler:
+ *   `(request: Request) => Promise<Response>`
  *
  * @param {ServerManifest} manifest
- * @param {Object} options
- * @param {(component: Function) => Promise<RenderResult>} options.render - SSR render function
- * @param {(css: Set<string>) => string} options.getCss - Get CSS for hashes
- * @param {string} options.clientBase - Base path for client assets
+ * @param {HandlerOptions} options
  * @returns {(request: Request) => Promise<Response>}
  */
 export function createHandler(manifest, options) {
-	const { render, getCss, clientBase = '/' } = options;
+	const { render, getCss, htmlTemplate, executeServerFunction } = options;
 	const router = createRouter(manifest.routes);
-	const globalMiddlewares = manifest.middlewares || [];
+	const globalMiddlewares = manifest.middlewares;
+	const trustProxy = manifest.trustProxy;
+	const clientAssets = manifest.clientAssets || {};
+
+	// Use adapter's runtime primitives for platform-agnostic operation
+	const runtime = manifest.runtime;
+
+	// Build the RPC lookup table using the adapter's hash function
+	const rpcLookup = manifest.rpcModules
+		? build_rpc_lookup(manifest.rpcModules, runtime.hash)
+		: new Map();
+
+	// Create async context and patch fetch for relative URL resolution in #server blocks
+	const asyncContext = runtime.createAsyncContext();
+	patch_global_fetch(asyncContext);
 
 	return async function handler(request) {
 		const url = new URL(request.url);
 		const method = request.method;
 
+		// Handle RPC requests for #server blocks
+		if (is_rpc_request(url.pathname)) {
+			return handle_rpc_request(request, {
+				resolveFunction(hash) {
+					const entry = rpcLookup.get(hash);
+					if (!entry) return null;
+					const fn = entry.serverObj[entry.funcName];
+					return typeof fn === 'function' ? fn : null;
+				},
+				executeServerFunction,
+				asyncContext,
+				trustProxy,
+			});
+		}
+
 		// Match route
 		const match = router.match(method, url.pathname);
 
@@ -66,7 +103,8 @@ export function createHandler(manifest, options) {
 					globalMiddlewares,
 					render,
 					getCss,
-					clientBase,
+					htmlTemplate,
+					clientAssets,
 				);
 			} else {
 				return await handleServerRoute(match.route, context, globalMiddlewares);
@@ -78,6 +116,10 @@ export function createHandler(manifest, options) {
 	};
 }
 
+// ============================================================================
+// Render routes
+// ============================================================================
+
 /**
  * Handle a RenderRoute in production
  *
@@ -87,7 +129,8 @@ export function createHandler(manifest, options) {
  * @param {Middleware[]} globalMiddlewares
  * @param {(component: Function) => Promise<RenderResult>} render
  * @param {(css: Set<string>) => string} getCss
- * @param {string} clientBase
+ * @param {string} htmlTemplate
+ * @param {Record<string, ClientAssetEntry>} clientAssets
  * @returns {Promise<Response>}
  */
 async function handleRenderRoute(
@@ -97,7 +140,8 @@ async function handleRenderRoute(
 	globalMiddlewares,
 	render,
 	getCss,
-	clientBase,
+	htmlTemplate,
+	clientAssets,
 ) {
 	const renderHandler = async () => {
 		// Get the page component
@@ -120,7 +164,7 @@ async function handleRenderRoute(
 		// Render to HTML
 		const { head, body, css } = await render(RootComponent);
 
-		// Generate CSS tags
+		// Generate inline scoped CSS (from SSR-rendered component hashes)
 		let cssContent = '';
 		if (css.size > 0) {
 			const cssString = getCss(css);
@@ -129,14 +173,46 @@ async function handleRenderRoute(
 			}
 		}
 
-		// Generate the full HTML document
-		const html = generateHtml({
-			head: head + cssContent,
-			body,
-			route,
-			context,
-			clientBase,
+		// Build asset preload tags from the client manifest.
+		// These ensure the browser starts downloading page-specific JS/CSS
+		// immediately, before the hydration script executes.
+		/** @type {string[]} */
+		const preloadTags = [];
+		const entryAssets = clientAssets[route.entry];
+
+		if (entryAssets?.css) {
+			for (const cssFile of entryAssets.css) {
+				preloadTags.push(`<link rel="stylesheet" href="/${cssFile}">`);
+			}
+		}
+		if (entryAssets?.js) {
+			preloadTags.push(`<link rel="modulepreload" href="/${entryAssets.js}">`);
+		}
+
+		// Preload the hydrate runtime so it starts downloading in parallel
+		const hydrateAsset = clientAssets.__hydrate_js;
+		if (hydrateAsset?.js) {
+			preloadTags.push(`<link rel="modulepreload" href="/${hydrateAsset.js}">`);
+		}
+
+		// Build head content with hydration data
+		const routeData = JSON.stringify({
+			entry: route.entry,
+			params: context.params,
 		});
+		const headContent = [
+			head,
+			cssContent,
+			...preloadTags,
+			`<script id="__ripple_data" type="application/json">${escapeScript(routeData)}</script>`,
+		]
+			.filter(Boolean)
+			.join('\n');
+
+		// Inject into the HTML template
+		const html = htmlTemplate
+			.replace('<!--ssr-head-->', headContent)
+			.replace('<!--ssr-body-->', body);
 
 		return new Response(html, {
 			status: 200,
@@ -147,6 +223,10 @@ async function handleRenderRoute(
 	return runMiddlewareChain(context, globalMiddlewares, route.before || [], renderHandler, []);
 }
 
+// ============================================================================
+// Server routes
+// ============================================================================
+
 /**
  * Handle a ServerRoute in production
  *
@@ -166,6 +246,10 @@ async function handleServerRoute(route, context, globalMiddlewares) {
 	);
 }
 
+// ============================================================================
+// Component wrappers
+// ============================================================================
+
 /**
  * Create a wrapper component that injects props
  * @param {Function} Component
@@ -194,67 +278,9 @@ function createLayoutWrapper(Layout, Page, pageProps) {
 	};
 }
 
-/**
- * Generate the full HTML document for production
- * @param {Object} options
- * @param {string} options.head
- * @param {string} options.body
- * @param {RenderRoute} options.route
- * @param {import('@ripple-ts/vite-plugin').Context} options.context
- * @param {string} options.clientBase
- * @returns {string}
- */
-function generateHtml({ head, body, route, context, clientBase }) {
-	const routeData = JSON.stringify({
-		entry: route.entry,
-		params: context.params,
-	});
-
-	return `<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="UTF-8">
-<meta name="viewport" content="width=device-width, initial-scale=1.0">
-${head}
-</head>
-<body>
-<div id="app">${body}</div>
-<script id="__ripple_data" type="application/json">${escapeScript(routeData)}</script>
-<script type="module">
-import { hydrate, mount } from '${clientBase}ripple.js';
-
-const data = JSON.parse(document.getElementById('__ripple_data').textContent);
-const target = document.getElementById('app');
-
-try {
-  const module = await import('${clientBase}' + data.entry.replace(/^\\//, '').replace(/\\.ripple$/, '.js'));
-  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 #app target.');
-  } else {
-    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);
-}
-</script>
-</body>
-</html>`;
-}
+// ============================================================================
+// Utilities
+// ============================================================================
 
 /**
  * Escape script content to prevent XSS

package/src/server/render-route.js

@@ -90,7 +90,7 @@ export async function handleRenderRoute(route, context, vite) {
 			.join('\n');
 
 		// Load and process index.html template
-		const templatePath = join(vite.config.root, 'public', 'index.html');
+		const templatePath = join(vite.config.root, 'index.html');
 		let template = await readFile(templatePath, 'utf-8');
 
 		// Apply Vite's HTML transforms (HMR client, module resolution, etc.)

package/src/server/virtual-entry.js

@@ -0,0 +1,215 @@
+/**
+ * Virtual server entry generator for production builds.
+ *
+ * Generates a self-contained server entry module that:
+ * - Imports all SSR-compiled page components and layouts
+ * - Imports the production request handler (createHandler)
+ * - Imports the adapter's serve() function
+ * - Wires routes, middlewares, RPC, and boots the HTTP server
+ */
+
+/** @import { Route } from '@ripple-ts/vite-plugin' */
+
+/**
+ * @typedef {Object} ClientAssetEntry
+ * @property {string} js - Path to the built JS file
+ * @property {string[]} css - Paths to the built CSS files
+ */
+
+/**
+ * @typedef {Object} VirtualEntryOptions
+ * @property {Route[]} routes - Route definitions from ripple.config.ts
+ * @property {string} rippleConfigPath - Absolute path to ripple.config.ts (for importing middlewares/adapter)
+ * @property {string} htmlTemplatePath - Path to the processed index.html template
+ * @property {string[]} [rpcModulePaths] - Paths (relative to root) of .ripple modules with #server blocks
+ * @property {Record<string, ClientAssetEntry>} [clientAssetMap] - Map of route entry paths to built JS/CSS asset paths
+ */
+
+/**
+ * Generate the virtual server entry module source code.
+ *
+ * The generated module:
+ * 1. Imports ripple SSR utilities (render, get_css_for_hashes, executeServerFunction)
+ * 2. Imports createHandler from @ripple-ts/vite-plugin/production
+ * 3. Imports ripple.config.ts to get adapter, middlewares, and routes
+ * 4. Imports each RenderRoute's entry (and layout) as SSR components
+ * 5. Builds a ServerManifest and creates the fetch handler
+ * 6. Reads the HTML template from disk
+ * 7. Boots the adapter with the handler
+ *
+ * @param {VirtualEntryOptions} options
+ * @returns {string} The generated JavaScript module source
+ */
+export function generateServerEntry(options) {
+	const {
+		routes,
+		rippleConfigPath,
+		htmlTemplatePath,
+		rpcModulePaths = [],
+		clientAssetMap = {},
+	} = options;
+
+	// Collect unique component entries and layouts
+	/** @type {Map<string, string>} entry path → import variable name */
+	const component_imports = new Map();
+	/** @type {Map<string, string>} layout path → import variable name */
+	const layout_imports = new Map();
+	/** @type {Map<string, string>} rpc module path → import variable name */
+	const rpc_imports = new Map();
+
+	let component_index = 0;
+	let layout_index = 0;
+	let rpc_index = 0;
+
+	for (const route of routes) {
+		if (route.type === 'render') {
+			if (!component_imports.has(route.entry)) {
+				component_imports.set(route.entry, `_page_${component_index++}`);
+			}
+			if (route.layout && !layout_imports.has(route.layout)) {
+				layout_imports.set(route.layout, `_layout_${layout_index++}`);
+			}
+		}
+	}
+
+	// Collect RPC modules (sub-components with #server blocks, not already in page entries)
+	for (const rpcPath of rpcModulePaths) {
+		if (!component_imports.has(rpcPath) && !rpc_imports.has(rpcPath)) {
+			rpc_imports.set(rpcPath, `_rpc_${rpc_index++}`);
+		}
+	}
+
+	// --- Dynamic import lines (built from route/RPC config) ---
+
+	const import_lines = [];
+
+	for (const [entry, varName] of component_imports) {
+		import_lines.push(`import * as ${varName} from ${JSON.stringify(entry)};`);
+	}
+	for (const [layout, varName] of layout_imports) {
+		import_lines.push(`import * as ${varName} from ${JSON.stringify(layout)};`);
+	}
+	for (const [rpcPath, varName] of rpc_imports) {
+		import_lines.push(`import * as ${varName} from ${JSON.stringify(rpcPath)};`);
+	}
+
+	// --- Dynamic map entries ---
+
+	const component_entries = [...component_imports]
+		.map(([entry, varName]) => `  ${JSON.stringify(entry)}: getDefaultExport(${varName}),`)
+		.join('\n');
+
+	const layout_entries = [...layout_imports]
+		.map(([layout, varName]) => `  ${JSON.stringify(layout)}: getDefaultExport(${varName}),`)
+		.join('\n');
+
+	// Only check _$_server_$_ on modules known to have #server blocks.
+	// Checking modules without #server blocks causes rollup warnings since
+	// they don't export _$_server_$_.
+	const rpcPathSet = new Set(rpcModulePaths);
+	const rpc_entries = [];
+
+	for (const [entry, varName] of component_imports) {
+		if (rpcPathSet.has(entry)) {
+			rpc_entries.push(`rpcModules[${JSON.stringify(entry)}] = ${varName}._$_server_$_;`);
+		}
+	}
+	for (const [rpcPath, varName] of rpc_imports) {
+		rpc_entries.push(`rpcModules[${JSON.stringify(rpcPath)}] = ${varName}._$_server_$_;`);
+	}
+
+	// --- Assemble the full module ---
+
+	return `\
+// Auto-generated server entry for production build
+// Do not edit — regenerated on each build
+
+import { render, get_css_for_hashes, executeServerFunction } from 'ripple/server';
+import { createHandler, resolveRippleConfig } from '@ripple-ts/vite-plugin/production';
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+
+import _rawRippleConfig from ${JSON.stringify(rippleConfigPath)};
+
+${import_lines.join('\n')}
+
+let rippleConfig;
+try {
+  rippleConfig = resolveRippleConfig(_rawRippleConfig, { requireAdapter: true });
+} catch (e) {
+  console.error(e.message);
+  process.exit(1);
+}
+
+function getDefaultExport(mod) {
+  if (typeof mod.default === 'function') return mod.default;
+  for (const [key, value] of Object.entries(mod)) {
+    if (typeof value === 'function' && /^[A-Z]/.test(key)) return value;
+  }
+  return null;
+}
+
+const components = {
+${component_entries}
+};
+
+const layouts = {
+${layout_entries}
+};
+
+const rpcModules = {};
+${rpc_entries.join('\n')}
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+if (!existsSync(join(__dirname, ${JSON.stringify(htmlTemplatePath)}))) {
+  console.error('[ripple] HTML template not found:', join(__dirname, ${JSON.stringify(htmlTemplatePath)}));
+  process.exit(1);
+}
+const htmlTemplate = readFileSync(join(__dirname, ${JSON.stringify(htmlTemplatePath)}), 'utf-8');
+
+const clientAssets = ${JSON.stringify(clientAssetMap, null, 2)};
+
+const handler = createHandler(
+  {
+    routes: rippleConfig.router.routes,
+    components,
+    layouts,
+    middlewares: rippleConfig.middlewares,
+    rpcModules,
+    trustProxy: rippleConfig.server.trustProxy,
+    runtime: rippleConfig.adapter.runtime,
+    clientAssets,
+  },
+  {
+    render,
+    getCss: get_css_for_hashes,
+    htmlTemplate,
+    executeServerFunction,
+  },
+);
+
+export { handler };
+
+// Auto-boot when running directly (node dist/server/entry.js)
+// Skip when imported as a module (e.g. by a serverless function wrapper)
+const isMainModule = typeof process !== 'undefined' && process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1]);
+if (isMainModule) {
+  if (rippleConfig.adapter?.serve) {
+    const server = rippleConfig.adapter.serve(handler, {
+      static: { dir: join(__dirname, '../client') },
+    });
+    const port = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000;
+    if (isNaN(port) || port < 1 || port > 65535) {
+    	console.error('[ripple] Invalid PORT value:', process.env.PORT);
+    	process.exit(1);
+    }
+    server.listen(port);
+    console.log('[ripple] Production server listening on port ' + port);
+  } else {
+    console.error('[ripple] No adapter configured in ripple.config.ts');
+    process.exit(1);
+  }
+}
+`;
+}