@octanejs/vite-plugin 0.1.3 → 0.1.4

package/src/server/virtual-entry.js

@@ -1,15 +1,184 @@
+// @ts-check
 /**
  * Production server-entry generator.
  *
- * PHASE 1 STUB. The generated server entry (imported by the SSR bundle build
- * in `closeBundle`) wires page/layout/rpc modules into `createHandler`. It is
- * unused in dev (dev SSR uses `vite.ssrLoadModule`). Implemented in Phase 2.
+ * `generateServerEntry` emits the module the SSR sub-build (closeBundle in
+ * src/index.js) uses as its Rollup input. The generated module statically
+ * imports every RenderRoute entry/layout module (compiled in server mode by
+ * the octane plugin the sub-build inherits from the app's vite.config) plus
+ * octane.config.ts itself, wires them into `createHandler`, and:
+ *
+ *   - exports `handler`  — the Web fetch handler `(Request) => Promise<Response>`
+ *   - exports `nodeHandler` — a Node `(req, res)` wrapper for serverless
+ *     platforms (e.g. a Vercel Node function does
+ *     `export { nodeHandler as default } from '../dist/server/entry.js'`)
+ *   - auto-boots when run directly (`node dist/server/entry.js`): the
+ *     adapter's `serve()` when configured, else the built-in Node server
+ *     (static dist/client assets + the handler).
+ *
+ * It is unused in dev (dev SSR loads modules through `vite.ssrLoadModule`).
+ */
+
+/** @import { Route } from '@octanejs/vite-plugin' */
+/** @import { ClientAssetEntry } from '../../types/production.d.ts' */
+
+import { get_route_entry_path } from '../routes.js';
+
+/**
+ * @typedef {Object} ServerEntryOptions
+ * @property {Route[]} routes - Route definitions from octane.config.ts
+ * @property {string} octaneConfigPath - Absolute path to octane.config.ts
+ * @property {Record<string, ClientAssetEntry>} [clientAssetMap] - Route entry path → built client asset paths
  */
 
 /**
- * @param {unknown} _options
- * @returns {never}
+ * @param {ServerEntryOptions} options
+ * @returns {string} The generated JavaScript module source
+ */
+export function generateServerEntry(options) {
+	const { routes, octaneConfigPath, clientAssetMap = {} } = options;
+
+	// Unique page-entry and layout module paths (multiple routes may share both).
+	/** @type {Map<string, string>} module path → import variable name */
+	const page_imports = new Map();
+	/** @type {Map<string, string>} */
+	const layout_imports = new Map();
+
+	for (const route of routes) {
+		if (route.type !== 'render') continue;
+		const entryPath = get_route_entry_path(route.entry);
+		if (entryPath && !page_imports.has(entryPath)) {
+			page_imports.set(entryPath, `_page_${page_imports.size}`);
+		}
+		if (typeof route.layout === 'string' && !layout_imports.has(route.layout)) {
+			layout_imports.set(route.layout, `_layout_${layout_imports.size}`);
+		}
+	}
+
+	const import_lines = [];
+	for (const [modulePath, varName] of page_imports) {
+		import_lines.push(`import * as ${varName} from ${JSON.stringify(modulePath)};`);
+	}
+	for (const [modulePath, varName] of layout_imports) {
+		import_lines.push(`import * as ${varName} from ${JSON.stringify(modulePath)};`);
+	}
+
+	// The manifest maps MODULE PATHS to module namespaces; createHandler picks
+	// the export per-route with the same `get_component_export` dev uses.
+	const component_entries = [...page_imports]
+		.map(([modulePath, varName]) => `\t${JSON.stringify(modulePath)}: ${varName},`)
+		.join('\n');
+	const layout_entries = [...layout_imports]
+		.map(([modulePath, varName]) => `\t${JSON.stringify(modulePath)}: ${varName},`)
+		.join('\n');
+
+	return `\
+// Auto-generated by @octanejs/vite-plugin — the production server entry.
+// Do not edit; regenerated on every build.
+
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+
+import { renderToReadableStream, executeServerFunction } from 'octane/server';
+import { prerender } from 'octane/static';
+import { createHandler, resolveOctaneConfig } from '@octanejs/vite-plugin/production';
+import { createNodeServer, nodeRequestToWebRequest, sendWebResponse } from '@octanejs/vite-plugin/node';
+
+// The app config — bundled (the sub-build aliases '@octanejs/vite-plugin' to
+// its config-surface facade, so this does not drag the compiler in).
+import _rawOctaneConfig from ${JSON.stringify(octaneConfigPath)};
+
+${import_lines.join('\n')}
+
+const octaneConfig = resolveOctaneConfig(_rawOctaneConfig);
+
+// Platform primitives: the adapter's when configured, else Node defaults.
+// (hash mirrors the compiler's module-server hashing: sha-256 hex, 8 chars.)
+const runtime = octaneConfig.adapter?.runtime ?? {
+	hash: (str) => createHash('sha256').update(str).digest('hex').slice(0, 8),
+	createAsyncContext: () => {
+		const als = new AsyncLocalStorage();
+		return { run: (store, fn) => als.run(store, fn), getStore: () => als.getStore() };
+	},
+};
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// The HTML template is the BUILT client index.html (hashed hydrate script and
+// asset links already in place), moved next to this entry by the build.
+const htmlTemplate = readFileSync(join(__dirname, './index.html'), 'utf-8');
+
+const components = {
+${component_entries}
+};
+
+const layouts = {
+${layout_entries}
+};
+
+const clientAssets = ${JSON.stringify(clientAssetMap, null, '\t')};
+
+export const handler = createHandler(
+	{
+		routes: octaneConfig.router.routes,
+		components,
+		layouts,
+		middlewares: octaneConfig.middlewares,
+		trustProxy: octaneConfig.server.trustProxy,
+		render: octaneConfig.server.render,
+		rootBoundary: octaneConfig.rootBoundary,
+		preHydrate: octaneConfig.router.preHydrate ?? null,
+		rpcModules: {},
+		runtime,
+		clientAssets,
+	},
+	{
+		renderToReadableStream,
+		prerender,
+		htmlTemplate,
+		executeServerFunction,
+	},
+);
+
+/**
+ * Node-style (req, res) wrapper — for serverless platforms whose functions
+ * speak Node HTTP (e.g. Vercel's Node runtime).
  */
-export function generateServerEntry(_options) {
-	throw new Error('[@octanejs/vite-plugin] Server entry generation is Phase 2.');
+export async function nodeHandler(req, res) {
+	try {
+		const response = await handler(nodeRequestToWebRequest(req));
+		await sendWebResponse(res, response);
+	} catch (error) {
+		console.error('[@octanejs/vite-plugin] Request error:', error);
+		if (!res.headersSent) {
+			res.statusCode = 500;
+			res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+		}
+		res.end('Internal Server Error');
+	}
+}
+
+// Auto-boot when run directly (node dist/server/entry.js); stay quiet when
+// imported by a serverless wrapper.
+const isMainModule =
+	typeof process !== 'undefined' &&
+	process.argv[1] &&
+	fileURLToPath(import.meta.url) === resolve(process.argv[1]);
+
+if (isMainModule) {
+	const port = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000;
+	if (isNaN(port) || port < 1 || port > 65535) {
+		console.error('[@octanejs/vite-plugin] Invalid PORT value:', process.env.PORT);
+		process.exit(1);
+	}
+	const staticDir = join(__dirname, '../client');
+	const server = octaneConfig.adapter?.serve
+		? octaneConfig.adapter.serve(handler, { static: { dir: staticDir } })
+		: createNodeServer(handler, { staticDir });
+	server.listen(port);
+	console.log('[@octanejs/vite-plugin] Production server listening on port ' + port);
+}
+`;
 }

package/tests/_fixtures/app/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<title>Fixture</title>
+		<!--ssr-head-->
+	</head>
+	<body>
+		<div id="root"><!--ssr-body--></div>
+	</body>
+</html>

package/tests/_fixtures/app/octane.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig, RenderRoute } from '@octanejs/vite-plugin';
+
+export default defineConfig({
+	router: {
+		routes: [
+			new RenderRoute({ path: '/', entry: ['Page', '/src/Page.tsrx'], layout: '/src/Layout.tsrx' }),
+			new RenderRoute({
+				path: '/pages/:slug',
+				entry: ['Page', '/src/Page.tsrx'],
+				layout: '/src/Layout.tsrx',
+			}),
+		],
+	},
+});

package/tests/_fixtures/app/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "octane-vite-plugin-fixture-app",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "description": "Minimal app the production-build test builds end-to-end (node_modules is symlinked by the test setup)."
+}

package/tests/_fixtures/app/src/Layout.tsrx

@@ -0,0 +1,6 @@
+export default function Layout(props: { children: unknown }) @{
+	<div class="shell">
+		<nav>{'fixture-nav'}</nav>
+		{props.children}
+	</div>
+}

package/tests/_fixtures/app/src/Page.tsrx

@@ -0,0 +1,17 @@
+import { useState } from 'octane';
+
+// A page with a dynamic text hole, a param read, and an event handler — enough
+// to prove the server bundle renders hydratable markup (markers + scoped
+// state) identical to dev SSR.
+export function Page(props: { params: Record<string, string>; url: string }) @{
+	const [count] = useState(1);
+	<main>
+		<h1>
+			{'Fixture page ' + (props.params.slug ?? 'home')}
+		</h1>
+		<p class="url">{props.url}</p>
+		<p class="count">
+			{'Count: ' + count}
+		</p>
+	</main>
+}

package/tests/_fixtures/app/vite.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vite';
+import { octane } from '@octanejs/vite-plugin';
+
+// SSR module graphs (dev + server build) must see the server runtime for bare
+// 'octane' imports from non-compiled sources (none here, but keeps the fixture
+// shaped like a real app).
+export default defineConfig({
+	plugins: [octane()],
+	ssr: {
+		noExternal: [/^octane($|\/)/],
+	},
+});

package/tests/handler.test.ts

@@ -0,0 +1,134 @@
+// createHandler unit tests — the production handler's pure assembly decisions
+// (template splitting, hydration payload shape, status, preload tags, the
+// buffered fallback, server routes, 404) with stub renderers. The real-render
+// byte-compat path is covered end-to-end in production.test.ts.
+import { describe, it, expect } from 'vitest';
+import { createHandler } from '../src/server/production.js';
+import { RenderRoute, ServerRoute } from '../src/routes.js';
+
+const TEMPLATE = `<!doctype html>
+<html><head><!--ssr-head--></head><body><div id="root"><!--ssr-body--></div>
+<script type="module" src="/assets/hydrate-abc.js"></script></body></html>`;
+
+function Page() {
+	return '<main>page</main>';
+}
+
+function streamOf(text: string): ReadableStream<Uint8Array> {
+	return new ReadableStream({
+		start(controller) {
+			controller.enqueue(new TextEncoder().encode(text));
+			controller.close();
+		},
+	});
+}
+
+const baseDeps = {
+	renderToReadableStream: async () =>
+		streamOf('<style data-octane="x">.x{}</style><main>page</main>'),
+	prerender: async () => ({
+		html: '<main>page</main>',
+		css: '<style data-octane="x">.x{}</style>',
+	}),
+	htmlTemplate: TEMPLATE,
+	executeServerFunction: async () => '',
+};
+
+function makeManifest(overrides: Record<string, unknown> = {}) {
+	const routes = [
+		new RenderRoute({ path: '/', entry: ['Page', '/src/Page.tsrx'] }),
+		new RenderRoute({ path: '/*splat', entry: ['Page', '/src/Page.tsrx'], status: 404 }),
+		new ServerRoute({
+			path: '/api/ping',
+			handler: () => new Response('pong', { status: 200 }),
+		}),
+	];
+	return {
+		routes,
+		components: { '/src/Page.tsrx': { Page } },
+		layouts: {},
+		middlewares: [],
+		...overrides,
+	};
+}
+
+describe('createHandler', () => {
+	it('streams template prefix → render stream → suffix with the dev-shaped data script', async () => {
+		const handler = createHandler(makeManifest() as any, baseDeps as any);
+		const response = await handler(new Request('http://localhost/?q=1'));
+		expect(response.status).toBe(200);
+		const html = await response.text();
+
+		// Assembly: styles + markup inside #root, template suffix intact.
+		expect(html).toContain(
+			'<div id="root"><style data-octane="x">.x{}</style><main>page</main></div>',
+		);
+		expect(html).toContain('src="/assets/hydrate-abc.js"');
+
+		// The payload matches dev render-route.js: same keys, same order.
+		const payload = html.match(/__octane_data" type="application\/json">(.*?)<\/script>/s)![1];
+		expect(payload).toBe(
+			JSON.stringify({
+				entry: '/src/Page.tsrx',
+				exportName: 'Page',
+				layout: null,
+				routeIndex: 0,
+				params: {},
+				url: '/?q=1',
+				preHydrate: null,
+			}),
+		);
+	});
+
+	it('uses the RenderRoute status (catch-all 404) and route params', async () => {
+		const handler = createHandler(makeManifest() as any, baseDeps as any);
+		const response = await handler(new Request('http://localhost/not/a/page'));
+		expect(response.status).toBe(404);
+		const html = await response.text();
+		expect(html).toContain('"params":{"splat":"not/a/page"}');
+	});
+
+	it("render: 'buffered' awaits prerender and sends one document (css leads the body)", async () => {
+		let streamed = false;
+		const deps = {
+			...baseDeps,
+			renderToReadableStream: async () => {
+				streamed = true;
+				return streamOf('');
+			},
+		};
+		const handler = createHandler(makeManifest({ render: 'buffered' }) as any, deps as any);
+		const html = await (await handler(new Request('http://localhost/'))).text();
+		expect(streamed).toBe(false);
+		expect(html).toContain(
+			'<div id="root"><style data-octane="x">.x{}</style><main>page</main></div>',
+		);
+	});
+
+	it('emits stylesheet + modulepreload tags for the matched entry from clientAssets', async () => {
+		const handler = createHandler(
+			makeManifest({
+				clientAssets: {
+					'/src/Page.tsrx': { js: 'assets/Page-123.js', css: ['assets/Page-123.css'] },
+				},
+			}) as any,
+			baseDeps as any,
+		);
+		const html = await (await handler(new Request('http://localhost/'))).text();
+		expect(html).toContain('<link rel="stylesheet" href="/assets/Page-123.css">');
+		expect(html).toContain('<link rel="modulepreload" href="/assets/Page-123.js">');
+	});
+
+	it('serves ServerRoutes and 404s unmatched paths when no catch-all exists', async () => {
+		const manifest = makeManifest();
+		(manifest.routes as unknown[]).splice(1, 1); // drop the catch-all
+		const handler = createHandler(manifest as any, baseDeps as any);
+
+		const api = await handler(new Request('http://localhost/api/ping'));
+		expect(api.status).toBe(200);
+		expect(await api.text()).toBe('pong');
+
+		const missing = await handler(new Request('http://localhost/nope'));
+		expect(missing.status).toBe(404);
+	});
+});

package/tests/plugin.test.ts

@@ -0,0 +1,155 @@
+// @octanejs/vite-plugin unit tests — the pure decision logic the website
+// surfaced gaps in: the dev-middleware's Vite-owned URL filter, `octane()`
+// option forwarding to the bundled compiler, the appType default, and the
+// config resolution of `router.preHydrate` / RenderRoute `status`.
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+import { describe, it, expect } from 'vitest';
+import { octane, isViteOwnedUrl, resolveOctaneConfig, RenderRoute } from '../src/index.js';
+import { RESOLVED_ADAPTER_BROWSER_STUB_ID } from '../src/project-codegen.js';
+
+function url(u: string): URL {
+	return new URL(u, 'http://localhost');
+}
+
+// Use this package as the fake Vite root: '/src/index.js' and '/types/index.d.ts'
+// are real files under it, '/docs/v2.0' etc. are not.
+const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+describe('isViteOwnedUrl', () => {
+	it('skips Vite-internal namespaces and module/asset requests', () => {
+		expect(isViteOwnedUrl(url('/@vite/client'))).toBe(true);
+		expect(isViteOwnedUrl(url('/@id/virtual:octane-hydrate'))).toBe(true);
+		expect(isViteOwnedUrl(url('/@fs/Users/x/repo/src/main.ts'))).toBe(true);
+		expect(isViteOwnedUrl(url('/__open-in-editor?file=x'))).toBe(true);
+		expect(isViteOwnedUrl(url('/node_modules/.vite/deps/chunk.js'))).toBe(true);
+		expect(isViteOwnedUrl(url('/src/main.ts'))).toBe(true);
+		expect(isViteOwnedUrl(url('/src/app/App.tsrx?v=abc123'))).toBe(true);
+		expect(isViteOwnedUrl(url('/favicon.svg'))).toBe(true);
+		expect(isViteOwnedUrl(url('/src/worker?worker'))).toBe(true);
+		expect(isViteOwnedUrl(url('/src/logo?url'))).toBe(true);
+	});
+
+	it('keeps page navigations', () => {
+		expect(isViteOwnedUrl(url('/'))).toBe(false);
+		expect(isViteOwnedUrl(url('/docs'))).toBe(false);
+		expect(isViteOwnedUrl(url('/docs/quick-start'))).toBe(false);
+		expect(isViteOwnedUrl(url('/definitely/not/a/page'))).toBe(false);
+		expect(isViteOwnedUrl(url('/search?q=octane'))).toBe(false);
+		// A bare dotfile segment is not an extension.
+		expect(isViteOwnedUrl(url('/.well-known'))).toBe(false);
+		// VALUED params matching a marker name are app query strings — Vite's
+		// transform markers are always bare (`?url`, `?raw`, `&import`).
+		expect(isViteOwnedUrl(url('/docs?url=https://example.com'))).toBe(false);
+		expect(isViteOwnedUrl(url('/page?raw=1'))).toBe(false);
+		expect(isViteOwnedUrl(url('/jobs?worker=nurse'))).toBe(false);
+	});
+
+	it('with fileRoots, an extension only counts when a real file backs it', () => {
+		// Real files under the root → Vite's.
+		expect(isViteOwnedUrl(url('/src/index.js'), [PKG_ROOT])).toBe(true);
+		expect(isViteOwnedUrl(url('/types/index.d.ts?v=abc'), [PKG_ROOT])).toBe(true);
+		// Dotted PAGE urls → SSR them.
+		expect(isViteOwnedUrl(url('/docs/v2.0'), [PKG_ROOT])).toBe(false);
+		expect(isViteOwnedUrl(url('/users/jane.doe'), [PKG_ROOT])).toBe(false);
+		// A missing asset also SSRs (the app's 404 page beats a bare dev 404).
+		expect(isViteOwnedUrl(url('/missing.png'), [PKG_ROOT])).toBe(false);
+		// Multiple roots (root + publicDir).
+		expect(isViteOwnedUrl(url('/src/index.js'), ['/nowhere', PKG_ROOT])).toBe(true);
+		// Non-file checks are unaffected by fileRoots.
+		expect(isViteOwnedUrl(url('/@vite/client'), [PKG_ROOT])).toBe(true);
+		expect(isViteOwnedUrl(url('/src/worker?worker'), [PKG_ROOT])).toBe(true);
+	});
+});
+
+describe('octane() plugin factory', () => {
+	it('forwards `exclude` to the bundled compiler (hook-slotting skip)', () => {
+		const [compiler] = octane({ exclude: ['/packages/tanstack-router/src/'] });
+		const code =
+			"import { useState } from 'octane';\nexport function useThing() { return useState(0); }\n";
+		const transform = compiler.transform as (code: string, id: string) => unknown;
+
+		// A pnpm-symlinked binding source resolves to /packages/*/src — excluded,
+		// so the hand-slot-forwarding file passes through untouched.
+		expect(transform.call({}, code, '/repo/packages/tanstack-router/src/useRouter.ts')).toBeNull();
+		// App code is still slotted.
+		expect(transform.call({}, code, '/repo/src/useThing.ts')).not.toBeNull();
+	});
+
+	it("defaults appType to 'custom' for dev, but respects the user and `vite preview`", async () => {
+		const [, meta] = octane();
+		const config = meta.config as (
+			userConfig: object,
+			env: object,
+		) => Promise<{ appType?: string }>;
+
+		expect((await config({}, { command: 'serve', mode: 'development' })).appType).toBe('custom');
+		// An explicit user appType wins.
+		expect(
+			(await config({ appType: 'spa' }, { command: 'serve', mode: 'development' })).appType,
+		).toBe(undefined);
+		// `vite preview` serves static files with Vite's own fallback; the
+		// production SSR build is previewed with `octane-preview` instead.
+		expect(
+			(await config({}, { command: 'serve', mode: 'production', isPreview: true })).appType,
+		).toBe(undefined);
+	});
+});
+
+describe('resolveOctaneConfig', () => {
+	const entry = ['App', '/src/App.tsrx'] as const;
+
+	it('passes router.preHydrate through and validates its shape', () => {
+		const resolved = resolveOctaneConfig({
+			router: {
+				routes: [new RenderRoute({ path: '/', entry })],
+				preHydrate: '/src/pre-hydrate.ts',
+			},
+		});
+		expect(resolved.router.preHydrate).toBe('/src/pre-hydrate.ts');
+		// Absent stays absent.
+		expect(resolveOctaneConfig({}).router.preHydrate).toBe(undefined);
+		// Must be a Vite-root path the browser can dynamic-import.
+		expect(() =>
+			resolveOctaneConfig({ router: { routes: [], preHydrate: 'src/pre-hydrate.ts' } }),
+		).toThrow(/preHydrate/);
+	});
+
+	it('accepts an integer RenderRoute status and rejects anything else', () => {
+		const route = new RenderRoute({ path: '/*splat', entry, status: 404 });
+		expect(route.status).toBe(404);
+		expect(resolveOctaneConfig({ router: { routes: [route] } }).router.routes[0]).toBe(route);
+		expect(() =>
+			resolveOctaneConfig({
+				router: { routes: [new RenderRoute({ path: '/', entry, status: 4.04 })] },
+			}),
+		).toThrow(/status/);
+	});
+});
+
+describe('server-only adapter browser stub', () => {
+	const [, meta] = octane();
+	const resolveId = meta.resolveId as (
+		id: string,
+		importer?: string,
+		options?: { ssr?: boolean },
+	) => Promise<string | null>;
+	const load = meta.load as (id: string) => Promise<string | undefined>;
+
+	it('client-side imports of adapter packages resolve to the stub, server gets the real one', async () => {
+		for (const id of ['@octanejs/adapter-vercel', '@ripple-ts/adapter-node']) {
+			expect(await resolveId(id, undefined, { ssr: false })).toBe(RESOLVED_ADAPTER_BROWSER_STUB_ID);
+		}
+		expect(await resolveId('@octanejs/adapter-vercel', undefined, { ssr: true })).toBe(null);
+	});
+
+	it('the stub covers the octane adapter surface with no node builtins', async () => {
+		const source = (await load(RESOLVED_ADAPTER_BROWSER_STUB_ID)) as string;
+		// The union of the listed adapters' public names — a client import of any
+		// of them must resolve (and only throw on USE).
+		for (const name of ['vercel', 'adapt', 'serve']) {
+			expect(source).toContain(`export function ${name}`);
+		}
+		expect(source).not.toContain('node:');
+	});
+});