# Vercel

> Vercel — first deploy

- Skill: `beckyisj/vercel` (Agent Skill)
- Install (CLI): `npx skillmds@latest add beckyisj/vercel`
- Raw SKILL.md: https://api.skillmd.com/api/skills/beckyisj/vercel/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: beckyisj (https://skillmd.com/u/beckyisj)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/beckyisj/vercel

---


# Vercel — first deploy

Set up hosting once, properly, so `/ship` can do the routine deploys afterwards.

**Argument**: `$ARGUMENTS` is the project path and optionally the custom domain. Default to the current directory.

## Process

### 1. Detect state

```bash
which vercel || echo "no vercel cli"
vercel whoami 2>&1
ls .vercel/project.json vercel.json 2>/dev/null
git remote -v
cat package.json | grep -E '"(build|dev|start)"'
grep -v '^#' .env.local 2>/dev/null | cut -d= -f1
```

This tells you: is the CLI installed and logged in, is the project already linked, is there a GitHub remote (Vercel's Git integration wants one), what the framework is, and which env vars will need to exist in production.

### 2. Install and log in (once)

```bash
npm i -g vercel
vercel login
```

`vercel login` opens a browser. The user has to click through it; tell them to type `! vercel login` if they are driving this from a Claude Code session so the prompt lands in their terminal.

### 3. Link the project

```bash
vercel link --yes
```

Accept the detected framework. This writes `.vercel/project.json`; add `.vercel` to `.gitignore` if it isn't there.

### 4. Environment variables

For every key found in `.env.local` in step 1, push it to all three environments:
```bash
vercel env add <KEY> production
vercel env add <KEY> preview
vercel env add <KEY> development
```
Each command prompts for the value; the user pastes it. Never read the secret values into the conversation yourself. Keys prefixed `NEXT_PUBLIC_` or `VITE_` are bundled into the browser, so double-check none of those hold a secret.

Later, to get production vars onto a new machine: `vercel env pull .env.local`.

### 5. Deploy

```bash
vercel --prod
```

Read the output. A URL means success. If the build fails, the log is readable: nine times out of ten it is a TypeScript error that `npm run dev` tolerated, or an env var missing in production. Fix and re-run.

### 6. Custom domain (if given)

```bash
vercel domains add <domain>
```

Vercel prints the DNS record it wants: an **A record** `@ → 76.76.21.21` for the apex, and a per-project **CNAME** for `www` or any subdomain (looks like `abc123.vercel-dns-017.com`; copy it from the output, it is not the same for every project). Hand those to `/domain` for the registrar-specific steps, or if the registrar is Vercel itself, it's already done.

On Cloudflare the A record must be **DNS only** (grey cloud) or Vercel can't issue the SSL certificate.

Confirm with:
```bash
vercel domains verify <domain>
```

### 7. Verify

```bash
curl -sI https://<deployment-url> | head -1
curl -sI https://<domain> | head -1        # if a domain was added
```

Expect `HTTP/2 200`. A `307` on the apex that lands on `www` (or vice versa) is Vercel's redirect and is fine.

### 8. Report

```
Vercel
- Project: my-app (linked, framework: Next.js)
- Env: 4 vars pushed to production/preview/development
- Deploy: https://my-app-abc123.vercel.app — 200
- Domain: mytool.app — DNS pending at Namecheap (A @ 76.76.21.21)
- Next: /ship for future deploys · Settings → Git to enable preview URLs per PR
```

## Gotchas

- **Hobby tier function timeout is 10 seconds.** A route that calls an LLM or processes a file will hit it. Options: Pro (60s), or `export const maxDuration = 60` with Fluid Compute, or move the work to a background job.
- **Cold starts** on serverless functions add about a second after idle. Fine for most apps.
- **Preview deploys from PRs** need the GitHub integration: Vercel dashboard → Project → Settings → Git → Connect. `vercel --prod` from the CLI works without it.
- **Pricing**: Hobby is free (100 GB bandwidth, personal use only). Pro is $20/month per member and required for anything commercial.
- **Analytics** is one import away: `npm i @vercel/analytics`, then `<Analytics />` from `@vercel/analytics/next` in the root layout. Free for 2,500 events/month on Hobby.