Help us improve
Share bugs, ideas, or general feedback.
From vercel
Stand up and operate the Vercel deploy pipeline — project setup, the Production / Preview / Development environment trio, custom environments, domains and aliases, Deployment Protection (SSO / password / Bypass Tokens), build configuration, rollback via re-aliasing, and the deploy-hook patterns that drive CI-from-non-git sources. Use this skill when a new Vercel project is being created, when "set up our preview deployments" comes up, when staging deploys need a stable URL, when domain configuration is in question, when a deploy fails and the cause isn't obvious, or when rollback is on the table. Trigger on any "how do we ship to Vercel" question.
npx claudepluginhub bpainter/composable-dxp-claude-marketplace --plugin vercelHow this skill is triggered — by the user, by Claude, or both
Slash command
/vercel:vercel-deploy-pipelineThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Owns the deploy lifecycle on Vercel — from "we don't have a project yet" through "production rollback in 30 seconds." Pair with `vercel-fluid-compute` (runtime decisions land here), `vercel-cdn-edge` (cache invalidation on deploy), `vercel-security` (Deployment Protection), `vercel-observability` (post-deploy verification), and `vercel-rest-api` (programmatic operations).
Guides technical evaluation of code review feedback: read fully, restate for understanding, verify against codebase, respond with reasoning or pushback before implementing.
Share bugs, ideas, or general feedback.
Owns the deploy lifecycle on Vercel — from "we don't have a project yet" through "production rollback in 30 seconds." Pair with vercel-fluid-compute (runtime decisions land here), vercel-cdn-edge (cache invalidation on deploy), vercel-security (Deployment Protection), vercel-observability (post-deploy verification), and vercel-rest-api (programmatic operations).
vercel.json, both checked. Don't depend on dashboard-only state for reproducibility.1. Confirm scope
- Personal account vs. Team. For client work: always Team.
- Plan tier (Hobby / Pro / Enterprise) — drives feature availability.
- Who pays, who has admin, who has deploy access.
2. Connect git
- GitHub / GitLab / Bitbucket repo.
- Pick the framework preset (Next.js for ~90% of Slalom work).
- Verify Root Directory if monorepo (e.g., `apps/web`).
- Verify Build Command, Install Command, Output Directory.
3. Environments
- Production: pinned to default branch (`main`).
- Preview: every non-default branch / PR.
- Development: local via `vercel dev`.
- Add staging-aliased Preview domain (see "Domains" below).
4. Environment variables
- Server-only secrets in Production + Preview (encrypted).
- `NEXT_PUBLIC_*` for client-side public config.
- Use `vercel env pull` to sync to local `.env`.
- NEVER commit secrets. NEVER expose `*_TOKEN` or `*_SECRET` as `NEXT_PUBLIC_`.
5. Domains
- Production domain (`example.com`) → DNS-verified, attached to Production environment.
- Apex vs. www — pick one canonical, redirect the other.
- `staging.example.com` aliased to a stable Preview URL pattern.
6. Deployment Protection
- Production: public, OR password-protected if pre-launch.
- Preview: SSO (Vercel Authentication) — gates all preview URLs to org members.
- Bypass Tokens for E2E test runners and external QA tools.
7. Observability + Security
- Speed Insights + Web Analytics enabled.
- WAF + BotID enabled (Pro+).
- Spend cap configured.
8. Document
- .vercel/project.json committed.
- README contains "How to deploy", "How to access preview", "Who has admin."
| Environment | Source | Lifetime | Use |
|---|---|---|---|
| Production | Push to main | Long-lived deployment alias | Customer-facing |
| Preview | Push to any non-default branch / PR | One per branch, refreshed on push | Stakeholder review, QA |
| Development | vercel dev locally | Ephemeral, per-developer | Local development |
| Custom (Pro+) | Manual config (staging, qa) | Long-lived alias | Stable QA / UAT URL |
Custom environments: useful when Preview URLs aren't stable enough (e.g., external QA team needs a single URL). Configure in Project Settings → Environments. Treat each custom environment as having its own env-var set; copy carefully from Preview.
Domains
├── example.com → Production (alias)
├── www.example.com → 301 redirect to apex
├── staging.example.com → custom-environment alias (Pro+) OR latest Preview
└── *.example.com (wildcard) → for branch-named subdomains (rare)
Patterns:
staging.example.com aliased to a custom environment OR to a "latest preview" pattern. Stakeholders bookmark this.<project>-git-<branch>-<scope>.vercel.app. Predictable per-branch; useful for PR-based stakeholder review.DNS:
cname.vercel-dns.com, ORFor Slalom builds, prefer the CNAME pattern unless the client is using Vercel as their DNS provider. Document the DNS state in the runbook.
Three modes, often combined:
Org-account-gated access to Preview deployments. Default ON for non-public projects. Members of the Vercel team see Preview URLs; everyone else gets a login wall.
Enable in Project Settings → Deployment Protection → Vercel Authentication.
Static password on selected environments. Useful for pre-launch Production where the client wants stakeholders to access without giving them Vercel accounts.
Enable in Project Settings → Deployment Protection → Password Protection.
Programmatic-access tokens that skip Deployment Protection. Use for:
Generate in Project Settings → Deployment Protection → Bypass for Automation. Token is a query param: ?x-vercel-protection-bypass=<token>. Treat as a secret — leaks publish your preview.
IP allowlist for sensitive routes or Production. Pair with WAF for layered defense. See vercel-security.
Most Slalom projects need only modest configuration:
vercel.json (when needed — many projects don't have one):
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"headers": [
{
"source": "/(.*)",
"headers": [
{ "key": "X-Frame-Options", "value": "DENY" },
{ "key": "X-Content-Type-Options", "value": "nosniff" },
{ "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
]
}
],
"rewrites": [
{ "source": "/api/proxy/:path*", "destination": "https://api.example.com/:path*" }
],
"redirects": [
{ "source": "/old-path", "destination": "/new-path", "permanent": true }
]
}
Headers, rewrites, redirects can also live in next.config.mjs — pick one place per concern. For Slalom builds, prefer next.config.mjs for app-level concerns and vercel.json for platform-level (e.g., security headers, function config).
Function configuration:
{
"functions": {
"app/api/heavy/route.ts": {
"maxDuration": 60,
"memory": 1024
}
}
}
maxDuration defaults vary by plan; long-running functions (LLM streaming, video processing) often need explicit higher values.
Order of operations when a deploy fails:
next upgrade in package.json).vercel build. This runs the Vercel build environment more faithfully than next build.| Symptom | Likely cause |
|---|---|
Module not found: sharp | Native dep failing; ensure sharp is in dependencies, not devDependencies |
| Function exceeds size limit | Large dep (e.g., Puppeteer) bundled into a function |
Image Optimization error | Domain not in images.remotePatterns |
proxy.ts errors | Old middleware.ts not renamed after Next.js 16 upgrade |
| Env var undefined | Set in Production but not Preview, or vice versa |
| Build succeeds but 404s in Production | Routing config drift; check next.config redirects/rewrites |
Vercel rollback is alias re-pointing — not a re-build:
Dashboard → Deployments → Find prior good deployment → "Promote to Production"
Or via CLI:
vercel promote <prior-deployment-url-or-id> --token=$VERCEL_TOKEN
Or via REST API (vercel-rest-api).
Implications:
Deploy hooks are URLs that, when POSTed to, trigger a deploy of a specific branch:
POST https://api.vercel.com/v1/integrations/deploy/{project-id}/{hook-id}
Use cases:
Configure in Project Settings → Git → Deploy Hooks. The hook URL is sensitive — treat as a secret.
For ISR / on-demand revalidation patterns, prefer those over deploy hooks; they're cheaper and faster. Deploy hooks are for "rebuild from scratch" scenarios.
Patterns to enforce:
NEXT_PUBLIC_* audit. Anything prefixed NEXT_PUBLIC_ is shipped to the browser. Audit before launch.vercel env pull. Avoid hand-editing .env.local for Production-mirror config.# Vercel Project Setup: [Project Name]
## Account & Team
- Team: {team-id}
- Plan: {Hobby | Pro | Enterprise}
- Admins: {list}
- Deploy access: {list}
## Project
- Project ID: {id}
- Repo: {git URL}
- Framework: {Next.js / other}
- Root directory: {path or repo root}
- Production branch: {main}
## Environments
| Env | Source | Domain | Protection |
|---|---|---|---|
| Production | main | example.com | public |
| Preview | non-main branches | <project>-git-<branch>.vercel.app | SSO |
| Custom: staging | (alias to latest preview / custom env) | staging.example.com | SSO |
## Environment variables
| Name | Production | Preview | Notes |
|---|---|---|---|
| ... | ✓ | ✓ | server-only |
## Observability
- Speed Insights: {enabled}
- Web Analytics: {enabled}
- Log drain: {Datadog / Axiom / etc., or none}
## Security
- WAF: {enabled / rules}
- BotID: {enabled}
- Bot Management: {rules}
- Trusted IPs: {if Enterprise}
## Cost
- Spend cap: {$N}
- Alerts: {addresses}
## Owners
- Slalom: {names}
- Client: {names}
# Deploy Incident: [Date] [One-line summary]
## Symptom
{what was broken}
## Detection
{how the issue surfaced — alert, customer report, monitoring}
## Root cause
{what changed and why it broke}
## Fix
{what we did}
## Prevention
{what we'll add to the runbook / CI / monitoring to catch this earlier}
## Timeline
- T+0: incident
- T+N: detected
- T+M: rolled back
- T+P: root cause identified
- T+Q: fix deployed
staging, qa, uat, pre-prod all with different env-var sets that drift. Keep to ≤2 custom environments.vercel.json disagree. Pick one source of truth (preferably vercel.json + next.config.mjs checked into the repo).vercel-fluid-compute.vercel-cdn-edge.vercel-storage.vercel-observability.vercel-security.vercel-rest-api.../../references/marketplace-integrations.md.../../references/vercel-foundations.md../../references/cli-cheat-sheet.md