Vercel Cli

Vercel CLI Skill

The Vercel CLI (vercel or vc) deploys, manages, and develops projects on the Vercel platform from the command line. Use vercel <command> -h for full flag details on any command.

Critical: Project Linking

Commands must be run from the directory containing the .vercel folder (or a subdirectory of it). How .vercel gets set up depends on your project structure:

• `.vercel/project.json`: Created by vercel link. Links a single project. Fine for single-project repos, and can work in monorepos if there's only one project.
• `.vercel/repo.json`: Created by vercel link --repo. Links a repo that may contain multiple projects. Always a good idea when any project has a non-root directory (e.g., apps/web).

Running from a project subdirectory (e.g., apps/web/) skips the "which project?" prompt since it's unambiguous.

When something goes wrong, check how things are linked first — look at what's in .vercel/ and whether it's project.json or repo.json. Also verify you're on the right team with vercel whoami — linking while on the wrong team is a common mistake.

Quick Start

npm i -g vercel
vercel login
vercel link              # single project
# OR
vercel link --repo       # monorepo
vercel pull
vercel dev        # local development
vercel deploy     # preview deployment
vercel --prod     # production deployment

Decision Tree

Use this to route to the correct reference file:

• Deploy → references/deployment.md
• Local development → references/local-development.md
• Environment variables → references/environment-variables.md
• CI/CD automation → references/ci-automation.md
• Domains or DNS → references/domains-and-dns.md
• Projects or teams → references/projects-and-teams.md
• Logs, metrics, debugging, or accessing preview deploys → references/monitoring-and-debugging.md
• Blob storage → references/storage.md
• Integrations (databases, storage, etc.) → references/integrations.md
• Access a preview deployment → use vercel curl (see references/monitoring-and-debugging.md)
• CLI doesn't have a command for it → use vercel api as a fallback (see references/advanced.md)
• Node.js backends (Express, Hono, etc.) → references/node-backends.md
• Monorepos (Turborepo, Nx, workspaces) → references/monorepos.md
• Bun runtime → references/bun.md
• Feature flags → references/flags.md
• Advanced (API, webhooks) → references/advanced.md
• Global flags → references/global-options.md
• First-time setup → references/getting-started.md

Anti-Patterns

• Wrong link type in monorepos with multiple projects: vercel link creates project.json, which only tracks one project. Use vercel link --repo instead. When things break, check .vercel/ first.
• Letting commands auto-link in monorepos: Many commands implicitly run vercel link if .vercel/ doesn't exist. This creates project.json, which may be wrong. Run vercel link (or --repo) explicitly first.
• Linking while on the wrong team: Use vercel whoami to check, vercel teams switch to change.
• Forgetting `--yes` in CI: Required to skip interactive prompts.
• Using `vercel deploy` after `vercel build` without `--prebuilt`: The build output is ignored.
• Hardcoding tokens in flags: Use VERCEL_TOKEN env var instead of --token.
• Disabling deployment protection: Use vercel curl instead to access preview deploys.

Load the Vercel CLI skill and help with project deployment and management.

Workflow

Step 1: Load vercel-cli skill

skill({ name: 'vercel-cli' })

Step 2: Identify task type from user request

Use the decision tree in SKILL.md to select the relevant reference file.

Step 3: Read the reference file

Based on task type, read references/<topic>.md. Use vercel <command> -h for full flag details.

Step 4: Execute task

Key things to verify:

• Project is linked (.vercel/ directory exists)
• Env vars are pulled if needed (vercel pull)
• Use --yes in CI/agent contexts
• Use VERCEL_TOKEN env var for auth (not --token)
• Use vercel curl to access preview deployments (don't disable protection)

Step 5: Summarize

=== Vercel CLI Task Complete ===

Topic: <topic>
<brief summary of what was done>

<user-request> $ARGUMENTS </user-request>

Advanced Commands

vercel api — Fallback for Missing CLI Commands

Use `vercel api` when a CLI command doesn't exist for what you need. Full access to the Vercel REST API with automatic authentication.

vercel api /v2/user                                    # GET current user
vercel api /v9/projects --scope my-team                # list projects
vercel api /v10/projects -X POST -F name=my-project    # create project
vercel api /v6/deployments --paginate                  # paginate all results
vercel api ls                                          # list available endpoints

Use vercel api ls to discover available endpoints.

Other Commands

• vercel webhooks — manage webhooks (create, ls, rm)
• vercel mcp — set up MCP integration for AI agents
• vercel telemetry — manage telemetry settings
• vercel upgrade — upgrade the CLI

Bun on Vercel

Vercel supports Bun as a runtime. To enable it, add "bunVersion": "1.x" to your vercel.json:

{
  "bunVersion": "1.x"
}

That's it. Vercel will use Bun instead of Node.js to run your project.

This works with any framework — backend apps (Express, Hono, Elysia), frontend frameworks, or anything else. Bun is used as the runtime, so Bun-specific APIs and features are available.

Example: Elysia with Bun

Elysia is a Bun-native framework. To use it on Vercel:

vercel.json:

{
  "bunVersion": "1.x"
}

package.json:

{
  "type": "module",
  "dependencies": {
    "elysia": "^1.0.0"
  }
}

server.ts:

import { Elysia } from 'elysia';

const app = new Elysia().get('/', () => 'Hello Elysia!');

export default app;

Example: Next.js with Bun

vercel.json:

{
  "bunVersion": "1.x"
}

package.json:

{
  "scripts": {
    "dev": "bun run --bun next dev",
    "build": "bun run --bun next build"
  }
}

Anti-Patterns

• Forgetting `bunVersion` in `vercel.json`: Without it, your project runs on Node.js. Bun-specific APIs (like Bun.file()) will fail at runtime.

CI/CD Automation

Authentication

Use VERCEL_TOKEN env var (not --token — it leaks in process listings). Use --scope if the token has access to multiple teams.

The Standard CI Deploy Pattern

vercel pull --yes --environment=production
vercel build --prod
vercel deploy --prebuilt --prod

For multi-project monorepos, ensure vercel link --repo --yes has been run first.

Separate Build and Deploy Jobs

Use --standalone so build artifacts are self-contained and can be passed between jobs:

jobs:
  build:
    steps:
      - run: vercel pull --yes --environment=production
      - run: vercel build --prod --standalone
      - uses: actions/upload-artifact@v4
        with:
          name: vercel-build
          path: .vercel/output

  deploy:
    needs: build
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: vercel-build
          path: .vercel/output
      - run: vercel deploy --prebuilt --prod

Without --standalone, the deploy job will fail because artifacts reference files outside .vercel/output/.

Capturing the Deploy URL

URL=$(vercel deploy --prod)   # stdout = URL, stderr = progress

Key Rules

1. Always use --yes to skip prompts 2. Always use VERCEL_TOKEN env var for auth 3. Use --scope if the token has access to multiple teams 4. Use vercel build + vercel deploy --prebuilt for deterministic builds 5. If something goes wrong, check .vercel/ — project.json vs repo.json is the most common issue

Deployment

Ensure .vercel/ exists before deploying (via vercel link or vercel link --repo).

Basic Usage

vercel                    # preview deployment (default)
vercel --prod             # production deployment
vercel --target staging   # custom environment

Prebuilt Deploy

Build locally, deploy the output — avoids remote builds:

vercel build --prod
vercel deploy --prebuilt --prod

If build and deploy run in separate CI jobs, use --standalone so artifacts are self-contained:

vercel build --prod --standalone
# (upload .vercel/output/ as artifact, then in deploy job:)
vercel deploy --prebuilt --prod

Deploy Output

• stdout: The deployment URL (pipeable)
• stderr: Progress and errors

URL=$(vercel deploy --prod)

Accessing Preview Deployments

Use vercel curl — it handles deployment protection automatically:

vercel curl /api/health --deployment $PREVIEW_URL

Do not disable deployment protection. Use vercel curl instead.

Other Deploy Commands

• vercel redeploy <url> — rebuild an existing deployment
• vercel promote <url> — move a deployment to production without rebuilding
• vercel rollback <url> — revert to a previous deployment
• vercel rolling-release — gradual traffic shifting

Workflows

Blue/Green

URL=$(vercel --prod --skip-domain)   # deploy without domain assignment
vercel curl / --deployment $URL      # verify (handles deployment protection)
vercel promote $URL                  # promote to production

Rolling Release

vercel rr configure --enable --stage=10,5m --stage=50,10m --stage=100,0
vercel rr start --dpl=<deployment-url>
vercel rr status

Domains & DNS

Overview

• vercel domains — manage domain ownership and project assignment
• vercel dns — manage DNS records (when using Vercel nameservers)
• vercel alias — map deployment URLs to custom domains
• vercel certs — manage SSL certificates (usually auto-managed)

Most users only need vercel alias — domains and DNS are auto-configured when using Vercel nameservers.

Typical Flow

1. Add domain to project: vercel domains add example.com my-project 2. Configure nameservers at registrar to point to Vercel 3. Deploy: vercel --prod (domain is auto-assigned)

Or manually alias: vercel alias set <deployment-url> example.com

DNS Records

vercel dns ls example.com
vercel dns add example.com @ A 1.2.3.4
vercel dns add example.com sub CNAME target.example.com
vercel dns rm rec_abc123

Use vercel <command> -h for full flag details.

Environment Variables

Scoping

Env vars are scoped to environments: production, preview (can be branch-specific), and development.

Variables can be plain text or sensitive (encrypted, not readable after creation).

Managing Env Vars

vercel env add API_KEY production              # add to production
vercel env ls                                  # list all
vercel env update API_KEY production           # update value
vercel env rm API_KEY preview                  # remove from preview
echo "secret" | vercel env add TOKEN production  # pipe value from stdin

Note: environment is a positional argument, not a flag.

Pulling Locally

vercel env pull                   # writes to .env.local
vercel env pull .env.development  # writes to custom file

vercel pull also downloads env vars along with project config.

Running with Env Vars

Inject env vars into a subprocess without writing to a file:

vercel env run -- npm test
vercel env run -e preview -- next dev

The -- separator is required before the command.

Feature Flags

vercel flags manages Vercel Flags — create, inspect, update, set, enable, disable, archive, and delete feature flags, plus manage SDK keys.

Creating Flags

create is the primary command; add is an alias.

vercel flags create my-feature                            # create boolean flag
vercel flags create my-feature --kind string --description "My flag"  # string flag with description
vercel flags create my-feature --kind string --variant control="Welcome back" --variant treatment="New onboarding"  # with explicit variants

Flag kinds: boolean (default), string, number. Boolean flags get true/false variants automatically; use --variant VALUE[=LABEL] (repeatable) for string/number flags.

Listing and Inspecting

vercel flags list                                         # list active flags
vercel flags list --state archived                        # list archived flags
vercel flags list --json                                  # output as JSON
vercel flags inspect my-feature                           # show flag details

Opening in Dashboard

vercel flags open                                         # open project flags dashboard
vercel flags open my-feature                              # open a specific flag

Updating Flags

Update variant values, labels, or both on an existing flag.

vercel flags update my-feature --variant control --value welcome-back --label "Welcome back"
vercel flags update my-feature --variant control --label "Control" --message "Rename control variant"
vercel flags update my-feature --variant false --label "Disabled"

Options: --variant (variant ID or value), --value (new value), --label/-l (new label), --message (revision message).

Setting Served Variant

set controls which variant is served in a given environment. Works with all flag kinds.

vercel flags set welcome-message -e production --variant control
vercel flags set bucket-size -e preview --variant 20
vercel flags set my-feature -e development --variant true

Options: --environment/-e, --variant/-v, --message.

Enable / Disable (Boolean Shortcut)

Only works with boolean flags. Shortcuts that set the served variant to true or false.

vercel flags enable my-feature -e production
vercel flags enable my-feature -e production --message "Resume production rollout"
vercel flags disable my-feature -e production
vercel flags disable my-feature -e production --variant off
vercel flags disable my-feature -e production --message "Pause rollout"

Environments: production, preview, development. Omit -e to choose interactively.

Archive / Delete

vercel flags archive my-feature --yes                     # archive (skip prompt)
vercel flags rm my-feature --yes                          # delete (must be archived first)

SDK Keys

SDK keys authenticate your application when evaluating flags. The full key value is only shown at creation time.

vercel flags sdk-keys ls                                  # list SDK keys
vercel flags sdk-keys ls --json                           # list as JSON
vercel flags sdk-keys add --type server -e production     # create server key
vercel flags sdk-keys add --type client -e preview --label "Preview App"  # client key with label
vercel flags sdk-keys rm <hash-key> --yes                 # delete key

Getting Started

Install

npm i -g vercel

First-Time Setup

1. Authenticate — vercel login (opens browser). For CI, use VERCEL_TOKEN env var instead. 2. Check your team — vercel whoami to see current team. vercel teams switch to change. Linking on the wrong team is a common mistake. 3. Link your project — vercel link (single project) or vercel link --repo (monorepo with multiple projects or non-root directories). Creates .vercel/. 4. Pull env vars — vercel pull downloads project settings and env vars to .env.local. 5. Dev or deploy — vercel dev (local server) or vercel --prod (production deploy).

Project Linking

Commands must be run from the directory containing .vercel/ or a subdirectory of it.

• `.vercel/project.json`: Created by vercel link. Links a single project. Fine for single-project repos, and can work in monorepos if there's only one project.
• `.vercel/repo.json`: Created by vercel link --repo. Links a repo that may contain multiple projects. Always a good idea when any project has a non-root directory (e.g., apps/web).

Running from a project subdirectory (e.g., apps/web/) skips the "which project?" prompt.

When something goes wrong, check how things are linked first — look at .vercel/ and whether it's project.json or repo.json.

Global Options

Key flags available on every vercel command:

• --help / -h — show help for the command
• --debug / -d — enable debug output
• --cwd DIR — override working directory
• --scope SCOPE / --team SLUG — set team context (both do the same thing)
• --token TOKEN — auth token (prefer VERCEL_TOKEN env var instead)
• --yes / -y — skip confirmation prompts (required in CI)
• --non-interactive — suppress interactive prompts (auto-detected for agents/CI)

--non-interactive is auto-detected when stdin is not a TTY, so agents and CI get this behavior by default.

Prefer VERCEL_TOKEN env var over --token to avoid leaking secrets in shell history.

Integrations

What Are Integrations?

Integrations are third-party services provisioned through the Vercel Marketplace and automatically connected to your project via environment variables. Categories include: AI, Agents, Analytics, Authentication, CMS, Code Review, Code Security, Commerce, DevTools, Experimentation, Flags, Logging, Messaging, Monitoring, Observability, Payments, Productivity, Searching, Security, Storage, Support Agent, Testing, Video, Web Automation, and Workflow.

When to Recommend an Integration

• The project needs a database — Postgres, MySQL, Redis, etc. → vercel integration add
• The project needs a KV store, blob storage, or other managed service → vercel integration add
• The user is manually setting env vars for a third-party service that's available on the Marketplace — an integration handles provisioning and env var injection automatically
• The user wants to add observability, logging, or error tracking → check the Marketplace

The key benefit: integrations automatically provision the resource AND inject the right environment variables into your project. No manual env var setup needed.

When in doubt about flags or subcommands, use `--help`:

vercel integration -h                              # list subcommands
vercel integration add -h                          # flags for add
vercel ir -h                                       # integration-resource subcommands

Discovering Integrations

vercel integration discover                        # list all marketplace integrations
vercel integration discover --format=json          # as JSON

Adding an Integration

vercel integration add <slug>                      # install and provision
vercel integration add <slug>/<product>            # specific product (multi-product integrations)
vercel integration add <slug> --name my-db         # custom resource name

The CLI prompts for product selection when multiple products exist and no /<product> slug is given (errors in non-TTY — specify the product slug). Billing plan uses --plan or server default (no prompt). Metadata uses -m flags or server defaults (no prompt). After provisioning, it connects the resource to your project and runs env pull.

vercel install <slug> (or vercel i <slug>) is an alias — behaves identically.

Browser fallback: The CLI may open a browser in two cases: (1) first-time install requiring terms acceptance — the CLI polls and resumes automatically once the user accepts, so do not kill the process; and (2) non-provisionable integrations — the CLI exits with code 1, inform the user they need to finish in the browser.

Environments

vercel integration add <slug> -e production            # specific environment
vercel integration add <slug> -e production -e preview # multiple (repeatable)

Defaults to all environments (production, preview, development).

Metadata

Some integrations require configuration during provisioning (e.g., region, database version):

vercel integration add <slug> -m region=us-east-1
vercel integration add <slug> -m region=us-east-1 -m version=16

Plans

vercel integration add <slug> --plan <plan-id>         # specific billing plan
vercel integration add <slug> -p <plan-id>             # shorthand

Other Flags

vercel integration add <slug> --no-connect             # skip connecting to project (also skips env pull)
vercel integration add <slug> --no-env-pull            # skip env pull only
vercel integration add <slug> --prefix NEON2_          # prefix env var names (e.g., NEON2_DATABASE_URL)
vercel integration add <slug> --installation-id <id>   # use specific installation (multi-installation)
vercel integration add <slug> --format=json            # output as JSON

Listing Resources

Alias: vercel integration ls

vercel integration list                                # resources for linked project
vercel integration list --all                          # all resources across the team
vercel integration list -i <slug>                      # filter by integration
vercel integration list <project>                      # resources for a specific project
vercel integration list --format=json                  # as JSON

Opening Dashboards

vercel integration open <integration>                  # open integration dashboard (SSO)
vercel integration open <integration> <resource>       # open specific resource dashboard
vercel integration open <integration> --format=json    # get SSO link as JSON

Disconnecting

Use vercel integration-resource (alias: vercel ir):

vercel ir disconnect <resource>                        # disconnect from current project
vercel ir disconnect <resource> <project>              # disconnect from specific project
vercel ir disconnect <resource> --all                  # disconnect from all projects
vercel ir disconnect <resource> --yes                  # skip confirmation

Disconnecting removes environment variables from the project but does not delete the resource.

Note: --format=json requires --yes on destructive commands (ir disconnect, ir remove, integration remove) — the CLI rejects JSON output with interactive prompts.

Billing

Only applies to integrations with prepayment-type billing plans. Returns "no balance info available" for integrations without prepayment billing.

vercel integration balance <slug>                      # show balance and thresholds
vercel integration balance <slug> --format=json        # as JSON
vercel ir create-threshold <resource> <minimum> <spend> <limit>
vercel ir create-threshold <resource> <minimum> <spend> <limit> --yes  # skip confirmation

Threshold parameters (dollar amounts, e.g., 50 100 500):

• minimum — balance floor; auto-replenish triggers when balance drops below this
• spend — replenishment amount added when minimum is hit
• limit — hard spending cap

Works for both resource-level and installation-level thresholds (CLI auto-detects).

Guides

vercel integration guide <slug>                        # show setup guide
vercel integration guide <slug> --framework nextjs     # framework-specific (-f shorthand)
vercel integration guide <slug>/<product>              # specific product

After installing, pull credentials to .env.local:

vercel env pull                                        # pulls to .env.local

This runs automatically after vercel integration add (unless --no-env-pull).

Removing Resources

Alias: vercel ir rm

vercel ir remove <resource>                            # delete (must not be connected)
vercel ir remove <resource> --disconnect-all           # disconnect all projects, then delete
vercel ir remove <resource> --disconnect-all --yes     # skip confirmation

This permanently deletes the resource from the provider. Cannot be undone.

Uninstalling an Integration

vercel integration remove <slug>                       # uninstall (all resources must be deleted first)
vercel integration remove <slug> --yes                 # skip confirmation

Cleanup Workflow

vercel integration list --all -i <slug>                # find all resources
vercel ir remove <resource-1> --disconnect-all --yes   # delete each resource
vercel ir remove <resource-2> --disconnect-all --yes
vercel integration remove <slug> --yes                 # then uninstall

Local Development

Prerequisites

1. Link your project — vercel link or vercel link --repo (monorepo). Check your team first with vercel whoami. 2. Pull env vars — vercel pull or vercel env pull

Usage

vercel dev                           # default: 0.0.0.0:3000
vercel dev --listen 8080             # custom port
vercel dev --listen 127.0.0.1:5000   # custom host and port

Related Commands

• vercel link — connect to a Vercel project. Use --repo for multi-project monorepos.
• vercel pull — download project settings and env vars to .env.local
• vercel env pull — download only env vars (not project settings)
• vercel init — scaffold a new project from a Vercel example
• vercel open — open the Vercel dashboard for the linked project

Run vercel dev from a project subdirectory (e.g., apps/web/) to skip the project selection prompt.

Monitoring & Debugging

Logs

vercel logs <deployment-url>                   # view logs
vercel logs --follow                           # stream live
vercel logs --level error --level warn         # filter by severity
vercel logs --source lambda                    # filter by source (lambda, edge, static)
vercel logs --since 2024-01-01                 # filter by time
vercel logs --query "timeout"                  # search

Metrics

vercel metrics schema                                                    # list available metrics
vercel metrics schema vercel.function_invocation                         # inspect a metric prefix
vercel metrics vercel.function_invocation.count --since 1h               # query linked project
vercel metrics vercel.request.count --group-by http_status --since 6h    # group by schema dimension
vercel metrics vercel.function_invocation.request_duration_ms -a avg --group-by route --since 1h
vercel metrics vercel.ai_gateway_request.cost -a sum --group-by ai_provider --since 7d
vercel metrics vercel.speed_insights_metric.lcp -a p75 --group-by route --since 7d
vercel metrics --all vercel.function_invocation.count --group-by project_id --since 24h
vercel metrics vercel.function_invocation.count -f "http_status ge 500" --group-by error_code --since 1h --format=json

Inspecting Deployments

vercel inspect <url>               # deployment details
vercel inspect <url> --wait        # wait for completion
vercel inspect <url> --logs        # show build logs

vercel curl — Access Preview Deployments

Use `vercel curl` to access preview deploys. It handles deployment protection automatically — no need to disable protection or manage bypass secrets.

vercel curl /api/health --deployment $PREVIEW_URL
vercel curl /api/data --deployment $PREVIEW_URL -- -X POST -d '{"key":"value"}'

Do not disable deployment protection. Use vercel curl instead.

Finding Regressions

vercel bisect performs a binary search across deployments to find which one introduced a problem:

vercel bisect --good <url> --bad <url> --path /api/users
vercel bisect --run ./test-script.sh    # automated testing

Cache

vercel cache purge                    # purge CDN cache
vercel cache invalidate --tag mytag   # invalidate by cache tag

Monorepos on Vercel

Vercel auto-detects monorepo tools (Turborepo, Nx) and workspace managers (pnpm, Yarn, npm). Each project in the monorepo gets its own Vercel project, linked via vercel link --repo.

Quick Start

vercel link --repo    # link the whole repo
vercel pull           # pull env vars
vc dev                # local development
vercel deploy         # deploy

Linking

Use vercel link --repo to create .vercel/repo.json, which maps directories to Vercel projects:

{
  "orgId": "org_xxxxx",
  "projects": [
    { "id": "prj_xxxxx", "name": "web", "directory": "apps/web" },
    { "id": "prj_yyyyy", "name": "api", "directory": "apps/api" }
  ]
}

Running from a project subdirectory (e.g., apps/web/) skips the "which project?" prompt.

Root Directory

Set rootDirectory in vercel.json when your app isn't at the repo root:

{
  "rootDirectory": "apps/api"
}

Turborepo

Turborepo requires an explicit build task. Define it in turbo.json:

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "env": ["VERCEL"],
      "outputs": [".next/**", "!.next/cache/**", ".vercel/output/**", "dist/**"]
    }
  }
}

Vercel automatically generates the right build command — you don't need to configure it. If you need a manual override in vercel.json:

{
  "buildCommand": "turbo run build --filter={packages/my-app}..."
}

turbo-ignore

Vercel auto-sets npx turbo-ignore as the "Ignored Build Step" command, which skips builds when a project's dependencies haven't changed.

Nx

Nx requires a build target. Define it in nx.json:

{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

Example: Turborepo + pnpm + Hono

root/
├── turbo.json
├── package.json
├── pnpm-workspace.yaml
├── vercel.json
├── apps/
│   └── api/
│       ├── package.json
│       └── server.ts
└── packages/
    └── shared/
        ├── package.json
        └── src/index.ts

pnpm-workspace.yaml:

packages:
  - 'apps/*'
  - 'packages/*'

vercel.json:

{
  "rootDirectory": "apps/api"
}

apps/api/server.ts:

import { Hono } from 'hono';
import { greet } from '@repo/shared';

const app = new Hono();
app.get('/', c => c.text(greet('world')));

export default app;

Anti-Patterns

• Using `vercel link` instead of `vercel link --repo`: Creates project.json which only tracks one project. Use --repo for monorepos.
• Missing `build` task in turbo.json/nx.json: Vercel requires an explicit build task. Without it, the build fails.
• Adding a `build` script to package.json for transpilation: Vercel handles TypeScript compilation. The turbo.json build task is for orchestration, not transpilation.
• Linking while on the wrong team: Use vercel whoami to check, vercel teams switch to change.

Node Backends on Vercel

Vercel supports Node.js backend frameworks as first-class apps. Express and Hono are the most common, but Fastify, Elysia, NestJS, H3, and Koa are also supported. Your app is the entrypoint — not the api/ folder. No rewrites, no build scripts. Just export your app and deploy.

Quick Start

# Express
npm init -y && npm i express
# Create server.ts that exports default app
vc dev       # local development
vc deploy    # deploy

How It Works

1. Vercel detects the framework from package.json dependencies 2. Finds your entrypoint file (must import the framework) 3. Introspects your routes automatically — no vercel.json rewrites needed 4. Bundles and deploys as a single Lambda

Entrypoint Detection

Vercel searches for these filenames (in order): app, index, server, main, src/app, src/index, src/server, src/main

With these extensions: .js, .cjs, .mjs, .ts, .cts, .mts

The preferred entrypoint filename is server.ts. The file must import the framework (import express from 'express', import { Hono } from 'hono', etc.).

We recommend using export default for the app instance, but calling .listen() also works.

Minimal Express App

my-app/
├── package.json
└── server.ts

package.json:

{
  "type": "module",
  "dependencies": {
    "express": "5.1.0"
  }
}

server.ts:

import express from 'express';

const app = express();

app.get('/', (_req, res) => {
  res.send('Hello Express!');
});

export default app;

Minimal Hono App

package.json:

{
  "type": "module",
  "dependencies": {
    "hono": "^4.8.9"
  }
}

server.ts:

import { Hono } from 'hono';

const app = new Hono();

app.get('/', c => {
  return c.text('Hello Hono!');
});

export default app;

Local Development

Run vc dev from the project root. Vercel runs your app directly with TypeScript support. No dev script is required, though you can add one if you prefer.

Static files in public/ are served automatically.

Configuration

Most apps need zero configuration. Optional vercel.json settings:

{
  "functions": {
    "server.ts": {
      "includeFiles": "views/**/*"
    }
  }
}

Anti-Patterns

• Putting routes in `api/` folder: Your framework IS the app. Define routes in your app code, not as separate files in api/.
• Adding `vercel.json` rewrites: Routes are introspected automatically from your app. Rewrites are not needed.
• Adding a `build` script: Vercel handles TypeScript compilation and bundling. Don't add a build script for transpilation — it's not needed and can cause issues.

Projects & Teams

Projects

vercel project ls                    # list projects
vercel project add my-project        # create project
vercel project inspect my-app        # inspect project
vercel project rm my-app             # remove project

Deployments

vercel list                          # list deployments
vercel list --status READY           # filter by status
vercel list -m gitBranch=main        # filter by metadata
vercel inspect <url>                 # deployment details
vercel remove <name|id>              # remove deployments
vercel remove my-app --safe          # skip aliased deployments

Teams

vercel whoami                        # current user and team
vercel teams ls                      # list teams
vercel teams switch                  # interactive team picker
vercel teams switch my-team          # switch by slug
vercel teams invite user@example.com # invite member

Scoping

Use --scope or --team on any command to target a specific team:

vercel deploy --scope my-team

Blob Storage

vercel blob manages Vercel Blob storage — simple file storage for uploading, listing, and deleting files.

vercel blob put ./image.png                              # upload
vercel blob put ./image.png --pathname images/photo.png  # custom path
vercel blob put ./large.zip --multipart                  # large files
vercel blob list                                         # list blobs
vercel blob list --prefix images/                        # filter by prefix
vercel blob del <url-or-pathname>                        # delete
vercel blob copy <from-url> <to-pathname>                # copy

Store Management

vercel blob store add              # create a new store
vercel blob store get              # show store details
vercel blob store remove           # remove a store

Load the Vercel CLI skill and help with project deployment and management.

Workflow

Step 1: Load vercel-cli skill

skill({ name: 'vercel-cli' })

Step 2: Identify task type from user request

Use the decision tree in SKILL.md to select the relevant reference file.

Step 3: Read the reference file

Based on task type, read references/<topic>.md. Use vercel <command> -h for full flag details.

Step 4: Execute task

Key things to verify:

• Project is linked (.vercel/ directory exists)
• Env vars are pulled if needed (vercel pull)
• Use --yes in CI/agent contexts
• Use VERCEL_TOKEN env var for auth (not --token)
• Use vercel curl to access preview deployments (don't disable protection)

Step 5: Summarize

=== Vercel CLI Task Complete ===

Topic: <topic>
<brief summary of what was done>

<user-request> $ARGUMENTS </user-request>

Advanced Commands

vercel api — Fallback for Missing CLI Commands

Use `vercel api` when a CLI command doesn't exist for what you need. Full access to the Vercel REST API with automatic authentication.

vercel api /v2/user                                    # GET current user
vercel api /v9/projects --scope my-team                # list projects
vercel api /v10/projects -X POST -F name=my-project    # create project
vercel api /v6/deployments --paginate                  # paginate all results
vercel api ls                                          # list available endpoints

Use vercel api ls to discover available endpoints.

Other Commands

• vercel webhooks — manage webhooks (create, ls, rm)
• vercel mcp — set up MCP integration for AI agents
• vercel telemetry — manage telemetry settings
• vercel upgrade — upgrade the CLI

Bun on Vercel

Vercel supports Bun as a runtime. To enable it, add "bunVersion": "1.x" to your vercel.json:

{
  "bunVersion": "1.x"
}

That's it. Vercel will use Bun instead of Node.js to run your project.

This works with any framework — backend apps (Express, Hono, Elysia), frontend frameworks, or anything else. Bun is used as the runtime, so Bun-specific APIs and features are available.

Example: Elysia with Bun

Elysia is a Bun-native framework. To use it on Vercel:

vercel.json:

{
  "bunVersion": "1.x"
}

package.json:

{
  "type": "module",
  "dependencies": {
    "elysia": "^1.0.0"
  }
}

server.ts:

import { Elysia } from 'elysia';

const app = new Elysia().get('/', () => 'Hello Elysia!');

export default app;

Example: Next.js with Bun

vercel.json:

{
  "bunVersion": "1.x"
}

package.json:

{
  "scripts": {
    "dev": "bun run --bun next dev",
    "build": "bun run --bun next build"
  }
}

Anti-Patterns

• Forgetting `bunVersion` in `vercel.json`: Without it, your project runs on Node.js. Bun-specific APIs (like Bun.file()) will fail at runtime.

CI/CD Automation

Authentication

Use VERCEL_TOKEN env var (not --token — it leaks in process listings). Use --scope if the token has access to multiple teams.

The Standard CI Deploy Pattern

vercel pull --yes --environment=production
vercel build --prod
vercel deploy --prebuilt --prod

For multi-project monorepos, ensure vercel link --repo --yes has been run first.

Separate Build and Deploy Jobs

Use --standalone so build artifacts are self-contained and can be passed between jobs:

jobs:
  build:
    steps:
      - run: vercel pull --yes --environment=production
      - run: vercel build --prod --standalone
      - uses: actions/upload-artifact@v4
        with:
          name: vercel-build
          path: .vercel/output

  deploy:
    needs: build
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: vercel-build
          path: .vercel/output
      - run: vercel deploy --prebuilt --prod

Without --standalone, the deploy job will fail because artifacts reference files outside .vercel/output/.

Capturing the Deploy URL

URL=$(vercel deploy --prod)   # stdout = URL, stderr = progress

Key Rules

1. Always use --yes to skip prompts 2. Always use VERCEL_TOKEN env var for auth 3. Use --scope if the token has access to multiple teams 4. Use vercel build + vercel deploy --prebuilt for deterministic builds 5. If something goes wrong, check .vercel/ — project.json vs repo.json is the most common issue

Deployment

Ensure .vercel/ exists before deploying (via vercel link or vercel link --repo).

Basic Usage

vercel                    # preview deployment (default)
vercel --prod             # production deployment
vercel --target staging   # custom environment

Prebuilt Deploy

Build locally, deploy the output — avoids remote builds:

vercel build --prod
vercel deploy --prebuilt --prod

If build and deploy run in separate CI jobs, use --standalone so artifacts are self-contained:

vercel build --prod --standalone
# (upload .vercel/output/ as artifact, then in deploy job:)
vercel deploy --prebuilt --prod

Deploy Output

• stdout: The deployment URL (pipeable)
• stderr: Progress and errors

URL=$(vercel deploy --prod)

Accessing Preview Deployments

Use vercel curl — it handles deployment protection automatically:

vercel curl /api/health --deployment $PREVIEW_URL

Do not disable deployment protection. Use vercel curl instead.

Other Deploy Commands

• vercel redeploy <url> — rebuild an existing deployment
• vercel promote <url> — move a deployment to production without rebuilding
• vercel rollback <url> — revert to a previous deployment
• vercel rolling-release — gradual traffic shifting

Workflows

Blue/Green

URL=$(vercel --prod --skip-domain)   # deploy without domain assignment
vercel curl / --deployment $URL      # verify (handles deployment protection)
vercel promote $URL                  # promote to production

Rolling Release

vercel rr configure --enable --stage=10,5m --stage=50,10m --stage=100,0
vercel rr start --dpl=<deployment-url>
vercel rr status

Domains & DNS

Overview

• vercel domains — manage domain ownership and project assignment
• vercel dns — manage DNS records (when using Vercel nameservers)
• vercel alias — map deployment URLs to custom domains
• vercel certs — manage SSL certificates (usually auto-managed)

Most users only need vercel alias — domains and DNS are auto-configured when using Vercel nameservers.

Typical Flow

1. Add domain to project: vercel domains add example.com my-project 2. Configure nameservers at registrar to point to Vercel 3. Deploy: vercel --prod (domain is auto-assigned)

Or manually alias: vercel alias set <deployment-url> example.com

DNS Records

vercel dns ls example.com
vercel dns add example.com @ A 1.2.3.4
vercel dns add example.com sub CNAME target.example.com
vercel dns rm rec_abc123

Use vercel <command> -h for full flag details.

Environment Variables

Scoping

Env vars are scoped to environments: production, preview (can be branch-specific), and development.

Variables can be plain text or sensitive (encrypted, not readable after creation).

Managing Env Vars

vercel env add API_KEY production              # add to production
vercel env ls                                  # list all
vercel env update API_KEY production           # update value
vercel env rm API_KEY preview                  # remove from preview
echo "secret" | vercel env add TOKEN production  # pipe value from stdin

Note: environment is a positional argument, not a flag.

Pulling Locally

vercel env pull                   # writes to .env.local
vercel env pull .env.development  # writes to custom file

vercel pull also downloads env vars along with project config.

Running with Env Vars

Inject env vars into a subprocess without writing to a file:

vercel env run -- npm test
vercel env run -e preview -- next dev

The -- separator is required before the command.

Feature Flags

vercel flags manages Vercel Flags — create, inspect, update, set, enable, disable, archive, and delete feature flags, plus manage SDK keys.

Creating Flags

create is the primary command; add is an alias.

vercel flags create my-feature                            # create boolean flag
vercel flags create my-feature --kind string --description "My flag"  # string flag with description
vercel flags create my-feature --kind string --variant control="Welcome back" --variant treatment="New onboarding"  # with explicit variants

Flag kinds: boolean (default), string, number. Boolean flags get true/false variants automatically; use --variant VALUE[=LABEL] (repeatable) for string/number flags.

Listing and Inspecting

vercel flags list                                         # list active flags
vercel flags list --state archived                        # list archived flags
vercel flags list --json                                  # output as JSON
vercel flags inspect my-feature                           # show flag details

Opening in Dashboard

vercel flags open                                         # open project flags dashboard
vercel flags open my-feature                              # open a specific flag

Updating Flags

Update variant values, labels, or both on an existing flag.

vercel flags update my-feature --variant control --value welcome-back --label "Welcome back"
vercel flags update my-feature --variant control --label "Control" --message "Rename control variant"
vercel flags update my-feature --variant false --label "Disabled"

Options: --variant (variant ID or value), --value (new value), --label/-l (new label), --message (revision message).

Setting Served Variant

set controls which variant is served in a given environment. Works with all flag kinds.

vercel flags set welcome-message -e production --variant control
vercel flags set bucket-size -e preview --variant 20
vercel flags set my-feature -e development --variant true

Options: --environment/-e, --variant/-v, --message.

Enable / Disable (Boolean Shortcut)

Only works with boolean flags. Shortcuts that set the served variant to true or false.

vercel flags enable my-feature -e production
vercel flags enable my-feature -e production --message "Resume production rollout"
vercel flags disable my-feature -e production
vercel flags disable my-feature -e production --variant off
vercel flags disable my-feature -e production --message "Pause rollout"

Environments: production, preview, development. Omit -e to choose interactively.

Archive / Delete

vercel flags archive my-feature --yes                     # archive (skip prompt)
vercel flags rm my-feature --yes                          # delete (must be archived first)

SDK Keys

SDK keys authenticate your application when evaluating flags. The full key value is only shown at creation time.

vercel flags sdk-keys ls                                  # list SDK keys
vercel flags sdk-keys ls --json                           # list as JSON
vercel flags sdk-keys add --type server -e production     # create server key
vercel flags sdk-keys add --type client -e preview --label "Preview App"  # client key with label
vercel flags sdk-keys rm <hash-key> --yes                 # delete key

Getting Started

Install

npm i -g vercel

First-Time Setup

1. Authenticate — vercel login (opens browser). For CI, use VERCEL_TOKEN env var instead. 2. Check your team — vercel whoami to see current team. vercel teams switch to change. Linking on the wrong team is a common mistake. 3. Link your project — vercel link (single project) or vercel link --repo (monorepo with multiple projects or non-root directories). Creates .vercel/. 4. Pull env vars — vercel pull downloads project settings and env vars to .env.local. 5. Dev or deploy — vercel dev (local server) or vercel --prod (production deploy).

Project Linking

Commands must be run from the directory containing .vercel/ or a subdirectory of it.

• `.vercel/project.json`: Created by vercel link. Links a single project. Fine for single-project repos, and can work in monorepos if there's only one project.
• `.vercel/repo.json`: Created by vercel link --repo. Links a repo that may contain multiple projects. Always a good idea when any project has a non-root directory (e.g., apps/web).

Running from a project subdirectory (e.g., apps/web/) skips the "which project?" prompt.

When something goes wrong, check how things are linked first — look at .vercel/ and whether it's project.json or repo.json.

Global Options

Key flags available on every vercel command:

• --help / -h — show help for the command
• --debug / -d — enable debug output
• --cwd DIR — override working directory
• --scope SCOPE / --team SLUG — set team context (both do the same thing)
• --token TOKEN — auth token (prefer VERCEL_TOKEN env var instead)
• --yes / -y — skip confirmation prompts (required in CI)
• --non-interactive — suppress interactive prompts (auto-detected for agents/CI)

--non-interactive is auto-detected when stdin is not a TTY, so agents and CI get this behavior by default.

Prefer VERCEL_TOKEN env var over --token to avoid leaking secrets in shell history.

Integrations

What Are Integrations?

Integrations are third-party services provisioned through the Vercel Marketplace and automatically connected to your project via environment variables. Categories include: AI, Agents, Analytics, Authentication, CMS, Code Review, Code Security, Commerce, DevTools, Experimentation, Flags, Logging, Messaging, Monitoring, Observability, Payments, Productivity, Searching, Security, Storage, Support Agent, Testing, Video, Web Automation, and Workflow.

When to Recommend an Integration

• The project needs a database — Postgres, MySQL, Redis, etc. → vercel integration add
• The project needs a KV store, blob storage, or other managed service → vercel integration add
• The user is manually setting env vars for a third-party service that's available on the Marketplace — an integration handles provisioning and env var injection automatically
• The user wants to add observability, logging, or error tracking → check the Marketplace

The key benefit: integrations automatically provision the resource AND inject the right environment variables into your project. No manual env var setup needed.

When in doubt about flags or subcommands, use `--help`:

vercel integration -h                              # list subcommands
vercel integration add -h                          # flags for add
vercel ir -h                                       # integration-resource subcommands

Discovering Integrations

vercel integration discover                        # list all marketplace integrations
vercel integration discover --format=json          # as JSON

Adding an Integration

vercel integration add <slug>                      # install and provision
vercel integration add <slug>/<product>            # specific product (multi-product integrations)
vercel integration add <slug> --name my-db         # custom resource name

The CLI prompts for product selection when multiple products exist and no /<product> slug is given (errors in non-TTY — specify the product slug). Billing plan uses --plan or server default (no prompt). Metadata uses -m flags or server defaults (no prompt). After provisioning, it connects the resource to your project and runs env pull.

vercel install <slug> (or vercel i <slug>) is an alias — behaves identically.

Browser fallback: The CLI may open a browser in two cases: (1) first-time install requiring terms acceptance — the CLI polls and resumes automatically once the user accepts, so do not kill the process; and (2) non-provisionable integrations — the CLI exits with code 1, inform the user they need to finish in the browser.

Environments

vercel integration add <slug> -e production            # specific environment
vercel integration add <slug> -e production -e preview # multiple (repeatable)

Defaults to all environments (production, preview, development).

Metadata

Some integrations require configuration during provisioning (e.g., region, database version):

vercel integration add <slug> -m region=us-east-1
vercel integration add <slug> -m region=us-east-1 -m version=16

Plans

vercel integration add <slug> --plan <plan-id>         # specific billing plan
vercel integration add <slug> -p <plan-id>             # shorthand

Other Flags

vercel integration add <slug> --no-connect             # skip connecting to project (also skips env pull)
vercel integration add <slug> --no-env-pull            # skip env pull only
vercel integration add <slug> --prefix NEON2_          # prefix env var names (e.g., NEON2_DATABASE_URL)
vercel integration add <slug> --installation-id <id>   # use specific installation (multi-installation)
vercel integration add <slug> --format=json            # output as JSON

Listing Resources

Alias: vercel integration ls

vercel integration list                                # resources for linked project
vercel integration list --all                          # all resources across the team
vercel integration list -i <slug>                      # filter by integration
vercel integration list <project>                      # resources for a specific project
vercel integration list --format=json                  # as JSON

Opening Dashboards

vercel integration open <integration>                  # open integration dashboard (SSO)
vercel integration open <integration> <resource>       # open specific resource dashboard
vercel integration open <integration> --format=json    # get SSO link as JSON

Disconnecting

Use vercel integration-resource (alias: vercel ir):

vercel ir disconnect <resource>                        # disconnect from current project
vercel ir disconnect <resource> <project>              # disconnect from specific project
vercel ir disconnect <resource> --all                  # disconnect from all projects
vercel ir disconnect <resource> --yes                  # skip confirmation

Disconnecting removes environment variables from the project but does not delete the resource.

Note: --format=json requires --yes on destructive commands (ir disconnect, ir remove, integration remove) — the CLI rejects JSON output with interactive prompts.

Billing

Only applies to integrations with prepayment-type billing plans. Returns "no balance info available" for integrations without prepayment billing.

vercel integration balance <slug>                      # show balance and thresholds
vercel integration balance <slug> --format=json        # as JSON
vercel ir create-threshold <resource> <minimum> <spend> <limit>
vercel ir create-threshold <resource> <minimum> <spend> <limit> --yes  # skip confirmation

Threshold parameters (dollar amounts, e.g., 50 100 500):

• minimum — balance floor; auto-replenish triggers when balance drops below this
• spend — replenishment amount added when minimum is hit
• limit — hard spending cap

Works for both resource-level and installation-level thresholds (CLI auto-detects).

Guides

vercel integration guide <slug>                        # show setup guide
vercel integration guide <slug> --framework nextjs     # framework-specific (-f shorthand)
vercel integration guide <slug>/<product>              # specific product

After installing, pull credentials to .env.local:

vercel env pull                                        # pulls to .env.local

This runs automatically after vercel integration add (unless --no-env-pull).

Removing Resources

Alias: vercel ir rm

vercel ir remove <resource>                            # delete (must not be connected)
vercel ir remove <resource> --disconnect-all           # disconnect all projects, then delete
vercel ir remove <resource> --disconnect-all --yes     # skip confirmation

This permanently deletes the resource from the provider. Cannot be undone.

Uninstalling an Integration

vercel integration remove <slug>                       # uninstall (all resources must be deleted first)
vercel integration remove <slug> --yes                 # skip confirmation

Cleanup Workflow

vercel integration list --all -i <slug>                # find all resources
vercel ir remove <resource-1> --disconnect-all --yes   # delete each resource
vercel ir remove <resource-2> --disconnect-all --yes
vercel integration remove <slug> --yes                 # then uninstall

Local Development

Prerequisites

1. Link your project — vercel link or vercel link --repo (monorepo). Check your team first with vercel whoami. 2. Pull env vars — vercel pull or vercel env pull

Usage

vercel dev                           # default: 0.0.0.0:3000
vercel dev --listen 8080             # custom port
vercel dev --listen 127.0.0.1:5000   # custom host and port

Related Commands

• vercel link — connect to a Vercel project. Use --repo for multi-project monorepos.
• vercel pull — download project settings and env vars to .env.local
• vercel env pull — download only env vars (not project settings)
• vercel init — scaffold a new project from a Vercel example
• vercel open — open the Vercel dashboard for the linked project

Run vercel dev from a project subdirectory (e.g., apps/web/) to skip the project selection prompt.

Monitoring & Debugging

Logs

vercel logs <deployment-url>                   # view logs
vercel logs --follow                           # stream live
vercel logs --level error --level warn         # filter by severity
vercel logs --source lambda                    # filter by source (lambda, edge, static)
vercel logs --since 2024-01-01                 # filter by time
vercel logs --query "timeout"                  # search

Metrics

vercel metrics schema                                                    # list available metrics
vercel metrics schema vercel.function_invocation                         # inspect a metric prefix
vercel metrics vercel.function_invocation.count --since 1h               # query linked project
vercel metrics vercel.request.count --group-by http_status --since 6h    # group by schema dimension
vercel metrics vercel.function_invocation.request_duration_ms -a avg --group-by route --since 1h
vercel metrics vercel.ai_gateway_request.cost -a sum --group-by ai_provider --since 7d
vercel metrics vercel.speed_insights_metric.lcp -a p75 --group-by route --since 7d
vercel metrics --all vercel.function_invocation.count --group-by project_id --since 24h
vercel metrics vercel.function_invocation.count -f "http_status ge 500" --group-by error_code --since 1h --format=json

Inspecting Deployments

vercel inspect <url>               # deployment details
vercel inspect <url> --wait        # wait for completion
vercel inspect <url> --logs        # show build logs

vercel curl — Access Preview Deployments

Use `vercel curl` to access preview deploys. It handles deployment protection automatically — no need to disable protection or manage bypass secrets.

vercel curl /api/health --deployment $PREVIEW_URL
vercel curl /api/data --deployment $PREVIEW_URL -- -X POST -d '{"key":"value"}'

Do not disable deployment protection. Use vercel curl instead.

Finding Regressions

vercel bisect performs a binary search across deployments to find which one introduced a problem:

vercel bisect --good <url> --bad <url> --path /api/users
vercel bisect --run ./test-script.sh    # automated testing

Cache

vercel cache purge                    # purge CDN cache
vercel cache invalidate --tag mytag   # invalidate by cache tag

Monorepos on Vercel

Vercel auto-detects monorepo tools (Turborepo, Nx) and workspace managers (pnpm, Yarn, npm). Each project in the monorepo gets its own Vercel project, linked via vercel link --repo.

Quick Start

vercel link --repo    # link the whole repo
vercel pull           # pull env vars
vc dev                # local development
vercel deploy         # deploy

Linking

Use vercel link --repo to create .vercel/repo.json, which maps directories to Vercel projects:

{
  "orgId": "org_xxxxx",
  "projects": [
    { "id": "prj_xxxxx", "name": "web", "directory": "apps/web" },
    { "id": "prj_yyyyy", "name": "api", "directory": "apps/api" }
  ]
}

Running from a project subdirectory (e.g., apps/web/) skips the "which project?" prompt.

Root Directory

Set rootDirectory in vercel.json when your app isn't at the repo root:

{
  "rootDirectory": "apps/api"
}

Turborepo

Turborepo requires an explicit build task. Define it in turbo.json:

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "env": ["VERCEL"],
      "outputs": [".next/**", "!.next/cache/**", ".vercel/output/**", "dist/**"]
    }
  }
}

Vercel automatically generates the right build command — you don't need to configure it. If you need a manual override in vercel.json:

{
  "buildCommand": "turbo run build --filter={packages/my-app}..."
}

turbo-ignore

Vercel auto-sets npx turbo-ignore as the "Ignored Build Step" command, which skips builds when a project's dependencies haven't changed.

Nx

Nx requires a build target. Define it in nx.json:

{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

Example: Turborepo + pnpm + Hono

root/
├── turbo.json
├── package.json
├── pnpm-workspace.yaml
├── vercel.json
├── apps/
│   └── api/
│       ├── package.json
│       └── server.ts
└── packages/
    └── shared/
        ├── package.json
        └── src/index.ts

pnpm-workspace.yaml:

packages:
  - 'apps/*'
  - 'packages/*'

vercel.json:

{
  "rootDirectory": "apps/api"
}

apps/api/server.ts:

import { Hono } from 'hono';
import { greet } from '@repo/shared';

const app = new Hono();
app.get('/', c => c.text(greet('world')));

export default app;

Anti-Patterns

• Using `vercel link` instead of `vercel link --repo`: Creates project.json which only tracks one project. Use --repo for monorepos.
• Missing `build` task in turbo.json/nx.json: Vercel requires an explicit build task. Without it, the build fails.
• Adding a `build` script to package.json for transpilation: Vercel handles TypeScript compilation. The turbo.json build task is for orchestration, not transpilation.
• Linking while on the wrong team: Use vercel whoami to check, vercel teams switch to change.

Node Backends on Vercel

Vercel supports Node.js backend frameworks as first-class apps. Express and Hono are the most common, but Fastify, Elysia, NestJS, H3, and Koa are also supported. Your app is the entrypoint — not the api/ folder. No rewrites, no build scripts. Just export your app and deploy.

Quick Start

# Express
npm init -y && npm i express
# Create server.ts that exports default app
vc dev       # local development
vc deploy    # deploy

How It Works

1. Vercel detects the framework from package.json dependencies 2. Finds your entrypoint file (must import the framework) 3. Introspects your routes automatically — no vercel.json rewrites needed 4. Bundles and deploys as a single Lambda

Entrypoint Detection

Vercel searches for these filenames (in order): app, index, server, main, src/app, src/index, src/server, src/main

With these extensions: .js, .cjs, .mjs, .ts, .cts, .mts

The preferred entrypoint filename is server.ts. The file must import the framework (import express from 'express', import { Hono } from 'hono', etc.).

We recommend using export default for the app instance, but calling .listen() also works.

Minimal Express App

my-app/
├── package.json
└── server.ts

package.json:

{
  "type": "module",
  "dependencies": {
    "express": "5.1.0"
  }
}

server.ts:

import express from 'express';

const app = express();

app.get('/', (_req, res) => {
  res.send('Hello Express!');
});

export default app;

Minimal Hono App

package.json:

{
  "type": "module",
  "dependencies": {
    "hono": "^4.8.9"
  }
}

server.ts:

import { Hono } from 'hono';

const app = new Hono();

app.get('/', c => {
  return c.text('Hello Hono!');
});

export default app;

Local Development

Run vc dev from the project root. Vercel runs your app directly with TypeScript support. No dev script is required, though you can add one if you prefer.

Static files in public/ are served automatically.

Configuration

Most apps need zero configuration. Optional vercel.json settings:

{
  "functions": {
    "server.ts": {
      "includeFiles": "views/**/*"
    }
  }
}

Anti-Patterns

• Putting routes in `api/` folder: Your framework IS the app. Define routes in your app code, not as separate files in api/.
• Adding `vercel.json` rewrites: Routes are introspected automatically from your app. Rewrites are not needed.
• Adding a `build` script: Vercel handles TypeScript compilation and bundling. Don't add a build script for transpilation — it's not needed and can cause issues.

Projects & Teams

Projects

vercel project ls                    # list projects
vercel project add my-project        # create project
vercel project inspect my-app        # inspect project
vercel project rm my-app             # remove project

Deployments

vercel list                          # list deployments
vercel list --status READY           # filter by status
vercel list -m gitBranch=main        # filter by metadata
vercel inspect <url>                 # deployment details
vercel remove <name|id>              # remove deployments
vercel remove my-app --safe          # skip aliased deployments

Teams

vercel whoami                        # current user and team
vercel teams ls                      # list teams
vercel teams switch                  # interactive team picker
vercel teams switch my-team          # switch by slug
vercel teams invite user@example.com # invite member

Scoping

Use --scope or --team on any command to target a specific team:

vercel deploy --scope my-team

Blob Storage

vercel blob manages Vercel Blob storage — simple file storage for uploading, listing, and deleting files.

vercel blob put ./image.png                              # upload
vercel blob put ./image.png --pathname images/photo.png  # custom path
vercel blob put ./large.zip --multipart                  # large files
vercel blob list                                         # list blobs
vercel blob list --prefix images/                        # filter by prefix
vercel blob del <url-or-pathname>                        # delete
vercel blob copy <from-url> <to-pathname>                # copy

Store Management

vercel blob store add              # create a new store
vercel blob store get              # show store details
vercel blob store remove           # remove a store