@ripple-ts/vite-plugin 0.3.34 → 0.3.35

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @ripple-ts/vite-plugin
 
+## 0.3.35
+
+### Patch Changes
+
+- [#966](https://github.com/Ripple-TS/ripple/pull/966)
+  [`caf83e3`](https://github.com/Ripple-TS/ripple/commit/caf83e386faa9133df70460f266fc27ab323082b)
+  Thanks [@RazinShafayet2007](https://github.com/RazinShafayet2007)! - fix:
+  register SSR/API middleware as a pre-hook so it runs before Vite's HTML fallback
+  middleware
+
+  The dev server's `configureServer` hook previously returned a function
+  (post-hook), which registered SSR/API middleware after Vite's internal
+  middleware stack. Vite's HTML fallback middleware would intercept all non-file
+  GET requests first, preventing SSR rendering and API routes from ever executing.
+
+  Switched to a pre-hook (no return value) so middleware is registered before Vite
+  internals. Config loading is deferred to the first request via
+  `ensureConfigLoaded()`, which retries on missing config and surfaces load errors
+  as dev-server 500 pages instead of silently falling through.
+
+- Updated dependencies []:
+  - @tsrx/ripple@0.0.17
+  - @ripple-ts/adapter@0.3.35
+
 ## 0.3.34
 
 ### Patch Changes

package/package.json

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

package/src/index.js

@@ -574,138 +574,225 @@ export function ripple(inlineOptions = {}) {
 			},
 
 			/**
-			 * Configure the dev server with SSR middleware
+			 * Configure the dev server with SSR middleware.
+			 *
+			 * Uses a pre-hook (no return value) so that Ripple's SSR/API
+			 * middleware is registered BEFORE Vite's internal middlewares.
+			 * Route-owning middleware must run before Vite's HTML fallback
+			 * middleware, which otherwise intercepts non-file GET requests
+			 * and serves index.html.
+			 *
+			 * Config loading is deferred until the first incoming request so
+			 * that `vite.ssrLoadModule` is guaranteed to be fully initialised.
+			 *
 			 * @param {ViteDevServer} vite
 			 */
 			configureServer(vite) {
-				// Return a function to be called after Vite's internal middlewares
-				return async () => {
-					if (!rippleConfigExists(root)) return;
+				// Deferred config initialisation — resolved on first request
+				// that finds a ripple.config.ts. The promise is cleared after
+				// every attempt so that "config missing" is never cached
+				// permanently (the user may create the file while the dev
+				// server is running).
+				/** @type {Promise<void> | null} */
+				let initPromise = null;
+				/** @type {number} */
+				let lastConfigErrorMtimeMs = 0;
 
-					try {
-						rippleConfig = await loadRippleConfig(root, { vite });
+				/**
+				 * Ensure ripple.config.ts has been loaded and the router is
+				 * ready. Safe to call on every request — a successful load
+				 * (even with no routes) is short-circuited, a missing config
+				 * file is retried on the next request, and load errors are
+				 * only retried when the file has been modified.
+				 */
+				async function ensureConfigLoaded() {
+					// Config and router are already loaded.
+					if (rippleConfig && router) return;
 
-						if (!has_route_config(rippleConfig)) {
+					if (initPromise) {
+						await initPromise;
+						return;
+					}
+
+					const configPath = getRippleConfigPath(root);
+
+					// Config file doesn't exist (yet). Don't cache this — the
+					// user may create it while the dev server is running.
+					if (!rippleConfigExists(root)) return;
+
+					// After a load error, only retry if the file has been
+					// modified since the last failure. This avoids per-request
+					// log spam while instantly picking up fixes.
+					if (lastConfigErrorMtimeMs) {
+						try {
+							const stat = fs.statSync(configPath);
+							if (stat.mtimeMs <= lastConfigErrorMtimeMs) return;
+						} catch {
 							return;
 						}
+					}
+
+					if (!initPromise) {
+						// Snapshot mtime before loading into a local variable.
+						// Only promoted to lastConfigErrorMtimeMs if the load
+						// actually fails — this prevents concurrent requests
+						// during a normal first load from seeing a non-zero
+						// lastConfigErrorMtimeMs and short-circuiting above.
+						let preLoadMtimeMs;
+						try {
+							preLoadMtimeMs = fs.statSync(configPath).mtimeMs;
+						} catch {
+							preLoadMtimeMs = Date.now();
+						}
 
-						// Create router from config
-						router = createRouter(rippleConfig.router.routes);
-						console.log(
-							`[@ripple-ts/vite-plugin] Loaded ${rippleConfig.router.routes.length} routes from ripple.config.ts`,
-						);
-					} catch (error) {
-						console.error('[@ripple-ts/vite-plugin] Failed to load ripple.config.ts:', error);
-						return;
+						initPromise = (async () => {
+							const nextConfig = await loadRippleConfig(root, { vite });
+
+							let nextRouter = null;
+							if (has_route_config(nextConfig)) {
+								nextRouter = createRouter(nextConfig.router.routes);
+							}
+
+							rippleConfig = nextConfig;
+							router = nextRouter;
+
+							if (nextRouter) {
+								console.log(
+									`[@ripple-ts/vite-plugin] Loaded ${nextConfig.router.routes.length} routes from ripple.config.ts`,
+								);
+							}
+						})()
+							.catch((error) => {
+								// Record pre-load mtime so retries only happen
+								// when the file has been modified.
+								lastConfigErrorMtimeMs = preLoadMtimeMs;
+								throw error;
+							})
+							.finally(() => {
+								initPromise = null;
+							});
 					}
 
-					// Add SSR middleware
-					vite.middlewares.use((req, res, next) => {
-						// Handle async logic in an IIFE
-						(async () => {
-							// Skip if no router
-							if (!router || !rippleConfig) {
-								next();
-								return;
+					await initPromise;
+				}
+
+				// Pre-hook: register middleware directly without returning a
+				// function, so it is inserted BEFORE Vite's built-in stack.
+				vite.middlewares.use(function rippleDevMiddleware(req, res, next) {
+					// Handle async logic in an IIFE
+					(async () => {
+						// Lazy-load ripple.config.ts. This is deferred to the
+						// first request because vite.ssrLoadModule may not be
+						// fully initialised when configureServer runs.
+						try {
+							await ensureConfigLoaded();
+						} catch (error) {
+							// Log but do NOT return a 500 — falling through to
+							// next() lets Vite continue serving its own internal
+							// requests (HMR, CSS, JS modules, etc.). A broken
+							// ripple.config.ts should not kill the entire dev
+							// server. The error is retried on the next request
+							// because ensureConfigLoaded clears initPromise.
+							vite.ssrFixStacktrace(/** @type {Error} */ (error));
+							console.error('[@ripple-ts/vite-plugin] Failed to load ripple.config.ts:', error);
+							next();
+							return;
+						}
+
+						// Skip if no router
+						if (!router || !rippleConfig) {
+							next();
+							return;
+						}
+
+						const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+						const method = req.method || 'GET';
+
+						// Handle RPC requests for #server blocks
+						if (is_rpc_request(url.pathname)) {
+							await handleRpcRequest(req, res, vite, rippleConfig.server.trustProxy, rippleConfig);
+							return;
+						}
+
+						// Match route
+						const match = router.match(method, url.pathname);
+
+						if (!match) {
+							next();
+							return;
+						}
+
+						try {
+							// Reload config to get fresh routes (for HMR)
+							const previousRoutes = rippleConfig.router.routes;
+							const freshConfig = await loadRippleConfig(root, { vite });
+							if (freshConfig) {
+								rippleConfig = freshConfig;
 							}
 
-							const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
-							const method = req.method || 'GET';
-
-							// Handle RPC requests for #server blocks
-							if (is_rpc_request(url.pathname)) {
-								await handleRpcRequest(
-									req,
-									res,
-									vite,
-									rippleConfig.server.trustProxy,
-									rippleConfig,
+							// Check if routes have changed
+							if (JSON.stringify(previousRoutes) !== JSON.stringify(rippleConfig.router.routes)) {
+								console.log(
+									`[@ripple-ts/vite-plugin] Detected route changes. Re-loading ${rippleConfig.router.routes.length} routes from ripple.config.ts`,
 								);
-								return;
 							}
 
-							// Match route
-							const match = router.match(method, url.pathname);
+							router = createRouter(rippleConfig.router.routes);
 
-							if (!match) {
+							// Re-match with fresh router
+							const freshMatch = router.match(method, url.pathname);
+							if (!freshMatch) {
 								next();
 								return;
 							}
 
-							try {
-								// Reload config to get fresh routes (for HMR)
-								const previousRoutes = rippleConfig.router.routes;
-								const freshConfig = await loadRippleConfig(root, { vite });
-								if (freshConfig) {
-									rippleConfig = freshConfig;
-								}
-
-								// Check if routes have changed
-								if (JSON.stringify(previousRoutes) !== JSON.stringify(rippleConfig.router.routes)) {
-									console.log(
-										`[@ripple-ts/vite-plugin] Detected route changes. Re-loading ${rippleConfig.router.routes.length} routes from ripple.config.ts`,
-									);
-								}
-
-								router = createRouter(rippleConfig.router.routes);
-
-								// Re-match with fresh router
-								const freshMatch = router.match(method, url.pathname);
-								if (!freshMatch) {
-									next();
-									return;
-								}
-
-								// Create context
-								const request = nodeRequestToWebRequest(req);
-								const context = createContext(request, freshMatch.params);
-
-								const globalMiddlewares = rippleConfig.middlewares;
-
-								let response;
-
-								if (freshMatch.route.type === 'render') {
-									// Handle RenderRoute with global middlewares
-									response = await runMiddlewareChain(
-										context,
-										globalMiddlewares,
-										freshMatch.route.before || [],
-										async () =>
-											handleRenderRoute(
-												/** @type {RenderRoute} */ (freshMatch.route),
-												context,
-												vite,
-											),
-										[],
-									);
-								} else {
-									// Handle ServerRoute
-									response = await handleServerRoute(freshMatch.route, context, globalMiddlewares);
-								}
-
-								// Send response
-								await sendWebResponse(res, response);
-							} catch (error) {
-								console.error('[@ripple-ts/vite-plugin] Request error:', error);
-								vite.ssrFixStacktrace(/** @type {Error} */ (error));
-
-								res.statusCode = 500;
-								res.setHeader('Content-Type', 'text/html');
-								res.end(
-									`<pre style="color: red; background: #1a1a1a; padding: 2rem; margin: 0;">${escapeHtml(
-										error instanceof Error ? error.stack || error.message : String(error),
-									)}</pre>`,
+							// Create context
+							const request = nodeRequestToWebRequest(req);
+							const context = createContext(request, freshMatch.params);
+
+							const globalMiddlewares = rippleConfig.middlewares;
+
+							let response;
+
+							if (freshMatch.route.type === 'render') {
+								// Handle RenderRoute with global middlewares
+								response = await runMiddlewareChain(
+									context,
+									globalMiddlewares,
+									freshMatch.route.before || [],
+									async () =>
+										handleRenderRoute(/** @type {RenderRoute} */ (freshMatch.route), context, vite),
+									[],
 								);
+							} else {
+								// Handle ServerRoute
+								response = await handleServerRoute(freshMatch.route, context, globalMiddlewares);
 							}
-						})().catch((err) => {
-							console.error('[@ripple-ts/vite-plugin] Unhandled middleware error:', err);
-							if (!res.headersSent) {
-								res.statusCode = 500;
-								res.end('Internal Server Error');
-							}
-						});
+
+							// Send response
+							await sendWebResponse(res, response);
+						} catch (error) {
+							console.error('[@ripple-ts/vite-plugin] Request error:', error);
+							vite.ssrFixStacktrace(/** @type {Error} */ (error));
+
+							res.statusCode = 500;
+							res.setHeader('Content-Type', 'text/html');
+							res.end(
+								`<pre style="color: red; background: #1a1a1a; padding: 2rem; margin: 0;">${escapeHtml(
+									error instanceof Error ? error.stack || error.message : String(error),
+								)}</pre>`,
+							);
+						}
+					})().catch((err) => {
+						console.error('[@ripple-ts/vite-plugin] Unhandled middleware error:', err);
+						if (!res.headersSent) {
+							res.statusCode = 500;
+							res.end('Internal Server Error');
+						}
 					});
-				};
+				});
+				// No return — pre-hook ensures middleware runs before
+				// viteHtmlFallbackMiddleware
 			},
 
 			/**

package/tests/configure-server.test.js

@@ -0,0 +1,288 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { ripple } from '@ripple-ts/vite-plugin';
+import { createServer } from 'vite';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+
+/**
+ * Tests for configureServer middleware ordering.
+ *
+ * Ripple's SSR/API middleware is route-owning middleware. It must be
+ * registered as a pre-hook (no return value from configureServer) so
+ * it runs before Vite's HTML fallback middleware, which otherwise
+ * intercepts non-file GET requests and serves index.html.
+ */
+describe('configureServer middleware ordering', () => {
+	/**
+	 * Get the main ripple plugin from the plugin array.
+	 * @returns {{ plugin: import('vite').Plugin, plugins: import('vite').Plugin[] }}
+	 */
+	function getPlugins() {
+		const plugins = ripple({ excludeRippleExternalModules: true });
+		const plugin = plugins.find((p) => p.name === 'vite-plugin-ripple');
+		if (!plugin) throw new Error('vite-plugin-ripple not found in plugin array');
+		return { plugin, plugins };
+	}
+
+	/**
+	 * Create a mock ViteDevServer with just enough surface for configureServer.
+	 */
+	function createMockVite() {
+		/** @type {Function[]} */
+		const registeredMiddlewares = [];
+		return {
+			middlewares: {
+				use: vi.fn((/** @type {Function} */ fn) => {
+					registeredMiddlewares.push(fn);
+				}),
+			},
+			registeredMiddlewares,
+			ssrLoadModule: vi.fn(),
+			ssrFixStacktrace: vi.fn(),
+			environments: {},
+		};
+	}
+
+	/**
+	 * Call configResolved on the plugin to set up `root` and `config`.
+	 * @param {import('vite').Plugin} plugin
+	 */
+	async function initPlugin(plugin) {
+		if (typeof plugin.configResolved === 'function') {
+			await plugin.configResolved(
+				/** @type {any} */ ({
+					root: '/nonexistent-test-root',
+					command: 'serve',
+				}),
+			);
+		}
+	}
+
+	// --- Unit tests (mocked Vite) ---
+
+	it('uses a pre-hook — configureServer does NOT return a function', async () => {
+		const { plugin } = getPlugins();
+		const mockVite = createMockVite();
+
+		await initPlugin(plugin);
+
+		const result = plugin.configureServer(/** @type {any} */ (mockVite));
+
+		// A post-hook returns a function (or async function).
+		// A pre-hook returns undefined (void).
+		expect(result).toBeUndefined();
+	});
+
+	it('registers middleware synchronously inside configureServer', async () => {
+		const { plugin } = getPlugins();
+		const mockVite = createMockVite();
+
+		await initPlugin(plugin);
+
+		plugin.configureServer(/** @type {any} */ (mockVite));
+
+		expect(mockVite.middlewares.use).toHaveBeenCalledTimes(1);
+		expect(mockVite.registeredMiddlewares).toHaveLength(1);
+		expect(typeof mockVite.registeredMiddlewares[0]).toBe('function');
+	});
+
+	it('middleware calls next() when no ripple config exists', async () => {
+		const { plugin } = getPlugins();
+		const mockVite = createMockVite();
+
+		await initPlugin(plugin);
+
+		plugin.configureServer(/** @type {any} */ (mockVite));
+
+		const middleware = mockVite.registeredMiddlewares[0];
+		expect(middleware).toBeDefined();
+
+		/** @type {ReturnType<typeof vi.fn>} */
+		let next;
+		const nextCalled = new Promise((resolve) => {
+			next = vi.fn(() => resolve(undefined));
+
+			const req = /** @type {any} */ ({
+				url: '/api/test',
+				method: 'GET',
+				headers: { host: 'localhost' },
+			});
+
+			const res = /** @type {any} */ ({
+				statusCode: 200,
+				headersSent: false,
+				setHeader: vi.fn(),
+				end: vi.fn(),
+			});
+
+			middleware(req, res, next);
+		});
+
+		await nextCalled;
+
+		// @ts-ignore — next is assigned inside the Promise constructor
+		expect(next).toHaveBeenCalledTimes(1);
+	});
+
+	it('ripple middleware is registered before a simulated html fallback', async () => {
+		const { plugin } = getPlugins();
+		/** @type {Function[]} */
+		const stack = [];
+
+		const mockVite = /** @type {any} */ ({
+			middlewares: {
+				use: vi.fn((/** @type {Function} */ fn) => {
+					stack.push(fn);
+				}),
+			},
+			ssrLoadModule: vi.fn(),
+			ssrFixStacktrace: vi.fn(),
+			environments: {},
+		});
+
+		await initPlugin(plugin);
+
+		const returnValue = plugin.configureServer(mockVite);
+
+		// Our middleware should already be registered (pre-hook)
+		expect(stack).toHaveLength(1);
+
+		// Simulate Vite adding its internal html fallback AFTER configureServer
+		const htmlFallback = (
+			/** @type {any} */ req,
+			/** @type {any} */ res,
+			/** @type {any} */ _next,
+		) => {
+			res.setHeader('Content-Type', 'text/html');
+			res.end('<html>fallback</html>');
+		};
+		stack.push(htmlFallback);
+
+		// Ripple middleware is at index 0, html fallback is at index 1
+		expect(stack[0]).not.toBe(htmlFallback);
+		expect(stack[1]).toBe(htmlFallback);
+
+		if (typeof returnValue === 'function') {
+			throw new Error(
+				'configureServer returned a function — this is a post-hook pattern ' +
+					'which places middleware AFTER viteHtmlFallbackMiddleware. ' +
+					'SSR/API routes will be unreachable.',
+			);
+		}
+	});
+
+	// --- Integration tests (real Vite dev server) ---
+
+	/** @type {import('vite').ViteDevServer | null} */
+	let server = null;
+
+	afterEach(async () => {
+		if (server) {
+			await server.close();
+			server = null;
+		}
+	});
+
+	it('middleware is ordered before html fallback in a real Vite server', async () => {
+		const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ripple-vite-test-'));
+		fs.writeFileSync(path.join(tmpDir, 'index.html'), '<html><body></body></html>');
+
+		try {
+			server = await createServer({
+				root: tmpDir,
+				configFile: false,
+				plugins: [ripple({ excludeRippleExternalModules: true })],
+				server: { middlewareMode: true },
+				logLevel: 'silent',
+			});
+
+			const stack = server.middlewares.stack;
+
+			const rippleIndex = stack.findIndex((/** @type {any} */ layer) => {
+				const name = layer.handle?.name || layer.name || '';
+				return name === 'rippleDevMiddleware';
+			});
+
+			const htmlFallbackIndex = stack.findIndex((/** @type {any} */ layer) => {
+				const name = layer.handle?.name || layer.name || '';
+				return name.includes('htmlFallback') || name.includes('HtmlFallback');
+			});
+
+			// Our middleware must exist in the stack
+			expect(rippleIndex).toBeGreaterThanOrEqual(0);
+
+			// If Vite has an HTML fallback, our middleware must come before it
+			if (htmlFallbackIndex !== -1) {
+				expect(rippleIndex).toBeLessThan(htmlFallbackIndex);
+			}
+		} finally {
+			fs.rmSync(tmpDir, { recursive: true, force: true });
+		}
+	});
+
+	it('non-ripple requests pass through to next middleware', async () => {
+		const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ripple-vite-test-'));
+		fs.writeFileSync(path.join(tmpDir, 'index.html'), '<html><body>hello</body></html>');
+
+		try {
+			server = await createServer({
+				root: tmpDir,
+				configFile: false,
+				plugins: [ripple({ excludeRippleExternalModules: true })],
+				server: { middlewareMode: true },
+				logLevel: 'silent',
+			});
+
+			const response = await new Promise((resolve) => {
+				const req = /** @type {any} */ ({
+					url: '/',
+					method: 'GET',
+					headers: { host: 'localhost', accept: 'text/html' },
+					on: () => {},
+					removeListener: () => {},
+				});
+
+				const chunks = [];
+				const res = /** @type {any} */ ({
+					statusCode: 200,
+					headersSent: false,
+					_headers: {},
+					setHeader(key, val) {
+						this._headers[key] = val;
+					},
+					getHeader(key) {
+						return this._headers[key];
+					},
+					writeHead(status, headers) {
+						this.statusCode = status;
+						if (headers) Object.assign(this._headers, headers);
+					},
+					write(chunk) {
+						chunks.push(chunk);
+					},
+					end(chunk) {
+						if (chunk) chunks.push(chunk);
+						resolve({
+							statusCode: this.statusCode,
+							headers: this._headers,
+							body: Buffer.concat(
+								chunks.map((c) => (typeof c === 'string' ? Buffer.from(c) : c)),
+							).toString(),
+						});
+					},
+					on: () => {},
+					removeListener: () => {},
+				});
+
+				server.middlewares.handle(req, res);
+			});
+
+			// Ripple middleware passed through and Vite handled the request
+			expect(response.statusCode).toBe(200);
+			expect(response.body).toContain('hello');
+		} finally {
+			fs.rmSync(tmpDir, { recursive: true, force: true });
+		}
+	});
+});

package/types/index.d.ts

@@ -1,212 +1,210 @@
 import type { Plugin, BuildEnvironmentOptions, ViteDevServer } from 'vite';
 import type { RuntimePrimitives } from '@ripple-ts/adapter';
 
-declare module '@ripple-ts/vite-plugin' {
-	// ============================================================================
-	// Plugin exports
-	// ============================================================================
-
-	export function ripple(options?: RipplePluginOptions): Plugin[];
-	export function defineConfig(options: RippleConfigOptions): RippleConfigOptions;
-	export function resolveRippleConfig(
-		raw: RippleConfigOptions,
-		options?: { requireAdapter?: boolean },
-	): ResolvedRippleConfig;
-	export function getRippleConfigPath(projectRoot: string): string;
-	export function rippleConfigExists(projectRoot: string): boolean;
-	export function loadRippleConfig(
-		projectRoot: string,
-		options?: { vite?: ViteDevServer; requireAdapter?: boolean },
-	): Promise<ResolvedRippleConfig>;
-
-	// ============================================================================
-	// Route classes
-	// ============================================================================
-
-	export class RenderRoute {
-		readonly type: 'render';
-		path: string;
-		entry: string;
-		layout?: string;
-		before: Middleware[];
-		constructor(options: RenderRouteOptions);
-	}
-
-	export class ServerRoute {
-		readonly type: 'server';
-		path: string;
-		methods: string[];
-		handler: RouteHandler;
-		before: Middleware[];
-		after: Middleware[];
-		constructor(options: ServerRouteOptions);
-	}
-
-	export type Route = RenderRoute | ServerRoute;
-
-	// ============================================================================
-	// Route options
-	// ============================================================================
-
-	export interface RenderRouteOptions {
-		/** URL path pattern (e.g., '/', '/posts/:id', '/docs/*slug') */
-		path: string;
-		/** Path to the Ripple component entry file */
-		entry: string;
-		/** Path to the layout component (wraps the entry) */
-		layout?: string;
-		/** Middleware to run before rendering */
-		before?: Middleware[];
-	}
-
-	export interface ServerRouteOptions {
-		/** URL path pattern (e.g., '/api/hello', '/api/posts/:id') */
-		path: string;
-		/** HTTP methods to handle (default: ['GET']) */
-		methods?: string[];
-		/** Request handler that returns a Response */
-		handler: RouteHandler;
-		/** Middleware to run before the handler */
-		before?: Middleware[];
-		/** Middleware to run after the handler */
-		after?: Middleware[];
-	}
-
-	// ============================================================================
-	// Context and middleware
-	// ============================================================================
-
-	export interface Context {
-		/** The incoming Request object */
-		request: Request;
-		/** URL parameters extracted from the route pattern */
-		params: Record<string, string>;
-		/** Parsed URL object */
-		url: URL;
-		/** Shared state for passing data between middlewares */
-		state: Map<string, unknown>;
-	}
-
-	export type NextFunction = () => Promise<Response>;
-	export type Middleware = (context: Context, next: NextFunction) => Response | Promise<Response>;
-	export type RouteHandler = (context: Context) => Response | Promise<Response>;
-
-	// ============================================================================
-	// Configuration
-	// ============================================================================
-
-	export interface RipplePluginOptions {
-		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' */
-			outDir?: string;
-			minify?: boolean;
-			target?: BuildEnvironmentOptions['target'];
-		};
-		adapter?: {
-			serve: AdapterServeFunction;
-			/**
-			 * Platform-specific runtime primitives provided by the adapter.
-			 *
-			 * These allow the server runtime to operate without depending
-			 * on Node.js-specific APIs like `node:crypto` or `node:async_hooks`.
-			 *
-			 * Required for production builds. In development, the vite plugin
-			 * falls back to Node.js defaults if not provided.
-			 */
-			runtime: RuntimePrimitives;
-		};
-		router?: {
-			routes: Route[];
-		};
-		/** Global middlewares applied to all routes */
-		middlewares?: Middleware[];
+// ============================================================================
+// Plugin exports
+// ============================================================================
+
+export function ripple(options?: RipplePluginOptions): Plugin[];
+export function defineConfig(options: RippleConfigOptions): RippleConfigOptions;
+export function resolveRippleConfig(
+	raw: RippleConfigOptions,
+	options?: { requireAdapter?: boolean },
+): ResolvedRippleConfig;
+export function getRippleConfigPath(projectRoot: string): string;
+export function rippleConfigExists(projectRoot: string): boolean;
+export function loadRippleConfig(
+	projectRoot: string,
+	options?: { vite?: ViteDevServer; requireAdapter?: boolean },
+): Promise<ResolvedRippleConfig>;
+
+// ============================================================================
+// Route classes
+// ============================================================================
+
+export class RenderRoute {
+	readonly type: 'render';
+	path: string;
+	entry: string;
+	layout?: string;
+	before: Middleware[];
+	constructor(options: RenderRouteOptions);
+}
+
+export class ServerRoute {
+	readonly type: 'server';
+	path: string;
+	methods: string[];
+	handler: RouteHandler;
+	before: Middleware[];
+	after: Middleware[];
+	constructor(options: ServerRouteOptions);
+}
+
+export type Route = RenderRoute | ServerRoute;
+
+// ============================================================================
+// Route options
+// ============================================================================
+
+export interface RenderRouteOptions {
+	/** URL path pattern (e.g., '/', '/posts/:id', '/docs/*slug') */
+	path: string;
+	/** Path to the Ripple component entry file */
+	entry: string;
+	/** Path to the layout component (wraps the entry) */
+	layout?: string;
+	/** Middleware to run before rendering */
+	before?: Middleware[];
+}
+
+export interface ServerRouteOptions {
+	/** URL path pattern (e.g., '/api/hello', '/api/posts/:id') */
+	path: string;
+	/** HTTP methods to handle (default: ['GET']) */
+	methods?: string[];
+	/** Request handler that returns a Response */
+	handler: RouteHandler;
+	/** Middleware to run before the handler */
+	before?: Middleware[];
+	/** Middleware to run after the handler */
+	after?: Middleware[];
+}
+
+// ============================================================================
+// Context and middleware
+// ============================================================================
+
+export interface Context {
+	/** The incoming Request object */
+	request: Request;
+	/** URL parameters extracted from the route pattern */
+	params: Record<string, string>;
+	/** Parsed URL object */
+	url: URL;
+	/** Shared state for passing data between middlewares */
+	state: Map<string, unknown>;
+}
+
+export type NextFunction = () => Promise<Response>;
+export type Middleware = (context: Context, next: NextFunction) => Response | Promise<Response>;
+export type RouteHandler = (context: Context) => Response | Promise<Response>;
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+export interface RipplePluginOptions {
+	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' */
+		outDir?: string;
+		minify?: boolean;
+		target?: BuildEnvironmentOptions['target'];
+	};
+	adapter?: {
+		serve: AdapterServeFunction;
 		/**
-		 * Client-side TSX compat integrations keyed by kind, e.g. `react` for `<tsx:react>`.
+		 * Platform-specific runtime primitives provided by the adapter.
 		 *
-		 * You can either pass a descriptor object or import a compat factory directly,
-		 * as long as that factory export carries Ripple compat metadata.
+		 * These allow the server runtime to operate without depending
+		 * on Node.js-specific APIs like `node:crypto` or `node:async_hooks`.
 		 *
-		 * These are compiled into a browser-side compat registry by the Vite plugin,
-		 * allowing `mount()` / `hydrate()` to pick them up automatically.
+		 * Required for production builds. In development, the vite plugin
+		 * falls back to Node.js defaults if not provided.
 		 */
-		compat?: CompatConfig;
-		platform?: {
-			env: Record<string, string>;
-		};
-		server?: {
-			/**
-			 * Whether to trust `X-Forwarded-Proto` and `X-Forwarded-Host` headers
-			 * when deriving the request origin (protocol + host).
-			 *
-			 * Enable this only when the application is behind a trusted reverse proxy
-			 * (e.g., nginx, Cloudflare, AWS ALB). When `false` (the default), the
-			 * protocol is inferred from the socket and the host from the `Host` header.
-			 *
-			 * @default false
-			 */
-			trustProxy?: boolean;
-		};
-	}
-
+		runtime: RuntimePrimitives;
+	};
+	router?: {
+		routes: Route[];
+	};
+	/** Global middlewares applied to all routes */
+	middlewares?: Middleware[];
 	/**
-	 * Resolved configuration with all defaults applied.
-	 * Returned by `resolveRippleConfig` and `loadRippleConfig`.
-	 * Consumers should use this type instead of applying ad-hoc defaults.
+	 * 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.
 	 */
-	export interface ResolvedRippleConfig {
-		build: {
-			/** @default 'dist' */
-			outDir: string;
-			minify?: boolean;
-			target?: BuildEnvironmentOptions['target'];
-		};
-		adapter?: {
-			serve: AdapterServeFunction;
-			runtime: RuntimePrimitives;
-		};
-		router: {
-			routes: Route[];
-		};
-		/** @default [] */
-		middlewares: Middleware[];
+	compat?: CompatConfig;
+	platform?: {
+		env: Record<string, string>;
+	};
+	server?: {
+		/**
+		 * Whether to trust `X-Forwarded-Proto` and `X-Forwarded-Host` headers
+		 * when deriving the request origin (protocol + host).
+		 *
+		 * Enable this only when the application is behind a trusted reverse proxy
+		 * (e.g., nginx, Cloudflare, AWS ALB). When `false` (the default), the
+		 * protocol is inferred from the socket and the host from the `Host` header.
+		 *
+		 * @default false
+		 */
+		trustProxy?: boolean;
+	};
+}
+
+/**
+ * Resolved configuration with all defaults applied.
+ * Returned by `resolveRippleConfig` and `loadRippleConfig`.
+ * Consumers should use this type instead of applying ad-hoc defaults.
+ */
+export interface ResolvedRippleConfig {
+	build: {
+		/** @default 'dist' */
+		outDir: string;
+		minify?: boolean;
+		target?: BuildEnvironmentOptions['target'];
+	};
+	adapter?: {
+		serve: AdapterServeFunction;
+		runtime: RuntimePrimitives;
+	};
+	router: {
+		routes: Route[];
+	};
+	/** @default [] */
+	middlewares: Middleware[];
+	/** @default {} */
+	compat: Record<string, CompatFactoryConfig>;
+	platform: {
 		/** @default {} */
-		compat: Record<string, CompatFactoryConfig>;
-		platform: {
-			/** @default {} */
-			env: Record<string, string>;
-		};
-		server: {
-			/** @default false */
-			trustProxy: boolean;
-		};
-	}
-
-	export type AdapterServeFunction = (
-		handler: (request: Request, platform?: unknown) => Response | Promise<Response>,
-		options?: Record<string, unknown>,
-	) => { listen: (port?: number) => unknown; close: () => void };
+		env: Record<string, string>;
+	};
+	server: {
+		/** @default false */
+		trustProxy: boolean;
+	};
 }
+
+export type AdapterServeFunction = (
+	handler: (request: Request, platform?: unknown) => Response | Promise<Response>,
+	options?: Record<string, unknown>,
+) => { listen: (port?: number) => unknown; close: () => void };