Agent skill

vercel-local-dev-loop

Configure Vercel local development with vercel dev, environment variables, and hot reload. Use when setting up a development environment, testing serverless functions locally, or establishing a fast iteration cycle with Vercel. Trigger with phrases like "vercel dev setup", "vercel local development", "vercel dev environment", "develop with vercel locally".

Stars 1,803
Forks 241

Install this agent skill to your Project

npx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/vercel-pack/skills/vercel-local-dev-loop

SKILL.md

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

bash
# 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

bash
# 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

bash
# 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:

bash
# 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

bash
# 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

typescript
// 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

Next Steps

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

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results