Expert Vercel Bot

Your specialized agent for deploying, configuring, and optimizing applications on the Vercel platform, covering Next.js deployments, edge functions, environment variables, and Vercel-specific features.

When to Use This Agent

Choose Expert Vercel Bot when:

• Deploying Next.js, SvelteKit, Nuxt, or other frameworks to Vercel
• Configuring Vercel project settings (domains, environment variables, build commands)
• Optimizing Vercel deployments (edge functions, ISR, image optimization, caching)
• Troubleshooting build failures, preview deployments, or serverless function issues
• Setting up Vercel CI/CD workflows with GitHub/GitLab integration

Consider alternatives when:

• You need general Next.js development help — use a Next.js agent
• You're deploying to AWS/Azure/GCP instead — use a cloud-specific agent
• You need infrastructure-as-code for Vercel — consider the Vercel Terraform provider

Quick Start

Copy
# .claude/agents/vercel-expert.yml
name: Expert Vercel Bot
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Vercel platform specialist for deployments, edge functions, and Next.js optimization

Example invocation:

claude "Configure our Next.js app for Vercel with ISR, edge middleware for geo-routing, and environment variables for staging and production"

Core Concepts

Vercel Project Configuration

Copy
// vercel.json
{
  "framework": "nextjs",
  "buildCommand": "next build",
  "outputDirectory": ".next",
  "regions": ["iad1", "sfo1"],
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "s-maxage=60, stale-while-revalidate" }
      ]
    }
  ],
  "rewrites": [
    { "source": "/blog/:slug", "destination": "/api/blog/:slug" }
  ]
}

Vercel Feature Map

Feature	Use Case	Configuration
Edge Functions	Low-latency middleware, geo-routing	export const runtime = 'edge'
ISR	Stale-while-revalidate page caching	revalidate: 60 in getStaticProps
Serverless Functions	API routes, webhooks	/api/** directory
Preview Deployments	PR-based staging environments	Automatic on PR push
Edge Config	Real-time feature flags, A/B tests	@vercel/edge-config package
Image Optimization	Responsive images, WebP/AVIF	next/image component

Configuration

Parameter	Description	Default
framework	Project framework (nextjs, sveltekit, nuxt)	nextjs
regions	Deployment regions	iad1
node_version	Node.js runtime version	20.x
build_command	Custom build command	auto-detected
function_max_duration	Serverless function timeout (seconds)	10

Best Practices

1. Use Edge Functions for latency-sensitive middleware. Authentication checks, geo-routing, A/B testing, and bot detection run faster at the edge than in serverless functions. Keep edge functions small — they have a 128KB code limit and limited API surface.

2. Configure ISR with appropriate revalidation windows. Pages that change hourly don't need 10-second revalidation. Match the revalidation period to your content update frequency. Use on-demand revalidation (res.revalidate()) for webhook-triggered updates instead of short polling intervals.

3. Separate environment variables by deployment context. Vercel supports Production, Preview, and Development environment scopes. Never share production API keys with preview deployments — use distinct credentials per environment to limit blast radius.

4. Set function regions close to your data. Serverless functions should run in the same region as your database to minimize latency. A function in iad1 (Virginia) calling a database in eu-west-1 (Ireland) adds 80-100ms of round-trip latency per query.

5. Use Vercel's build cache effectively. Enable turbo remote caching for monorepos, and avoid npm install in custom build scripts when Vercel already handles dependency installation. Each cache miss adds 30-60 seconds to your build.

Common Issues

Serverless function times out on cold start. Large function bundles (especially with heavy dependencies) increase cold start time. Reduce bundle size by tree-shaking, moving heavy processing to background jobs, and splitting API routes into smaller functions. Set maxDuration only as high as genuinely needed.

Preview deployment uses production environment variables. By default, preview deployments inherit Production-scoped variables if no Preview-scoped override exists. Always create Preview-scoped variables for sensitive values like API keys and database URLs to prevent preview builds from touching production data.

Build succeeds locally but fails on Vercel. Differences in Node.js version, OS (Vercel runs Amazon Linux), or environment variables cause this. Match your local Node version to Vercel's, ensure all environment variables are set in Vercel's dashboard, and check for case-sensitive file paths (Vercel's filesystem is case-sensitive, macOS isn't).