Back to Knowledge
Updated Sep 2026

Vercel Playbook

Vercel

Vercel

A cloud platform built by the team behind Next.js. Push to Git and every branch gets a live Preview Deployment; production is one merge away. Functions run on Fluid Compute by default, and Vercel adds storage, AI Gateway, queues, sandboxes, and more.

"Like magic website publishing. Push to GitHub, and boom — it's live."

is a deployment platform where your code becomes a website. Push to GitHub, and it's live. While this guide focuses on Vercel, many concepts apply to other hosts like Netlify, Railway, or Render. Here's how to use Vercel like a pro in 2026: deploys, previews, secrets, how your functions actually run, and the platform services worth knowing.

1What is Vercel?

Vercel is a deployment platform (hosting provider) that deploys your frontend and serverless backend automatically. When you push code to GitHub, Vercel builds it, optimizes it, and serves it globally via a CDN. Similar platforms include Netlify, Railway, and AWS Amplify.

Instant Deploys

Push to main, it's live in seconds.

Preview Deploys

Every branch and PR gets its own URL to test.

Global CDN

Your site is fast everywhere.

2The Vercel Workflow

01

Connect GitHub Repo

Import your repository at vercel.com/new (one-time setup). New to Git? Start with the Git playbook.

02

Add Environment Variables

Set your production secrets in the Vercel dashboard (section 5)

03

Push a Branch → Preview

Every push to a non-production branch gets its own preview URL

04

Merge to Main → Live!

Production updates at yourproject.vercel.app (or your custom domain)

Preview Deployments Are the Superpower

A preview deployment

Preview Deployment

An automatic staging environment created for every pull request or branch. Lets you see and test changes before merging to production.

"Like a dress rehearsal before opening night. See exactly how it looks before going live."

is a full, working copy of your app built from a branch. Vercel comments the URL on your pull request, so you (or a client) can click around before anything touches production. For vibe coders this is the perfect review loop: let Claude build on a branch, open the preview on your phone, then merge only what you like.

  • • Previews use the Preview set of environment variables, so point them at a test database, not production.
  • • OAuth logins often break on previews because each preview has a new URL. Test auth on a stable domain; see OAuth Setup.
  • • Broke production? Promote a previous deployment from the dashboard to roll back instantly, then fix forward.

3How Your Code Runs: Fluid Compute

Your pages are served from the CDN; your API routes, Server Actions, and dynamic pages run as Vercel Functions. New projects use Fluid Compute

Fluid Compute

Vercel's default function runtime model (on for new projects since April 2025). Instead of one request per function instance, an instance can handle many requests at once, keep working after the response with `waitUntil`, and you're billed for active CPU time rather than time spent waiting on things like AI responses.

"Like a waiter who serves several tables at once instead of standing idle while one table's food cooks."

by default (since April 2025). Think of classic serverless

Serverless

A cloud model where you don't manage servers: your code runs in response to requests or events, scales automatically, and you pay for usage. Modern platforms like Vercel's Fluid Compute reuse warm instances for many requests at once and bill for active CPU time, which makes serverless a much better fit for slow AI calls.

"Like renting a kitchen by the meal instead of buying a restaurant. Use it, pay for it, done."

 as one taxi per passenger; Fluid is a shuttle bus: one warm instance handles many requests at once, you pay for active CPU time rather than idle waiting, and you can finish work after responding with waitUntil.

LimitWhat to know
RuntimeNode.js 24.x is the default (22.x and 20.x are available; Node 20 is being deprecated on Vercel from Oct 1, 2026)
Max durationDefault 300 seconds on every plan. Hobby max is 300s; Pro and Enterprise go to 800s
Request / response body4.5 MB. Upload big files straight to storage (see Blob below), not through your function
MemoryHobby 2 GB; Pro and Enterprise up to 4 GB
Default regioniad1 (Washington, D.C.). Put your database nearby

Pin the Node version so your laptop, CI, and Vercel agree, and give slow routes (like AI calls) an explicit budget:

package.json

{
  "engines": { "node": "24.x" }
}

app/api/summarize/route.ts

// Seconds this route may run (up to your plan's max)
export const maxDuration = 60;

Skip the Edge runtime

Old tutorials (and some AI answers) say export const runtime = 'edge' makes things faster. Vercel now recommends migrating from Edge

Edge Runtime

A lightweight JavaScript runtime that ran code in data centers close to users, with only a subset of Node.js APIs. It's now legacy: Vercel recommends migrating from Edge to Node.js, and Next.js 16.3 no longer supports `export const runtime = 'edge'`. If an old tutorial tells you to use it for speed, skip that step.

"Like a pop-up kiosk: close to customers but with a tiny kitchen. The full restaurant (Node.js) got fast enough that the kiosk isn't worth it."

to Node.js, and Next.js 16.3 no longer supports runtime = 'edge' at all. If you see it in your code, delete the line.

4Many Projects, One Account

Each Repo Is Its Own Project

You can host many projects under a single account. Each GitHub repo you connect becomes its own project with its own URL, domain, environment variables, and settings.

Example: your dashboard might look like:

my-portfolio→ portfolio.vercel.app
client-dashboard→ dashboard.myclient.com
side-project→ coolapp.vercel.app

What they share

Consolidated Billing

One bill and one set of usage limits for everything in the account or team.

Team Access

Add teammates once and give them access to specific projects. Great for agencies.

Integrations

Marketplace services like Neon or Upstash are installed once and connected to whichever projects need them.

Domain Management

Buy and manage domains in Vercel and assign them to any project.

Pro Tip: Building several apps for a client? Put them in a dedicated Vercel Team so billing and access stay separate from your personal projects. You can transfer projects later if needed.

5Environment Variables

Vercel Is Where Your Secrets Live

Your .env.local file is for LOCAL development. Vercel's Environment Variables are for PRODUCTION and PREVIEW. They don't sync by themselves.

Local Development

# .env.local (in your project)

DATABASE_URL="postgres://..."

API_KEY="sk-dev-xxx"

  • • Lives on YOUR computer
  • • Never committed to Git
  • • Only used when running locally

Production & Preview (Vercel)

# Vercel Dashboard → Settings

DATABASE_URL="postgres://..."

API_KEY="sk-prod-xxx"

  • • Lives on Vercel's servers
  • • Encrypted, scoped per environment
  • • Used when your site is deployed

Make Vercel the source of truth: vercel env pull

Instead of copy-pasting secrets around, store them in Vercel and pull them down. The CLI writes your .env.local

.env File

A special file where you store environment variables. It's usually hidden and never shared publicly.

"Like a secret diary. It holds your passwords and keys — never share it or commit it to GitHub!"

for you (and Marketplace integrations add their own variables automatically):

Terminal

npm i -g vercel        # install the CLI once
vercel link            # connect this folder to your Vercel project
vercel env pull        # writes .env.local with your Development variables

# Need a specific environment?
vercel env pull --environment=preview

Next.js loads .env.local automatically on npm run dev. Make sure .gitignore covers it (look for a .env* line) before your first commit. The full guide is in Environment Variables.

Common Mistake

"It works locally but not in production!" — You probably forgot to add the environment variable

Environment Variable

A secret value stored outside your code, like API keys or passwords. Keeps sensitive info out of your codebase.

"Like a sticky note with the WiFi password — you know it, but you don't write it on the wall."

in Vercel, or added it after the last deploy. Changes only apply to new deployments, so redeploy.

Adding Environment Variables in the Dashboard

  1. 1Go to your project in the Vercel dashboard
  2. 2Click Settings → Environment Variables
  3. 3Add your key-value pairs (e.g., DATABASE_URL)
  4. 4Choose which environments: Production, Preview, and/or Development
  5. 5Redeploy your project for changes to take effect

6Platform Services Worth Knowing

You don't need all of these on day one. Know they exist so you (and Claude) don't reinvent them.

Marketplace Storage (databases, Redis)

Databases on Vercel come from Marketplace partners like Neon, Upstash, and Supabase. You install them from the dashboard or CLI. Billing and env vars are wired up for you.

Terminal

vercel install neon      # Postgres
vercel install upstash   # Redis (great for rate limiting)
vercel env pull          # grab the new connection strings

Next: Neon and Connect a Database.

Vercel Blob (file storage)

For uploads, images, and PDFs. Each store is either public (anyone with the URL can read) or private, and that choice is set per store and can't be changed later, so decide up front. On Vercel it authenticates automatically; BLOB_READ_WRITE_TOKEN is only for use outside Vercel or client uploads.

app/api/upload/route.ts

import { put } from '@vercel/blob';

export async function POST(request: Request) {
  const form = await request.formData();
  const file = form.get('file') as File;
  const blob = await put(`avatars/${file.name}`, file, { access: 'public' });
  return Response.json({ url: blob.url });
}

Remember the 4.5 MB body limit: for bigger files, upload from the browser directly to Blob instead of through a route like this.

AI Gateway

An AI Gateway

AI Gateway

A single endpoint that sits between your app and many AI providers, handling keys, routing, fallbacks, budgets, and usage tracking. With Vercel AI Gateway you pass a plain `"provider/model"` string like `'anthropic/claude-sonnet-5'` to the AI SDK and authenticate with `AI_GATEWAY_API_KEY` (or OIDC on Vercel).

"Like a travel agent who books any airline for you. One contact, one bill, and they rebook you if a flight is cancelled."

is one endpoint and one bill for many model providers, with fallbacks and spend tracking. With the AI SDK, a plain "provider/model" string routes through it. On Vercel it authenticates via OIDC; locally, vercel env pull gives you a token (or set AI_GATEWAY_API_KEY).

lib/ai.ts

import { generateText } from 'ai';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-5',
  prompt: 'Write a one-line welcome message for new users.',
});

Gateway model slugs use dots (anthropic/claude-opus-5.5), unlike Anthropic's own API IDs (claude-opus-5-5). Deep dive: AI SDK & Gateway.

Global Config

Formerly called Edge Config. A tiny, ultra-fast key-value store for things you want to change without a redeploy: feature flags, maintenance mode, a blocklist. Package: @vercel/global-config (the old @vercel/edge-config still works).

Background work

Jobs that outlive a request (multi-step AI agents, retries, long pipelines) belong in Vercel Workflow or Queues, not a single function call. See Durable Agents.

7Project Config in TypeScript: vercel.ts

Most Next.js projects need no Vercel config at all. When you do need redirects, headers, or cron jobs at the platform level, you can now write them in a typed vercel.ts instead of vercel.json (use one or the other, not both). Install the helper package with npm i @vercel/config.

vercel.ts

import { routes, type VercelConfig } from '@vercel/config/v1';

export const config: VercelConfig = {
  redirects: [routes.redirect('/old-docs', '/docs', { permanent: true })],
  headers: [
    routes.header('/(.*)', [
      { key: 'X-Content-Type-Options', value: 'nosniff' },
      { key: 'X-Frame-Options', value: 'DENY' },
    ]),
  ],
  crons: [{ path: '/api/cleanup', schedule: '0 0 * * *' }],
};

Because it's real TypeScript, your editor autocompletes the options and Claude is far less likely to invent keys that don't exist.

Before you share the link

Production env vars set (and a redeploy since)

Preview env vars point at test resources

No runtime = 'edge' lines left in the code

Node pinned with engines: 24.x

Big uploads go to Blob, not through a route

Custom domain added and verified

The full launch list lives in the Deployment Checklist.

Ready to deploy?

Create a free Vercel account and connect your first repo. Check current plan limits before you scale.

Start on Vercel Next: Database (Neon) Custom Domain