@ripple-ts/vite-plugin 0.2.213 → 0.2.215

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
- */
-
-/**
- * @typedef {Object} RenderResult
- * @property {string} head
- * @property {string} body
- * @property {Set<string>} css
+@import {
+	ServerManifest,
+	RenderResult,
+	HandlerOptions,
+	ClientAssetEntry,
+} from '@ripple-ts/vite-plugin/production';
  */
 
 /**
- * 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 ?? false;
+	const clientAssets = manifest.clientAssets || {};
+
+	// Use adapter's runtime primitives for platform-agnostic operation
+	const runtime = manifest.runtime;
 
-	return async function handler(request) {
+	// 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();
+	const fetchHandle = patch_global_fetch(asyncContext);
+
+	const handler = async function handler(/** @type {Request} */ 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);
@@ -76,8 +114,19 @@ export function createHandler(manifest, options) {
 			return new Response('Internal Server Error', { status: 500 });
 		}
 	};
+
+	// Enable same-origin fetch short-circuit: server-side fetch() calls that
+	// resolve to the same origin are routed directly through this handler
+	// in-process, instead of making a real network request.
+	fetchHandle.set_handler(handler);
+
+	return handler;
 }
 
+// ============================================================================
+// Render routes
+// ============================================================================
+
 /**
  * Handle a RenderRoute in production
  *
@@ -87,7 +136,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 +147,8 @@ async function handleRenderRoute(
 	globalMiddlewares,
 	render,
 	getCss,
-	clientBase,
+	htmlTemplate,
+	clientAssets,
 ) {
 	const renderHandler = async () => {
 		// Get the page component
@@ -120,7 +171,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 +180,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 +230,10 @@ async function handleRenderRoute(
 	return runMiddlewareChain(context, globalMiddlewares, route.before || [], renderHandler, []);
 }
 
+// ============================================================================
+// Server routes
+// ============================================================================
+
 /**
  * Handle a ServerRoute in production
  *
@@ -166,6 +253,10 @@ async function handleServerRoute(route, context, globalMiddlewares) {
 	);
 }
 
+// ============================================================================
+// Component wrappers
+// ============================================================================
+
 /**
  * Create a wrapper component that injects props
  * @param {Function} Component
@@ -194,67 +285,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.)