vercel-local-dev-loop

Vercel Local Dev Loop

Overview

Run Vercel serverless functions and API routes locally using vercel dev. Covers environment variable management, hot reload, local testing patterns, and framework-specific dev servers.

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 provides:

• 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":"[email protected]"}'

# 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 only for plain serverless function projects without a framework.

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):

File	Environment	Git
.env	All	Commit
.env.local	All (local only)	Ignore
.env.development	Development	Commit
.env.development.local	Development (local only)	Ignore

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

Error	Cause	Solution
vercel dev hangs on start	Port already in use	Kill the process on port 3000 or use --listen 8080
Error: No framework detected	Missing package.json or framework	Add a build framework or use plain functions in api/
Env var undefined locally	Not pulled from Vercel	Run vercel env pull .env.development.local
FUNCTION_INVOCATION_TIMEOUT	Function exceeds 10s locally	Check for unresolved promises or infinite loops
TypeScript errors in api/	Missing @vercel/node types	npm install --save-dev @vercel/node

Resources

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

Next Steps

Proceed to vercel-sdk-patterns for production-ready REST API integration patterns.