Vercel Local Dev Loop

Overview

Run Vercel serverless functions and API routes locally using

vercel dev

Prerequisites

• Completed

  vercel-install-auth

  setup
• Project linked via

  vercel link

• Node.js 18+ with npm/pnpm

Instructions

Step 1: Pull Environment Variables

# Pull env vars from Vercel to local .env files
vercel env pull .env.development.local

# This creates .env.development.local with all Development-scoped vars:
# VERCEL="1"
# VERCEL_ENV="development"
# DATABASE_URL="postgres://..."
# API_SECRET="sk-..."

Step 2: Start Local Dev Server

# vercel dev starts a local server that emulates the Vercel platform
vercel dev

# Output:
# Vercel CLI 39.x.x — dev command
# > Ready on http://localhost:3000

# With a specific port
vercel dev --listen 8080

# With debug logging
vercel dev --debug

vercel dev

• Serverless function emulation at

  /api/*

  routes
• Automatic TypeScript compilation

• vercel.json

  rewrites, redirects, and headers applied locally
• Environment variables loaded from

  .env*.local

  files
• Framework detection (Next.js, Nuxt, SvelteKit, etc.)

Step 3: Test Serverless Functions Locally

# Test your API route
curl http://localhost:3000/api/hello
# {"message":"Hello from Vercel Serverless Function!"}

# Test with POST body
curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"test","email":"test@example.com"}'

# Test with query parameters
curl "http://localhost:3000/api/search?q=vercel&limit=10"

Step 4: Framework-Specific Dev Servers

For frameworks with their own dev server, use those instead of

vercel dev

# Next.js — built-in Vercel compatibility
npx next dev
# API routes at pages/api/* or app/api/* work identically

# Nuxt
npx nuxi dev

# SvelteKit
npm run dev

# Astro
npx astro dev

The framework dev servers handle API routes natively. Use

vercel dev

Step 5: Local Environment Variable Management

# Add a new env var for development only
vercel env add MY_VAR development
# Prompts for value, stores encrypted on Vercel

# List all env vars
vercel env ls

# Remove an env var
vercel env rm MY_VAR development

# Pull updated vars after changes
vercel env pull .env.development.local

Step 6: Testing with Vitest

// api/__tests__/hello.test.ts
import { describe, it, expect, vi } from 'vitest';

// Mock the Vercel request/response
function createMockReq(overrides = {}) {
  return { method: 'GET', query: {}, body: null, ...overrides };
}

function createMockRes() {
  const res: any = {};
  res.status = vi.fn().mockReturnValue(res);
  res.json = vi.fn().mockReturnValue(res);
  res.send = vi.fn().mockReturnValue(res);
  return res;
}

describe('GET /api/hello', () => {
  it('returns 200 with message', async () => {
    const handler = (await import('../hello')).default;
    const req = createMockReq();
    const res = createMockRes();

    handler(req, res);

    expect(res.status).toHaveBeenCalledWith(200);
    expect(res.json).toHaveBeenCalledWith(
      expect.objectContaining({ message: expect.any(String) })
    );
  });
});

.env

File Hierarchy

Vercel loads environment files in this order (later files override earlier):

.env

.env.local

.env.development

.env.development.local

Output

• Local dev server running with serverless function emulation
• Environment variables synced from Vercel to local

  .env

  files
• Hot reload on file changes
• Test suite for serverless function handlers

Error Handling

vercel dev

--listen 8080

Error: No framework detected

api/

vercel env pull .env.development.local

FUNCTION_INVOCATION_TIMEOUT

api/

@vercel/node

npm install --save-dev @vercel/node

Resources

• Vercel Dev Command
• Environment Variables
• Vercel Functions
• Vitest Documentation

Next Steps

Proceed to

vercel-sdk-patterns