@ripple-ts/vite-plugin 0.2.210 → 0.2.211

package/src/server/production.js

@@ -0,0 +1,266 @@
+/**
+ * Production server runtime for Ripple metaframework
+ * This module is used in production builds to handle SSR + API routes
+ */
+
+import { createRouter } from './router.js';
+import { createContext, runMiddlewareChain } from './middleware.js';
+
+/**
+ * @typedef {import('@ripple-ts/vite-plugin').Route} Route
+ * @typedef {import('@ripple-ts/vite-plugin').Middleware} Middleware
+ * @typedef {import('@ripple-ts/vite-plugin').RenderRoute} RenderRoute
+ * @typedef {import('@ripple-ts/vite-plugin').ServerRoute} ServerRoute
+ */
+
+/**
+ * @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
+ */
+
+/**
+ * Create a production request handler from a manifest
+ *
+ * @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
+ * @returns {(request: Request) => Promise<Response>}
+ */
+export function createHandler(manifest, options) {
+	const { render, getCss, clientBase = '/' } = options;
+	const router = createRouter(manifest.routes);
+	const globalMiddlewares = manifest.middlewares || [];
+
+	return async function handler(request) {
+		const url = new URL(request.url);
+		const method = request.method;
+
+		// Match route
+		const match = router.match(method, url.pathname);
+
+		if (!match) {
+			return new Response('Not Found', { status: 404 });
+		}
+
+		// Create context
+		const context = createContext(request, match.params);
+
+		try {
+			if (match.route.type === 'render') {
+				return await handleRenderRoute(
+					match.route,
+					context,
+					manifest,
+					globalMiddlewares,
+					render,
+					getCss,
+					clientBase,
+				);
+			} else {
+				return await handleServerRoute(match.route, context, globalMiddlewares);
+			}
+		} catch (error) {
+			console.error('[ripple] Request error:', error);
+			return new Response('Internal Server Error', { status: 500 });
+		}
+	};
+}
+
+/**
+ * Handle a RenderRoute in production
+ *
+ * @param {RenderRoute} route
+ * @param {import('@ripple-ts/vite-plugin').Context} context
+ * @param {ServerManifest} manifest
+ * @param {Middleware[]} globalMiddlewares
+ * @param {(component: Function) => Promise<RenderResult>} render
+ * @param {(css: Set<string>) => string} getCss
+ * @param {string} clientBase
+ * @returns {Promise<Response>}
+ */
+async function handleRenderRoute(
+	route,
+	context,
+	manifest,
+	globalMiddlewares,
+	render,
+	getCss,
+	clientBase,
+) {
+	const renderHandler = async () => {
+		// Get the page component
+		const PageComponent = manifest.components[route.entry];
+		if (!PageComponent) {
+			throw new Error(`Component not found: ${route.entry}`);
+		}
+
+		// Get layout if specified
+		let RootComponent;
+		const pageProps = { params: context.params };
+
+		if (route.layout && manifest.layouts[route.layout]) {
+			const LayoutComponent = manifest.layouts[route.layout];
+			RootComponent = createLayoutWrapper(LayoutComponent, PageComponent, pageProps);
+		} else {
+			RootComponent = createPropsWrapper(PageComponent, pageProps);
+		}
+
+		// Render to HTML
+		const { head, body, css } = await render(RootComponent);
+
+		// Generate CSS tags
+		let cssContent = '';
+		if (css.size > 0) {
+			const cssString = getCss(css);
+			if (cssString) {
+				cssContent = `<style data-ripple-ssr>${cssString}</style>`;
+			}
+		}
+
+		// Generate the full HTML document
+		const html = generateHtml({
+			head: head + cssContent,
+			body,
+			route,
+			context,
+			clientBase,
+		});
+
+		return new Response(html, {
+			status: 200,
+			headers: { 'Content-Type': 'text/html; charset=utf-8' },
+		});
+	};
+
+	return runMiddlewareChain(context, globalMiddlewares, route.before || [], renderHandler, []);
+}
+
+/**
+ * Handle a ServerRoute in production
+ *
+ * @param {ServerRoute} route
+ * @param {import('@ripple-ts/vite-plugin').Context} context
+ * @param {Middleware[]} globalMiddlewares
+ * @returns {Promise<Response>}
+ */
+async function handleServerRoute(route, context, globalMiddlewares) {
+	const handler = async () => route.handler(context);
+	return runMiddlewareChain(
+		context,
+		globalMiddlewares,
+		route.before || [],
+		handler,
+		route.after || [],
+	);
+}
+
+/**
+ * Create a wrapper component that injects props
+ * @param {Function} Component
+ * @param {Record<string, unknown>} props
+ * @returns {Function}
+ */
+function createPropsWrapper(Component, props) {
+	return function WrappedComponent(/** @type {unknown} */ output, additionalProps = {}) {
+		return Component(output, { ...additionalProps, ...props });
+	};
+}
+
+/**
+ * Create a wrapper that composes a layout with a page component
+ * @param {Function} Layout
+ * @param {Function} Page
+ * @param {Record<string, unknown>} pageProps
+ * @returns {Function}
+ */
+function createLayoutWrapper(Layout, Page, pageProps) {
+	return function LayoutWrapper(/** @type {unknown} */ output, additionalProps = {}) {
+		const children = (/** @type {unknown} */ childOutput) => {
+			return Page(childOutput, { ...additionalProps, ...pageProps });
+		};
+		return Layout(output, { ...additionalProps, children });
+	};
+}
+
+/**
+ * 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>`;
+}
+
+/**
+ * Escape script content to prevent XSS
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeScript(str) {
+	return str.replace(/</g, '\\u003c').replace(/>/g, '\\u003e');
+}

package/src/server/render-route.js

@@ -0,0 +1,232 @@
+import { readFile } from 'node:fs/promises';
+import { join, sep } from 'node:path';
+
+/**
+ * @typedef {import('@ripple-ts/vite-plugin').Context} Context
+ * @typedef {import('@ripple-ts/vite-plugin').RenderRoute} RenderRoute
+ * @typedef {import('vite').ViteDevServer} ViteDevServer
+ */
+
+/**
+ * @typedef {Object} RenderResult
+ * @property {string} head
+ * @property {string} body
+ * @property {Set<string>} css
+ */
+
+/**
+ * Handle SSR rendering for a RenderRoute
+ *
+ * @param {RenderRoute} route
+ * @param {Context} context
+ * @param {ViteDevServer} vite
+ * @returns {Promise<Response>}
+ */
+export async function handleRenderRoute(route, context, vite) {
+	try {
+		// Load ripple server utilities
+		const { render, get_css_for_hashes } = await vite.ssrLoadModule('ripple/server');
+
+		// Load the page component
+		const pageModule = await vite.ssrLoadModule(route.entry);
+		const PageComponent = getDefaultExport(pageModule);
+
+		if (!PageComponent) {
+			throw new Error(`No default export found in ${route.entry}`);
+		}
+
+		// Build the component tree (with optional layout)
+		let RootComponent;
+		const pageProps = { params: context.params };
+
+		if (route.layout) {
+			// Load layout component
+			const layoutModule = await vite.ssrLoadModule(route.layout);
+			const LayoutComponent = getDefaultExport(layoutModule);
+
+			if (!LayoutComponent) {
+				throw new Error(`No default export found in ${route.layout}`);
+			}
+
+			// Create a wrapper that composes layout + page
+			// Layout receives children as a component prop
+			RootComponent = createLayoutWrapper(LayoutComponent, PageComponent, pageProps);
+		} else {
+			// No layout - render page directly with props
+			RootComponent = createPropsWrapper(PageComponent, pageProps);
+		}
+
+		// Render to HTML
+		/** @type {RenderResult} */
+		const { head, body, css } = await render(RootComponent);
+
+		// Generate CSS tags
+		let cssContent = '';
+		if (css.size > 0) {
+			const cssString = get_css_for_hashes(css);
+			if (cssString) {
+				cssContent = `<style data-ripple-ssr>${cssString}</style>`;
+			}
+		}
+
+		// Build head content with hydration data
+		const routeData = JSON.stringify({
+			entry: route.entry,
+			params: context.params,
+		});
+		const headContent = [
+			head,
+			cssContent,
+			`<script id="__ripple_data" type="application/json">${escapeScript(routeData)}</script>`,
+		]
+			.filter(Boolean)
+			.join('\n');
+
+		// Load and process index.html template
+		const templatePath = join(vite.config.root, 'public', 'index.html');
+		let template = await readFile(templatePath, 'utf-8');
+
+		// Apply Vite's HTML transforms (HMR client, module resolution, etc.)
+		template = await vite.transformIndexHtml(context.url.pathname, template);
+
+		// Replace placeholders
+		let html = template.replace('<!--ssr-head-->', headContent).replace('<!--ssr-body-->', body);
+
+		// Inject hydration script before </body>
+		const hydrationScript = `<script type="module" src="/@id/virtual:ripple-hydrate"></script>`;
+		html = html.replace('</body>', `${hydrationScript}\n</body>`);
+
+		return new Response(html, {
+			status: 200,
+			headers: {
+				'Content-Type': 'text/html; charset=utf-8',
+			},
+		});
+	} catch (error) {
+		console.error('[ripple] SSR render error:', error);
+
+		const errorHtml = generateErrorHtml(error, route);
+		return new Response(errorHtml, {
+			status: 500,
+			headers: {
+				'Content-Type': 'text/html; charset=utf-8',
+			},
+		});
+	}
+}
+
+/**
+ * Get the default export from a module
+ * Handles both `export default` and `export { X as default }`
+ *
+ * @param {Record<string, unknown>} module
+ * @returns {Function | null}
+ */
+function getDefaultExport(module) {
+	if (typeof module.default === 'function') {
+		return module.default;
+	}
+	// Look for a component-like export (capitalized function)
+	for (const [key, value] of Object.entries(module)) {
+		if (typeof value === 'function' && /^[A-Z]/.test(key)) {
+			return value;
+		}
+	}
+	return null;
+}
+
+/**
+ * Create a wrapper component that injects props
+ *
+ * @param {Function} Component
+ * @param {Record<string, unknown>} props
+ * @returns {Function}
+ */
+function createPropsWrapper(Component, props) {
+	/**
+	 * @param {unknown} output
+	 * @param {Record<string, unknown>} additionalProps
+	 */
+	return function WrappedComponent(output, additionalProps = {}) {
+		return Component(output, { ...additionalProps, ...props });
+	};
+}
+
+/**
+ * Create a wrapper that composes a layout with a page component
+ * The layout receives the page as its children prop
+ *
+ * @param {Function} Layout
+ * @param {Function} Page
+ * @param {Record<string, unknown>} pageProps
+ * @returns {Function}
+ */
+function createLayoutWrapper(Layout, Page, pageProps) {
+	/**
+	 * @param {unknown} output
+	 * @param {Record<string, unknown>} additionalProps
+	 */
+	return function LayoutWrapper(output, additionalProps = {}) {
+		// Children is a component function that renders the page
+		const children = (/** @type {unknown} */ childOutput) => {
+			return Page(childOutput, { ...additionalProps, ...pageProps });
+		};
+
+		return Layout(output, { ...additionalProps, children });
+	};
+}
+
+/**
+ * Escape script content to prevent XSS
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeScript(str) {
+	return str.replace(/</g, '\\u003c').replace(/>/g, '\\u003e');
+}
+
+/**
+ * Generate an error HTML page for development
+ *
+ * @param {unknown} error
+ * @param {RenderRoute} route
+ * @returns {string}
+ */
+function generateErrorHtml(error, route) {
+	const message = error instanceof Error ? error.message : String(error);
+	const stack = error instanceof Error ? error.stack : '';
+
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>SSR Error</title>
+<style>
+body { font-family: system-ui, sans-serif; padding: 2rem; background: #1a1a1a; color: #fff; }
+h1 { color: #ff6b6b; }
+pre { background: #2d2d2d; padding: 1rem; border-radius: 4px; overflow-x: auto; }
+.route { color: #888; }
+</style>
+</head>
+<body>
+<h1>SSR Render Error</h1>
+<p class="route">Route: ${route.path} → ${route.entry}</p>
+<pre>${escapeHtml(message)}</pre>
+${stack ? `<pre>${escapeHtml(stack)}</pre>` : ''}
+</body>
+</html>`;
+}
+
+/**
+ * Escape HTML entities
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeHtml(str) {
+	return str
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;');
+}

package/src/server/router.js

@@ -0,0 +1,122 @@
+/**
+ * @typedef {import('@ripple-ts/vite-plugin').Route} Route
+ * @typedef {import('@ripple-ts/vite-plugin').RenderRoute} RenderRoute
+ * @typedef {import('@ripple-ts/vite-plugin').ServerRoute} ServerRoute
+ */
+
+/**
+ * @typedef {Object} RouteMatch
+ * @property {Route} route
+ * @property {Record<string, string>} params
+ */
+
+/**
+ * @typedef {Object} CompiledRoute
+ * @property {Route} route
+ * @property {RegExp} pattern
+ * @property {string[]} paramNames
+ * @property {number} specificity - Higher = more specific (static > param > catch-all)
+ */
+
+/**
+ * Convert a route path pattern to a RegExp
+ * Supports:
+ * - Static segments: /about, /api/hello
+ * - Named params: /posts/:id, /users/:userId/posts/:postId
+ * - Catch-all: /docs/*slug
+ *
+ * @param {string} path
+ * @returns {{ pattern: RegExp, paramNames: string[], specificity: number }}
+ */
+function compilePath(path) {
+	/** @type {string[]} */
+	const paramNames = [];
+	let specificity = 0;
+
+	// Escape special regex characters except our param syntax
+	const regexString = path
+		.split('/')
+		.map((segment) => {
+			if (!segment) return '';
+
+			// Catch-all param: *slug
+			if (segment.startsWith('*')) {
+				const paramName = segment.slice(1);
+				paramNames.push(paramName);
+				specificity += 1; // Lowest specificity
+				return '(.+)';
+			}
+
+			// Named param: :id
+			if (segment.startsWith(':')) {
+				const paramName = segment.slice(1);
+				paramNames.push(paramName);
+				specificity += 10; // Medium specificity
+				return '([^/]+)';
+			}
+
+			// Static segment
+			specificity += 100; // Highest specificity
+			return escapeRegex(segment);
+		})
+		.join('/');
+
+	const pattern = new RegExp(`^${regexString || '/'}$`);
+	return { pattern, paramNames, specificity };
+}
+
+/**
+ * Escape special regex characters
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeRegex(str) {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Create a router from a list of routes
+ * @param {Route[]} routes
+ * @returns {{ match: (method: string, pathname: string) => RouteMatch | null }}
+ */
+export function createRouter(routes) {
+	/** @type {CompiledRoute[]} */
+	const compiledRoutes = routes.map((route) => {
+		const { pattern, paramNames, specificity } = compilePath(route.path);
+		return { route, pattern, paramNames, specificity };
+	});
+
+	// Sort by specificity (higher first) for correct matching order
+	compiledRoutes.sort((a, b) => b.specificity - a.specificity);
+
+	return {
+		/**
+		 * Match a request to a route
+		 * @param {string} method
+		 * @param {string} pathname
+		 * @returns {RouteMatch | null}
+		 */
+		match(method, pathname) {
+			for (const { route, pattern, paramNames } of compiledRoutes) {
+				// Check method for ServerRoute
+				if (route.type === 'server') {
+					const methods = /** @type {ServerRoute} */ (route).methods;
+					if (!methods.includes(method.toUpperCase())) {
+						continue;
+					}
+				}
+
+				const match = pathname.match(pattern);
+				if (match) {
+					/** @type {Record<string, string>} */
+					const params = {};
+					for (let i = 0; i < paramNames.length; i++) {
+						params[paramNames[i]] = decodeURIComponent(match[i + 1]);
+					}
+					return { route, params };
+				}
+			}
+			return null;
+		},
+	};
+}

package/src/server/server-route.js

@@ -0,0 +1,46 @@
+/**
+ * @typedef {import('@ripple-ts/vite-plugin').Context} Context
+ * @typedef {import('@ripple-ts/vite-plugin').ServerRoute} ServerRoute
+ * @typedef {import('@ripple-ts/vite-plugin').Middleware} Middleware
+ */
+
+import { runMiddlewareChain } from './middleware.js';
+
+/**
+ * Handle a ServerRoute (API endpoint)
+ *
+ * @param {ServerRoute} route
+ * @param {Context} context
+ * @param {Middleware[]} globalMiddlewares
+ * @returns {Promise<Response>}
+ */
+export async function handleServerRoute(route, context, globalMiddlewares) {
+	try {
+		// The handler wrapped as a function returning Promise<Response>
+		const handler = async () => {
+			return route.handler(context);
+		};
+
+		// Run the middleware chain: global → before → handler → after
+		const response = await runMiddlewareChain(
+			context,
+			globalMiddlewares,
+			route.before,
+			handler,
+			route.after,
+		);
+
+		return response;
+	} catch (error) {
+		console.error('[ripple] API route error:', error);
+
+		// Return error response
+		const message = error instanceof Error ? error.message : 'Internal Server Error';
+		return new Response(JSON.stringify({ error: message }), {
+			status: 500,
+			headers: {
+				'Content-Type': 'application/json',
+			},
+		});
+	}
+}