Reducing Next.js Cold Starts on Vercel

Why Next.js Cold Starts Matter for AI Agents

When you deploy an AI agent system on Vercel's serverless functions, every request to Claude through your Next.js API route triggers a cold start. Your function container spins up, Node.js initializes, dependencies load, and database connections establish. For users, this feels like your app is broken.

Indie teams building with Claude can't afford to lose users to timeout errors or perception of slowness. A 3-second cold start on a streaming response makes your agent feel unresponsive even if Claude replies instantly. The fix isn't about raw speed—it's about smart bundling, dependency management, and architecture choices.

Bundle Size: Your Biggest Lever

Next.js API routes ship your entire node_modules tree by default. If you're pulling in heavy dependencies (axios, moment, lodash), each cold start re-parses megabytes of JavaScript. The Vercel platform measures cold start time in seconds per 100MB of bundle size.

Audit your imports ruthlessly. Replace axios with fetch (built-in since Node 18). Use date-fns instead of moment. Import only what you need: `import { debounce } from 'lodash-es'` instead of the full lodash library. In Supabase integrations, use the lightweight '@supabase/supabase-js' client, not additional auth libraries.

Target: Keep your API route bundle under 5MB. Use `next/bundle-analyzer` to visualize what's bloating your functions.

Connection Pooling for Supabase

Every cold start creates a fresh Supabase client and establishes a new database connection. With dozens of concurrent requests, your Supabase connection pool exhausts instantly, and subsequent requests queue or fail.

Use PgBouncer connection pooling (included free with Supabase Pro) and reuse client instances across invocations via global scope. Initialize your Supabase client outside your API handler so it persists across warm invocations.

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_KEY!);

export async function POST(req: Request) {
  const { data } = await supabase.from('messages').insert({ content: 'test' });
  return Response.json(data);
}

Serverless Function Optimization

Vercel's Edge Functions (running Cloudflare Workers runtime) have 50MB limits but initialize in milliseconds instead of seconds. Move lightweight auth checks, request filtering, and response transformation to Edge Middleware. Keep Claude API calls in serverless functions where you have full Node.js runtime.

Use `maxDuration` sparingly—the longer your function timeout, the longer Vercel keeps resources allocated. Set it to the minimum needed (e.g., 30s for streaming Claude responses, not 60s).

Monitoring and Measuring Cold Starts

You can't optimize what you don't measure. Vercel's Analytics dashboard shows cold start distribution, but add custom logging to pinpoint bottlenecks. Log the timestamp at function entry and after each critical section (imports, DB connection, Claude API call).

Expect 300-800ms for a well-optimized cold start on Vercel's standard tier. Anything under 500ms is production-ready for AI agents where users expect streaming responses.

Open-Source Implementation

The Pantheon project (github.com/lewisallena17/pantheon) is a reference implementation combining Next.js, Supabase, and Claude API with cold start optimization built in from the ground up. It includes bundling config, connection pooling setup, and Edge Middleware examples you can fork and customize for your AI agent system.

Open-source implementation

Everything in this article runs in pantheon — a production-ready Next.js + Supabase + Claude starter. Clone it, deploy to Vercel, run PM2. The dashboard auto-commits every agent edit and reverts itself if TypeScript breaks.