Vercel

Vercube targets the standard Web Request / Response APIs. That lines up with Vercel Functions that use a fetch handler on the Node.js runtime: you ship one serverless function and route all HTTP traffic to it.

This guide assumes a typical Vercube entry file that:

• boots the app with createApp() (and your container setup),
• calls app.listen() only when import.meta.main is true (local dev / node dist/index.mjs),
• exports default: { fetch: app.fetch.bind(app) } so a platform can drive the app without listen().

If your entry file does not export that object yet, add it before deploying.

1. Production build

Vercel should run the same build you use locally. The CLI writes a Node ESM bundle to dist/index.mjs by default (see Configuration for build.output / build.entry).

In package.json:

{
  "scripts": {
    "build": "vercube build"
  },
  "engines": {
    "node": ">=22"
  }
}

In the Vercel project settings, set Build Command to pnpm build, npm run build, or bun run build-whatever matches your package manager. You do not need a separate "Output Directory" for static assets unless you also deploy a frontend; the API bundle lives under dist/ and is loaded by the function below.

2. Vercel function wrapper

Vercel discovers handlers under /api. Add a small file that re-exports your built app (so the platform invokes fetch on every request):

import handler from '../dist/index.mjs';

export default handler;

import handler from '../dist/index.mjs';

export default handler;

Ensure the Install + Build steps run before the function is bundled so dist/index.mjs exists.

3. Route everything to the function

Add a vercel.json at the repository root so paths like /api/foo and / both reach the same handler (adjust if you expose static files or multiple functions):

{
  "rewrites": [{ "source": "/(.*)", "destination": "/api" }]
}

4. Environment variables

Configure secrets and config in the Vercel dashboard (Settings → Environment Variables). They are exposed to the Node runtime as process.env like anywhere else.

Use Production / Preview / Development scopes as appropriate so local .env and Vercel stay in sync conceptually.

5. Node.js version on Vercel

Vercube expects Node.js 22+ (see the monorepo engines field). On Vercel, set the major version explicitly:

• Project → Settings → General → Node.js Version, or
• engines.node in package.json as shown above.

Mismatch here is a common source of "works locally, fails on Vercel".

Pitfalls and limitations

• Cold starts - The first request after idle time pays serverless startup cost. Keep module scope lean; avoid heavy work at import time except what you truly need for every invocation.
• Execution time - Default function duration limits apply. Long-running requests or background work belong in queues, cron, or other services-not in a single HTTP invocation.
• WebSockets - Vercel’s serverless model is request/response oriented. Real-time patterns usually need a dedicated host or a Vercel-supported alternative; plan accordingly.
• Monorepos - If the app lives in a subdirectory, set Root Directory in the Vercel project to that package so vercube build and api/ resolve correctly.

Optional checks

• Run vercube build locally, then node dist/index.mjs and hit your routes.
• After deploy, hit a known route (for example from the base example, GET /api/foo) and confirm status codes and logs in the Vercel dashboard.