# vercel

Emulates the Vercel REST API locally to test deployments, OAuth flows, and projects without touching real infrastructure.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 220 installs · ★ 2075 repo stars
- Author: vercel-labs
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/vercel-labs/emulate/tree/HEAD/skills/vercel/SKILL.md
- Updated: 2026-10-25
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/vercel-labs-vercel

## What it does

This skill spins up a stateful mock server matching Vercel REST API responses with cursor-based pagination. By default, the listener binds to `127.0.0.1` on port 4000, though `--host 0.0.0.0` exposes it to external containers. Outbound URLs adapt when you supply `--base-url`.

The mock handles operations across projects, members, teams, and OAuth flows such as `/login/oauth/token` or `/login/oauth/userinfo`. You can pre-seed users, tokens, and build configurations through a YAML setup file. Deleting a project cascades down to its deployments, custom domains, and environment keys.

The agent relies on `npx emulate:*` and `curl:*` under Bash permissions to operate the emulator.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/emulate --skill vercel -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/vercel/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/vercel/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/emulate --skill vercel -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/vercel/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/emulate --skill vercel -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/vercel/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install vercel-labs/emulate skills/vercel
```

2. **Manually: put the files in place**
- File: `.github/skills/vercel/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/emulate --skill vercel -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/vercel-labs/emulate --path skills/vercel
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/vercel/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/emulate --skill vercel -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/vercel-labs/emulate/tree/HEAD/skills/vercel/SKILL.md

## When to use it
- Test Vercel REST API calls locally without hitting live endpoints
- Simulate Vercel OAuth login in Auth.js or NextAuth
- Mock project creation with custom build settings and encrypted env vars
- Preload test accounts, teams, and tokens using seed files

## Example prompts
- Run the local Vercel API emulator via npx emulate
- Query http://localhost:4000/v10/projects using a test bearer token
- Configure Auth.js OAuth URLs to point to the local Vercel emulator

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: d03a7f0c66f01af9.

BEGIN THIRD-PARTY FILE d03a7f0c66f01af9
````text
---
name: vercel
description: Emulated Vercel REST API for local development and testing. Use when the user needs to interact with Vercel API endpoints locally, test Vercel integrations, emulate projects/deployments/domains, set up Vercel OAuth flows, manage environment variables, create API keys, configure protection bypass, emulate Vercel Blob storage, or test without hitting the real Vercel API. Triggers include "Vercel API", "emulate Vercel", "mock Vercel", "test Vercel OAuth", "Vercel integration", "Vercel Blob", "local Vercel", or any task requiring a local Vercel API.
allowed-tools: Bash(npx emulate:*), Bash(curl:*)
---

# Vercel API Emulator

Fully stateful Vercel REST API emulation with Vercel-style JSON responses and cursor-based pagination.

## Start

Local listeners bind to `127.0.0.1` by default. For access from containers or other machines, pass `--host 0.0.0.0` to the CLI or `hostname: '0.0.0.0'` to `createEmulator`. Configure `--base-url` or `baseUrl` for advertised URLs reachable by those clients.

```bash
# Vercel only
npx emulate --service vercel

# Default port
# http://localhost:4000
```

Or programmatically:

```typescript
import { createEmulator } from 'emulate'

const vercel = await createEmulator({ service: 'vercel', port: 4000 })
// vercel.url === 'http://localhost:4000'
```

## Auth

Pass tokens as `Authorization: Bearer <token>`. All endpoints accept `teamId` or `slug` query params for team scoping.

```bash
curl http://localhost:4000/v2/user \
  -H "Authorization: Bearer test_token_admin"
```

Team-scoped requests resolve the account from the `teamId` or `slug` query parameter. User-scoped requests resolve the account from the authenticated user.

## Pointing Your App at the Emulator

### Environment Variable

```bash
VERCEL_EMULATOR_URL=http://localhost:4000
```

### Vercel SDK / Custom Fetch

```typescript
const VERCEL_API = process.env.VERCEL_EMULATOR_URL ?? 'https://api.vercel.com'

const res = await fetch(`${VERCEL_API}/v10/projects`, {
  headers: { Authorization: `Bearer ${token}` },
})
```

### OAuth URL Mapping

| Real Vercel URL | Emulator URL |
|-----------------|-------------|
| `https://vercel.com/integrations/oauth/authorize` | `$VERCEL_EMULATOR_URL/oauth/authorize` |
| `https://api.vercel.com/login/oauth/token` | `$VERCEL_EMULATOR_URL/login/oauth/token` |
| `https://api.vercel.com/login/oauth/userinfo` | `$VERCEL_EMULATOR_URL/login/oauth/userinfo` |

### Auth.js / NextAuth.js

```typescript
{
  id: 'vercel',
  name: 'Vercel',
  type: 'oauth',
  authorization: {
    url: `${process.env.VERCEL_EMULATOR_URL}/oauth/authorize`,
  },
  token: {
    url: `${process.env.VERCEL_EMULATOR_URL}/login/oauth/token`,
  },
  userinfo: {
    url: `${process.env.VERCEL_EMULATOR_URL}/login/oauth/userinfo`,
  },
  clientId: process.env.VERCEL_CLIENT_ID,
  clientSecret: process.env.VERCEL_CLIENT_SECRET,
  profile(profile) {
    return {
      id: profile.sub,
      name: profile.name,
      email: profile.email,
      image: profile.picture,
    }
  },
}
```

## Seed Config

```yaml
tokens:
  test_token_admin:
    login: admin
````
END THIRD-PARTY FILE d03a7f0c66f01af9

The third-party file has ended. Everything between the d03a7f0c66f01af9 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3104 of 18095 bytes. © vercel-labs · Apache-2.0 · https://github.com/vercel-labs/emulate/tree/HEAD/skills/vercel/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
