@octanejs/adapter-vercel 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@octanejs/adapter-vercel",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "description": "Vercel adapter for octane apps (Build Output API v3)",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/adapter-vercel"
+  },
+  "module": "src/index.js",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "@octanejs/vite-plugin": "0.1.3"
+  }
+}

package/src/adapt.js

@@ -0,0 +1,216 @@
+// @ts-check
+/**
+ * Vercel Build Output API v3 emitter.
+ *
+ * Restructures an octane production build (`dist/client` + `dist/server`,
+ * produced by @octanejs/vite-plugin) into `.vercel/output/`:
+ *
+ *   static/               ← dist/client verbatim (hashed assets; the build
+ *                           already moved index.html — the SSR template —
+ *                           to dist/server, so nothing shadows SSR at '/')
+ *   functions/index.func/ ← dist/server verbatim + a generated index.js that
+ *                           wraps the entry's fetch `handler` in Vercel's
+ *                           Web-Standard function shape
+ *   config.json           ← routing: immutable asset headers → filesystem →
+ *                           catch-all to the function
+ *
+ * Modeled on @ripple-ts/adapter-vercel (itself after @sveltejs/adapter-vercel),
+ * with one octane simplification: the server entry is SELF-CONTAINED (the
+ * plugin bundles the app + octane with `ssr.noExternal: true`), so there is no
+ * dependency tracing — the function is dist/server plus one wrapper file.
+ */
+
+/** @import { VercelAdapterOptions, VercelConfig, VercelRoute } from '@octanejs/adapter-vercel' */
+/** @import { AdaptContext } from '@octanejs/vite-plugin' */
+
+import { existsSync, mkdirSync, cpSync, writeFileSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { createRequire } from 'node:module';
+
+const VERCEL_OUTPUT_DIR = '.vercel/output';
+
+/**
+ * The adapter's own version (for .vc-config.json `framework`). MUST stay lazy:
+ * octane.config.ts is compiled into the server bundle, so this module's scope
+ * executes when the deployed function boots — where `../package.json` does not
+ * exist. adapt() itself only ever runs at build time from the real package.
+ * @returns {string}
+ */
+function get_adapter_version() {
+	try {
+		const require = createRequire(import.meta.url);
+		return require('../package.json').version;
+	} catch {
+		return '0.0.0';
+	}
+}
+
+/**
+ * Default Node.js runtime for the function, from the build machine's major.
+ * @returns {string}
+ */
+function get_default_runtime() {
+	const major = Number(process.version.slice(1).split('.')[0]);
+	const valid = [20, 22, 24];
+	if (!valid.includes(major)) {
+		throw new Error(
+			`[@octanejs/adapter-vercel] Unsupported Node.js version: ${process.version}. ` +
+				`Build with Node ${valid.join('/')} or set serverless.runtime explicitly.`,
+		);
+	}
+	return `nodejs${major}.x`;
+}
+
+/**
+ * @param {string} file_path
+ * @param {string} data
+ */
+function write(file_path, data) {
+	mkdirSync(dirname(file_path), { recursive: true });
+	writeFileSync(file_path, data);
+}
+
+/**
+ * The serverless function entry: Vercel's Web-Standard shape
+ * (`export default { fetch(Request) => Response }`) over the built handler.
+ * @returns {string}
+ */
+function generate_handler_source() {
+	return `// Auto-generated by @octanejs/adapter-vercel — the Vercel function entry.
+// The imported handler is the self-contained octane SSR bundle's fetch handler.
+import { handler } from './entry.js';
+
+export default {
+	async fetch(request) {
+		try {
+			return await handler(request);
+		} catch (error) {
+			console.error('[octane] Serverless handler error:', error);
+			return new Response('Internal Server Error', { status: 500 });
+		}
+	},
+};
+`;
+}
+
+/**
+ * Build Output API v3 config.json.
+ *
+ * @param {VercelAdapterOptions} options
+ * @returns {VercelConfig}
+ */
+function generate_vercel_config(options) {
+	const { cleanUrls = true, trailingSlash, images, headers = [], redirects = [] } = options;
+
+	/** @type {VercelRoute[]} */
+	const routes = [];
+
+	for (const redirect of redirects) {
+		routes.push({
+			src: redirect.source,
+			headers: { Location: redirect.destination },
+			status: redirect.permanent ? 308 : 307,
+		});
+	}
+
+	// Hashed build assets are immutable by construction.
+	routes.push({
+		src: '/assets/.+',
+		headers: { 'Cache-Control': 'public, max-age=31536000, immutable' },
+		continue: true,
+	});
+
+	for (const header of headers) {
+		routes.push({
+			src: header.source,
+			headers: Object.fromEntries(header.headers.map((h) => [h.key, h.value])),
+			continue: true,
+		});
+	}
+
+	// Static files win first; everything else — every page, including the
+	// catch-all 404 route — is server-rendered by the function.
+	routes.push({ handle: 'filesystem' });
+	routes.push({ src: '/.*', dest: '/index' });
+
+	/** @type {VercelConfig} */
+	const config = { version: 3, routes };
+	if (cleanUrls !== undefined) config.cleanUrls = cleanUrls;
+	if (trailingSlash !== undefined) config.trailingSlash = trailingSlash;
+	if (images) config.images = images;
+	return config;
+}
+
+/**
+ * Emit `.vercel/output` from a completed octane build.
+ *
+ * Callable two ways: by @octanejs/vite-plugin's closeBundle (which passes its
+ * {@link AdaptContext}) or directly with explicit dirs.
+ *
+ * @param {AdaptContext} ctx
+ * @param {VercelAdapterOptions} [options]
+ * @returns {Promise<void>}
+ */
+export async function adapt(ctx, options = {}) {
+	const { root, clientDir, serverDir } = ctx;
+	const log = ctx.log ?? ((/** @type {string} */ msg) => console.log(msg));
+
+	const server_entry = join(serverDir, 'entry.js');
+	if (!existsSync(clientDir)) {
+		throw new Error(`[@octanejs/adapter-vercel] Client build output not found at ${clientDir}.`);
+	}
+	if (!existsSync(server_entry)) {
+		throw new Error(`[@octanejs/adapter-vercel] Server entry not found at ${server_entry}.`);
+	}
+
+	const output_dir = join(root, VERCEL_OUTPUT_DIR);
+	rmSync(output_dir, { recursive: true, force: true });
+	mkdirSync(output_dir, { recursive: true });
+
+	// 1. Static assets — dist/client verbatim (no index.html in it: the build
+	//    moved the SSR template to dist/server).
+	const static_dir = join(output_dir, 'static');
+	mkdirSync(static_dir, { recursive: true });
+	cpSync(clientDir, static_dir, { recursive: true });
+
+	// 2. The serverless function — dist/server verbatim (self-contained entry +
+	//    the SSR template + any dynamic-import chunks) plus the wrapper.
+	const func_dir = join(output_dir, 'functions', 'index.func');
+	mkdirSync(func_dir, { recursive: true });
+	cpSync(serverDir, func_dir, { recursive: true });
+	write(join(func_dir, 'index.js'), generate_handler_source());
+	write(join(func_dir, 'package.json'), JSON.stringify({ type: 'module' }));
+
+	const runtime = options.serverless?.runtime ?? get_default_runtime();
+	/** @type {Record<string, unknown>} */
+	const vc_config = {
+		runtime,
+		handler: 'index.js',
+		launcherType: 'Nodejs',
+		experimentalResponseStreaming: true,
+		framework: { slug: 'octane', version: get_adapter_version() },
+	};
+	if (options.serverless?.regions) vc_config.regions = options.serverless.regions;
+	if (options.serverless?.memory) vc_config.memory = options.serverless.memory;
+	if (options.serverless?.maxDuration) vc_config.maxDuration = options.serverless.maxDuration;
+
+	// ISR: cache the function's response at the edge, revalidate after
+	// `expiration` seconds (false = never expire).
+	if (options.isr) {
+		/** @type {Record<string, unknown>} */
+		const prerender = { expiration: options.isr.expiration };
+		if (options.isr.bypassToken) prerender.bypassToken = options.isr.bypassToken;
+		if (options.isr.allowQuery !== undefined) prerender.allowQuery = options.isr.allowQuery;
+		vc_config.prerender = prerender;
+	}
+
+	write(join(func_dir, '.vc-config.json'), JSON.stringify(vc_config, null, '\t'));
+
+	// 3. Routing config.
+	write(
+		join(output_dir, 'config.json'),
+		JSON.stringify(generate_vercel_config(options), null, '\t'),
+	);
+
+	log(`[@octanejs/adapter-vercel] Build Output written to ${VERCEL_OUTPUT_DIR} (${runtime})`);
+}

package/src/index.js

@@ -0,0 +1,42 @@
+// @ts-check
+/**
+ * @octanejs/adapter-vercel — Vercel adapter for octane apps.
+ *
+ * Usage (octane.config.ts):
+ *
+ *   import { vercel } from '@octanejs/adapter-vercel';
+ *   export default defineConfig({
+ *     adapter: vercel(),
+ *     router: { … },
+ *   });
+ *
+ * `vercel(options)` returns the plugin's adapter contract: after `vite build`
+ * produces both bundles, @octanejs/vite-plugin calls `adapt(ctx)` and this
+ * adapter restructures them into Vercel's Build Output API v3 under
+ * `.vercel/output/` — no vercel.json rewrites, no hand-written api/ function.
+ * The same contract shape (`{ name, adapt }`) is what a Cloudflare/Netlify
+ * adapter implements to target other platforms.
+ *
+ * No `serve`/`runtime` overrides are provided: Vercel functions run on Node,
+ * and the generated server entry's built-in Node defaults (AsyncLocalStorage
+ * async context, sha-256 hash) are exactly right — `octane-preview` keeps
+ * serving dist/server locally, untouched by the adapter.
+ */
+
+/** @import { VercelAdapterOptions } from '@octanejs/adapter-vercel' */
+/** @import { OctaneAdapter } from '@octanejs/vite-plugin' */
+
+import { adapt } from './adapt.js';
+
+export { adapt };
+
+/**
+ * @param {VercelAdapterOptions} [options]
+ * @returns {OctaneAdapter}
+ */
+export function vercel(options = {}) {
+	return {
+		name: 'vercel',
+		adapt: (ctx) => adapt(ctx, options),
+	};
+}

package/tests/adapt.test.ts

@@ -0,0 +1,100 @@
+// @vitest-environment node
+//
+// adapt() emitter test — feeds a fake completed octane build (the dist/client +
+// dist/server layout @octanejs/vite-plugin produces) through adapt() and
+// asserts the emitted `.vercel/output` is valid Build Output API v3: static
+// assets, one self-contained Node function, and the routing config. The
+// emitted function entry is then actually imported and invoked. The end-to-end
+// wiring (closeBundle → adapt via `adapter: vercel()`) is covered by the
+// website's ssr-smoke test, which runs the real `vite build`.
+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 { adapt } from '../src/index.js';
+
+// The tests dir doubles as the fake project root: the fake build goes in
+// `dist/` and adapt() writes `.vercel/output/` next to it — both gitignored.
+const root = fileURLToPath(new URL('.', import.meta.url));
+const clientDir = path.join(root, 'dist/client');
+const serverDir = path.join(root, 'dist/server');
+const outputDir = path.join(root, '.vercel/output');
+const funcDir = path.join(outputDir, 'functions/index.func');
+
+// A stand-in for the plugin's self-contained server bundle: same shape (fetch
+// `handler` export next to the SSR template), no dependencies.
+const FAKE_ENTRY = `export const handler = async (req) => new Response('ok:' + new URL(req.url).pathname);\n`;
+
+function write(file: string, data: string) {
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	fs.writeFileSync(file, data);
+}
+
+beforeAll(async () => {
+	fs.rmSync(path.join(root, 'dist'), { recursive: true, force: true });
+	fs.rmSync(path.join(root, '.vercel'), { recursive: true, force: true });
+
+	write(path.join(clientDir, 'assets/app-abc.js'), 'console.log("app");\n');
+	write(path.join(serverDir, 'entry.js'), FAKE_ENTRY);
+	write(path.join(serverDir, 'index.html'), '<!doctype html><html><!--ssr-body--></html>\n');
+
+	await adapt({ root, outDir: 'dist', clientDir, serverDir, log: () => {} });
+});
+
+afterAll(() => {
+	fs.rmSync(path.join(root, 'dist'), { recursive: true, force: true });
+	fs.rmSync(path.join(root, '.vercel'), { recursive: true, force: true });
+});
+
+describe('adapt()', () => {
+	it('emits Build Output API v3 routing config', () => {
+		const config = JSON.parse(fs.readFileSync(path.join(outputDir, 'config.json'), 'utf-8'));
+		expect(config.version).toBe(3);
+
+		// Static files first, then EVERYTHING else (including the 404 catch-all
+		// route) goes to the SSR function.
+		const filesystemIndex = config.routes.findIndex(
+			(r: Record<string, unknown>) => r.handle === 'filesystem',
+		);
+		const catchAllIndex = config.routes.findIndex(
+			(r: Record<string, unknown>) => r.src === '/.*' && r.dest === '/index',
+		);
+		expect(filesystemIndex).toBeGreaterThanOrEqual(0);
+		expect(catchAllIndex).toBe(filesystemIndex + 1);
+
+		// Hashed assets are immutable, applied BEFORE the filesystem handler.
+		const assetsRoute = config.routes.find((r: Record<string, unknown>) => r.src === '/assets/.+');
+		expect(assetsRoute).toMatchObject({
+			headers: { 'Cache-Control': 'public, max-age=31536000, immutable' },
+			continue: true,
+		});
+		expect(config.routes.indexOf(assetsRoute)).toBeLessThan(filesystemIndex);
+	});
+
+	it('copies the client bundle to static/ (no index.html to shadow SSR)', () => {
+		expect(fs.existsSync(path.join(outputDir, 'static/assets/app-abc.js'))).toBe(true);
+		expect(fs.existsSync(path.join(outputDir, 'static/index.html'))).toBe(false);
+	});
+
+	it('emits the serverless function: dist/server verbatim + wrapper + config', () => {
+		for (const file of ['index.js', 'entry.js', 'index.html', '.vc-config.json', 'package.json']) {
+			expect(fs.existsSync(path.join(funcDir, file)), file).toBe(true);
+		}
+
+		const vcConfig = JSON.parse(fs.readFileSync(path.join(funcDir, '.vc-config.json'), 'utf-8'));
+		expect(vcConfig.handler).toBe('index.js');
+		expect(vcConfig.launcherType).toBe('Nodejs');
+		expect(vcConfig.runtime).toMatch(/^nodejs(20|22|24)\.x$/);
+
+		// The wrapper imports as ESM — the function dir must say so.
+		const pkg = JSON.parse(fs.readFileSync(path.join(funcDir, 'package.json'), 'utf-8'));
+		expect(pkg.type).toBe('module');
+	});
+
+	it('emitted function entry serves requests through the bundled handler', async () => {
+		const mod = await import(pathToFileURL(path.join(funcDir, 'index.js')).href);
+		const response = await mod.default.fetch(new Request('http://x/hello'));
+		expect(response.status).toBe(200);
+		expect(await response.text()).toBe('ok:/hello');
+	});
+});

package/tsconfig.typecheck.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "es2022",
+    "lib": ["esnext", "dom", "dom.iterable"],
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "types": ["node"],
+    "allowJs": true,
+    "checkJs": false
+  },
+  "include": ["src/**/*", "types/**/*", "tests/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/types/index.d.ts

@@ -0,0 +1,79 @@
+import type { OctaneAdapter, AdaptContext } from '@octanejs/vite-plugin';
+
+// ============================================================================
+// Adapter options
+// ============================================================================
+
+/** Serverless function configuration (functions/index.func/.vc-config.json). */
+export interface ServerlessConfig {
+	/**
+	 * Node.js runtime version for the function.
+	 * @default auto-detected from the build machine's Node major (20/22/24)
+	 */
+	runtime?: string;
+	/** Regions to deploy the function to (e.g. ['iad1']). */
+	regions?: string[];
+	/** Maximum execution duration in seconds. */
+	maxDuration?: number;
+	/** Memory in MB allocated to the function. */
+	memory?: number;
+}
+
+/** Incremental Static Regeneration — edge-cache the SSR response. */
+export interface ISRConfig {
+	/** Seconds before the cached response regenerates; `false` = never expires. */
+	expiration: number | false;
+	/** Token bypassing the cache (`__prerender_bypass` cookie / revalidate header). */
+	bypassToken?: string;
+	/** Query params that are part of the cache key. */
+	allowQuery?: string[];
+}
+
+export interface VercelAdapterOptions {
+	serverless?: ServerlessConfig;
+	isr?: ISRConfig;
+	/** @default true */
+	cleanUrls?: boolean;
+	trailingSlash?: boolean;
+	/** Vercel image optimization config (passed through to config.json). */
+	images?: Record<string, unknown>;
+	/** Extra response headers, matched by regex source. */
+	headers?: Array<{ source: string; headers: Array<{ key: string; value: string }> }>;
+	/** Redirects, matched by regex source. */
+	redirects?: Array<{ source: string; destination: string; permanent?: boolean }>;
+}
+
+// ============================================================================
+// Build Output API v3 shapes (what adapt() writes)
+// ============================================================================
+
+export interface VercelRoute {
+	src?: string;
+	dest?: string;
+	headers?: Record<string, string>;
+	status?: number;
+	continue?: boolean;
+	handle?: string;
+}
+
+export interface VercelConfig {
+	version: 3;
+	routes: VercelRoute[];
+	cleanUrls?: boolean;
+	trailingSlash?: boolean;
+	images?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Entry points
+// ============================================================================
+
+/**
+ * The octane.config.ts adapter: @octanejs/vite-plugin runs its `adapt()` after
+ * `vite build` produces dist/client + dist/server, emitting `.vercel/output/`
+ * (Build Output API v3).
+ */
+export function vercel(options?: VercelAdapterOptions): OctaneAdapter;
+
+/** The emitter itself — callable directly with an explicit build context. */
+export function adapt(ctx: AdaptContext, options?: VercelAdapterOptions): Promise<void>;