@octanejs/vite-plugin 0.1.3 → 0.1.4

package/tests/production.test.ts

@@ -0,0 +1,157 @@
+// Production SSR build — end-to-end over the fixture app (tests/_fixtures/app):
+// `vite build` must produce BOTH bundles (dist/client assets + the
+// self-contained dist/server/entry.js), and the server bundle's handler must
+// render a route with hydratable output whose body region and #__octane_data
+// payload BYTE-MATCH dev SSR for the same request — that is the contract that
+// lets hydrateRoot adopt production responses exactly like dev ones.
+//
+// The fixture has no installed node_modules (it is not a workspace package);
+// the setup symlinks the workspace's octane / @octanejs/vite-plugin / vite in,
+// which is exactly what a pnpm install would produce.
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { build, createServer, type ViteDevServer } from 'vite';
+
+const fixtureRoot = fileURLToPath(new URL('./_fixtures/app', import.meta.url));
+const packageRoot = fileURLToPath(new URL('../', import.meta.url));
+const repoRoot = path.resolve(packageRoot, '../..');
+const distDir = path.join(fixtureRoot, 'dist');
+
+function linkPackage(name: string, target: string) {
+	const dest = path.join(fixtureRoot, 'node_modules', name);
+	fs.mkdirSync(path.dirname(dest), { recursive: true });
+	fs.rmSync(dest, { recursive: true, force: true });
+	fs.symlinkSync(target, dest, 'dir');
+}
+
+/** The rendered body region: everything streamed into `<div id="root">`. */
+function bodyRegionOf(html: string): string {
+	const open = '<div id="root">';
+	const start = html.indexOf(open);
+	const end = html.lastIndexOf('</div>');
+	expect(start).toBeGreaterThan(-1);
+	expect(end).toBeGreaterThan(start);
+	return html.slice(start + open.length, end);
+}
+
+function dataScriptOf(html: string): string {
+	const match = html.match(/<script id="__octane_data" type="application\/json">(.*?)<\/script>/s);
+	expect(match).not.toBeNull();
+	return match![1];
+}
+
+let devServer: ViteDevServer | null = null;
+let devOrigin = '';
+
+beforeAll(async () => {
+	linkPackage('octane', path.join(repoRoot, 'packages/octane'));
+	linkPackage('@octanejs/vite-plugin', packageRoot);
+	linkPackage('vite', path.join(packageRoot, 'node_modules/vite'));
+
+	fs.rmSync(distDir, { recursive: true, force: true });
+
+	// The production build: client bundle, then (closeBundle) the server bundle.
+	await build({ root: fixtureRoot, logLevel: 'silent' });
+
+	// A dev server on a random port — the byte-compat oracle.
+	devServer = await createServer({
+		root: fixtureRoot,
+		logLevel: 'silent',
+		server: { port: 0 },
+	});
+	await devServer.listen();
+	const address = devServer.httpServer?.address();
+	if (!address || typeof address !== 'object') throw new Error('dev server has no address');
+	devOrigin = `http://localhost:${address.port}`;
+}, 180_000);
+
+afterAll(async () => {
+	await devServer?.close();
+	fs.rmSync(distDir, { recursive: true, force: true });
+	fs.rmSync(path.join(fixtureRoot, 'node_modules'), { recursive: true, force: true });
+});
+
+describe('production SSR build', () => {
+	it('emits both bundles, moves the template to dist/server, and strips build metadata', () => {
+		expect(fs.existsSync(path.join(distDir, 'server/entry.js'))).toBe(true);
+		expect(fs.existsSync(path.join(distDir, 'server/index.html'))).toBe(true);
+		// The template must NOT stay in the static dir (it would shadow SSR at '/'
+		// on filesystem-first hosts) and the manifest must not ship.
+		expect(fs.existsSync(path.join(distDir, 'client/index.html'))).toBe(false);
+		expect(fs.existsSync(path.join(distDir, 'client/.vite'))).toBe(false);
+		// The client build produced hashed assets, including the hydrate entry
+		// referenced by the moved template.
+		const template = fs.readFileSync(path.join(distDir, 'server/index.html'), 'utf-8');
+		const scriptSrc = template.match(/<script type="module"[^>]*src="(\/assets\/[^"]+)"/)?.[1];
+		expect(scriptSrc).toBeTruthy();
+		expect(fs.existsSync(path.join(distDir, 'client', scriptSrc!))).toBe(true);
+		// The SSR placeholders survived the client build untouched.
+		expect(template).toContain('<!--ssr-head-->');
+		expect(template).toContain('<!--ssr-body-->');
+	});
+
+	it('the server bundle is self-contained (imports only node builtins)', () => {
+		const entry = fs.readFileSync(path.join(distDir, 'server/entry.js'), 'utf-8');
+		const specifiers = [...entry.matchAll(/^import[^'"]*['"]([^'"]+)['"]/gm)].map((m) => m[1]);
+		expect(specifiers.length).toBeGreaterThan(0);
+		for (const spec of specifiers) {
+			expect(spec.startsWith('node:'), `unexpected external import: ${spec}`).toBe(true);
+		}
+	});
+
+	it('renders a route through the built handler, byte-matching dev SSR', async () => {
+		const { handler } = await import(pathToFileURL(path.join(distDir, 'server/entry.js')).href);
+
+		for (const url of ['/', '/pages/hello']) {
+			const prodResponse = await handler(new Request(`http://localhost${url}`));
+			expect(prodResponse.status).toBe(200);
+			expect(prodResponse.headers.get('content-type')).toBe('text/html; charset=utf-8');
+			const prodHtml = await prodResponse.text();
+
+			const devResponse = await fetch(`${devOrigin}${url}`);
+			expect(devResponse.status).toBe(200);
+			const devHtml = await devResponse.text();
+
+			// The hydratable body region and the hydration payload are the
+			// byte-compat contract between dev and production.
+			expect(bodyRegionOf(prodHtml)).toBe(bodyRegionOf(devHtml));
+			expect(dataScriptOf(prodHtml)).toBe(dataScriptOf(devHtml));
+
+			// Sanity: it actually rendered the page.
+			expect(prodHtml).toContain('fixture-nav');
+			expect(prodHtml).toContain(url === '/' ? 'Fixture page home' : 'Fixture page hello');
+			expect(prodHtml).toContain(`<p class="url">${url}</p>`);
+		}
+	});
+
+	it('returns 404 for unmatched routes (no catch-all in the fixture)', async () => {
+		const { handler } = await import(pathToFileURL(path.join(distDir, 'server/entry.js')).href);
+		const response = await handler(new Request('http://localhost/nope/nothing'));
+		expect(response.status).toBe(404);
+	});
+
+	it('nodeHandler bridges the same handler for Node-style serverless wrappers', async () => {
+		const { nodeHandler } = await import(pathToFileURL(path.join(distDir, 'server/entry.js')).href);
+		const chunks: Buffer[] = [];
+		const headers: Record<string, unknown> = {};
+		const res = {
+			statusCode: 0,
+			headersSent: false,
+			setHeader(key: string, value: unknown) {
+				headers[key.toLowerCase()] = value;
+			},
+			write(chunk: Uint8Array) {
+				chunks.push(Buffer.from(chunk));
+			},
+			end(chunk?: Uint8Array) {
+				if (chunk) chunks.push(Buffer.from(chunk));
+			},
+		};
+		await nodeHandler({ method: 'GET', url: '/pages/node', headers: { host: 'localhost' } }, res);
+		expect(res.statusCode).toBe(200);
+		expect(headers['content-type']).toBe('text/html; charset=utf-8');
+		expect(Buffer.concat(chunks).toString('utf-8')).toContain('Fixture page node');
+	});
+});

package/tsconfig.typecheck.json

@@ -13,6 +13,6 @@
     "allowJs": true,
     "checkJs": false
   },
-  "include": ["src/**/*", "types/**/*"],
-  "exclude": ["node_modules", "dist", "tests"]
+  "include": ["src/**/*", "types/**/*", "tests/**/*.ts"],
+  "exclude": ["node_modules", "dist", "tests/_fixtures"]
 }

package/types/index.d.ts

@@ -8,6 +8,15 @@ import type { RuntimePrimitives } from '@ripple-ts/adapter';
 export interface OctanePluginOptions {
 	/** Override the client HMR default (on in serve mode, off for SSR). */
 	hmr?: boolean;
+	/**
+	 * Path fragments the compiler's plain `.ts`/`.js` hook-slotting pass must
+	 * skip — hand-slot-forwarding library sources that would otherwise be
+	 * double-slotted. Published bindings live in node_modules and are skipped
+	 * automatically; set this for monorepo / aliased-to-source setups where
+	 * pnpm symlinks resolve `@octanejs/*` imports to `packages/*\/src` paths
+	 * (e.g. `['/packages/tanstack-router/src/']`).
+	 */
+	exclude?: string[];
 }
 
 /**
@@ -16,6 +25,18 @@ export interface OctanePluginOptions {
  * config / routing / dev SSR / hydrate.
  */
 export function octane(options?: OctanePluginOptions): Plugin[];
+
+/**
+ * Is this a request the Vite dev server owns (module / asset / internal
+ * namespace / transform query), as opposed to a page navigation? The dev SSR
+ * middleware uses it so a catch-all RenderRoute never swallows Vite requests.
+ *
+ * `fileRoots` (the Vite root + publicDir) gate the file-extension heuristic:
+ * an extension-bearing path is only Vite's when it names a real file under
+ * one of them, so page URLs like `/docs/v2.0` still SSR. Without `fileRoots`
+ * any extension counts (conservative).
+ */
+export function isViteOwnedUrl(url: URL, fileRoots?: string[]): boolean;
 export function defineConfig(options: OctaneConfigOptions): OctaneConfigOptions;
 export function resolveOctaneConfig(
 	raw: OctaneConfigOptions,
@@ -38,6 +59,7 @@ export class RenderRoute {
 	entry: RenderRouteEntry;
 	layout?: string;
 	before: Middleware[];
+	status?: number;
 	constructor(options: RenderRouteOptions);
 }
 
@@ -66,6 +88,11 @@ export interface RenderRouteOptions {
 	layout?: string;
 	/** Middleware to run before rendering */
 	before?: Middleware[];
+	/**
+	 * HTTP status for the rendered response (default 200). Set 404 on a
+	 * catch-all route so the SSR'd not-found page reports its real status.
+	 */
+	status?: number;
 }
 
 export interface ServerRouteOptions {
@@ -112,6 +139,27 @@ export type Component<T = Record<string, any>> = (
 
 export type RenderRouteEntry = string | readonly [exportName: string, path: string];
 
+/**
+ * Props every RenderRoute component (and layout) receives: the route params
+ * and the request `url` (pathname + search, origin-free — the client hydrate
+ * entry re-renders with the identical string).
+ */
+export interface RenderRouteProps {
+	params: Record<string, string>;
+	url: string;
+}
+
+/**
+ * The app hook run by the client hydrate entry BEFORE `hydrateRoot` (config
+ * `router.preHydrate`): commit client-side state the server already resolved —
+ * typically a client router loading its match tree — so the first hydration
+ * pass adopts the same tree the server rendered.
+ */
+export type PreHydrateHook = (info: {
+	url: string;
+	params: Record<string, string>;
+}) => void | Promise<void>;
+
 export interface RootBoundaryOptions {
 	pending?: Component<Record<string, never>>;
 	catch?: Component<{ error: unknown; reset: () => void }>;
@@ -124,17 +172,15 @@ export interface OctaneConfigOptions {
 		minify?: boolean;
 		target?: BuildEnvironmentOptions['target'];
 	};
-	adapter?: {
-		serve: AdapterServeFunction;
-		/**
-		 * Platform-specific runtime primitives provided by the adapter.
-		 * Required for production builds; in development the plugin falls back
-		 * to Node.js defaults if not provided.
-		 */
-		runtime: RuntimePrimitives;
-	};
+	adapter?: OctaneAdapter;
 	router?: {
 		routes: Route[];
+		/**
+		 * Vite-root path (e.g. '/src/pre-hydrate.ts') of a module whose default
+		 * export is a {@link PreHydrateHook}. The client hydrate entry imports it
+		 * and awaits the hook before calling `hydrateRoot`.
+		 */
+		preHydrate?: string;
 	};
 	/** Global root pending/catch UI used by client and SSR render roots */
 	rootBoundary?: RootBoundaryOptions;
@@ -150,6 +196,14 @@ export interface OctaneConfigOptions {
 		 * @default false
 		 */
 		trustProxy?: boolean;
+		/**
+		 * Production SSR mode: 'streaming' (default) flushes the shell at
+		 * first await and streams suspense segments out-of-order (same engine
+		 * as dev SSR); 'buffered' awaits everything (`prerender`) and sends
+		 * one document — for hosts that break streamed responses.
+		 * @default 'streaming'
+		 */
+		render?: 'streaming' | 'buffered';
 	};
 }
 
@@ -163,12 +217,10 @@ export interface ResolvedOctaneConfig {
 		minify?: boolean;
 		target?: BuildEnvironmentOptions['target'];
 	};
-	adapter?: {
-		serve: AdapterServeFunction;
-		runtime: RuntimePrimitives;
-	};
+	adapter?: OctaneAdapter;
 	router: {
 		routes: Route[];
+		preHydrate?: string;
 	};
 	rootBoundary: RootBoundaryOptions;
 	/** @default [] */
@@ -180,9 +232,46 @@ export interface ResolvedOctaneConfig {
 	server: {
 		/** @default false */
 		trustProxy: boolean;
+		/** @default 'streaming' */
+		render: 'streaming' | 'buffered';
 	};
 }
 
+/**
+ * The build context @octanejs/vite-plugin passes to an adapter's `adapt()`
+ * after `vite build` produced both bundles.
+ */
+export interface AdaptContext {
+	/** Absolute project root (the Vite root). */
+	root: string;
+	/** The config `build.outDir` (relative to root, e.g. 'dist'). */
+	outDir: string;
+	/** Absolute path of the static client bundle ({outDir}/client). */
+	clientDir: string;
+	/** Absolute path of the server bundle ({outDir}/server, contains entry.js). */
+	serverDir: string;
+	/** Prefixed build logger. */
+	log: (message: string) => void;
+}
+
+/**
+ * The octane.config.ts `adapter` contract. All parts are optional and
+ * independent:
+ *
+ * - `adapt(ctx)` — post-build hook: restructure dist/client + dist/server for
+ *   a deployment target (e.g. @octanejs/adapter-vercel emits `.vercel/output`).
+ * - `serve(handler, opts)` — replaces the generated server entry's built-in
+ *   Node boot when running `node dist/server/entry.js` / `octane-preview`.
+ * - `runtime` — platform primitives (hashing, async context) replacing the
+ *   entry's Node defaults; needed on non-Node runtimes.
+ */
+export interface OctaneAdapter {
+	name?: string;
+	adapt?: (ctx: AdaptContext) => void | Promise<void>;
+	serve?: AdapterServeFunction;
+	runtime?: RuntimePrimitives;
+}
+
 export type AdapterServeFunction = (
 	handler: (request: Request, platform?: unknown) => Response | Promise<Response>,
 	options?: Record<string, unknown>,

package/types/node.d.ts

@@ -0,0 +1,31 @@
+import type { IncomingMessage, ServerResponse, Server } from 'node:http';
+
+/** Convert a Node.js IncomingMessage to a Web Request. */
+export function nodeRequestToWebRequest(nodeRequest: IncomingMessage): Request;
+
+/**
+ * Pipe a Web Response to a Node.js ServerResponse, streaming chunk-by-chunk
+ * (a streaming SSR body flushes as it renders).
+ */
+export function sendWebResponse(nodeResponse: ServerResponse, webResponse: Response): Promise<void>;
+
+/**
+ * Serve a static file from `staticDir` when the request path maps to one.
+ * `/assets/*` (hash-named build output) gets immutable caching; other files
+ * revalidate. Returns true when the request was handled.
+ */
+export function serveStaticFile(
+	req: IncomingMessage,
+	res: ServerResponse,
+	staticDir: string,
+): boolean;
+
+/**
+ * Minimal production HTTP server: static files from `staticDir` first (the
+ * built client assets), then the fetch-style SSR handler. The default boot for
+ * `node dist/server/entry.js` when octane.config.ts has no adapter.
+ */
+export function createNodeServer(
+	handler: (request: Request) => Response | Promise<Response>,
+	options?: { staticDir?: string },
+): { listen: (port?: number) => Server; close: () => void };

package/types/production.d.ts

@@ -6,6 +6,7 @@ import type {
 	OctaneConfigOptions,
 	RootBoundaryOptions,
 } from '@octanejs/vite-plugin';
+import type { RenderResult, StreamOptions, RenderOptions } from 'octane/server';
 
 export function resolveOctaneConfig(
 	raw: OctaneConfigOptions,
@@ -13,45 +14,57 @@ export function resolveOctaneConfig(
 ): ResolvedOctaneConfig;
 
 export interface ClientAssetEntry {
-	/** Path to the built JS file (relative to client output dir) */
+	/** Path to the built JS file (relative to the client output dir) */
 	js: string;
-	/** Paths to the built CSS files (relative to client output dir) */
+	/** Paths to the built CSS files (relative to the client output dir) */
 	css: string[];
 }
 
 export interface ServerManifest {
 	routes: Route[];
-	components: Record<string, Function>;
-	layouts: Record<string, Function>;
+	/** RenderRoute entry module path → module namespace (export picked per-route) */
+	components: Record<string, Record<string, unknown>>;
+	/** Layout module path → module namespace */
+	layouts: Record<string, Record<string, unknown>>;
 	middlewares: Middleware[];
-	/** Map of entry path → _$_server_$_ object for RPC support */
-	rpcModules?: Record<string, Record<string, Function>>;
 	/** Trust X-Forwarded-* headers when deriving origin for RPC fetch */
 	trustProxy?: boolean;
+	/** 'streaming' (default) renders via renderToReadableStream; 'buffered' awaits everything via prerender */
+	render?: 'streaming' | 'buffered';
 	rootBoundary?: RootBoundaryOptions;
-	/** Platform-specific runtime primitives from the adapter */
-	runtime: RuntimePrimitives;
-	/** Map of route entry paths to built client asset paths (preload tags). */
+	/** config `router.preHydrate`, serialized into #__octane_data for the client entry */
+	preHydrate?: string | null;
+	/** Map of entry path → `module server` namespace for RPC support */
+	rpcModules?: Record<string, Record<string, Function>>;
+	/** Platform primitives (adapter's, or the generated entry's Node defaults) */
+	runtime?: RuntimePrimitives;
+	/** Route entry module path → built client asset paths (preload tags) */
 	clientAssets?: Record<string, ClientAssetEntry>;
 }
 
-/**
- * octane RenderResult — re-exported from 'octane/server' (the single source of
- * truth) rather than re-declared, so the shape can't silently drift. Note
- * `render()` is async and `css` is ALREADY a ready, deduped
- * `<style data-octane="hash">…</style>` string (NOT a Set<string> needing a
- * `getCss` lookup like Ripple).
- */
-export type { RenderResult } from 'octane/server';
-import type { RenderResult } from 'octane/server';
-
 export interface HandlerOptions {
-	render: (component: Function, props?: unknown) => Promise<RenderResult>;
+	/** `renderToReadableStream` from 'octane/server' (the streaming engine dev SSR uses) */
+	renderToReadableStream: (
+		component: Function,
+		props?: unknown,
+		options?: StreamOptions,
+	) => Promise<ReadableStream<Uint8Array>>;
+	/** `prerender` from 'octane/static' (the buffered await-everything fallback) */
+	prerender: (
+		component: Function,
+		props?: unknown,
+		options?: RenderOptions,
+	) => Promise<RenderResult>;
+	/** The BUILT dist client index.html (moved to dist/server by the build) */
 	htmlTemplate: string;
+	/** RPC executor from 'octane/server' */
 	executeServerFunction: (fn: Function, body: string) => Promise<string>;
 }
 
-/** Production fetch-handler factory. PHASE 2. */
+/**
+ * Production fetch-handler factory. Mirrors the dev middleware's render path
+ * byte-for-byte in everything hydration can see (see server/production.js).
+ */
 export function createHandler(
 	manifest: ServerManifest,
 	options: HandlerOptions,