Vercel Deploy
Zero-auth deployment to Vercel with automatic framework detection. Deploy any web application with a single command and receive preview URLs, claim URLs, and deployment metadata.
When to Apply
Use this skill when:
- Deploying a web application to Vercel for preview or production
- Setting up a deployment pipeline for a new project
- Creating preview deployments for pull request review
- Testing production builds in a live environment
- Demonstrating a prototype or proof of concept
Supported Frameworks
Vercel auto-detects and configures builds for these frameworks:
| Framework | Detection | Build Command |
|---|
| Next.js | next.config.* | next build |
| Vite | vite.config.* | vite build |
| Remix | remix.config.* | remix build |
| SvelteKit | svelte.config.* | vite build |
| Astro | astro.config.* | astro build |
| Nuxt | nuxt.config.* | nuxt build |
| Gatsby | gatsby-config.* | gatsby build |
| Angular | angular.json | ng build |
| Vue CLI | vue.config.* | vue-cli-service build |
| Create React App | react-scripts in deps | react-scripts build |
| Ember | ember-cli-build.js | ember build |
| Hugo | config.toml / hugo.toml | hugo |
| Jekyll | _config.yml | jekyll build |
| Eleventy | .eleventy.js | eleventy |
| Docusaurus | docusaurus.config.* | docusaurus build |
| Static HTML | index.html at root | None |
Deployment Workflow
Step 1: Prerequisites
Ensure the Vercel CLI is installed:
npm install -g vercel
npx vercel
Step 2: Project Setup (First Time Only)
For new projects not yet linked to Vercel:
vercel link
vercel --yes
Step 3: Deploy
Preview Deployment (Default)
vercel
Production Deployment
vercel --prod
Zero-Auth Deployment (Agent Mode)
For automated deployments without authentication prompts:
VERCEL_TOKEN=your-token vercel --yes --token=$VERCEL_TOKEN
VERCEL_TOKEN=your-token npx vercel --yes --token=$VERCEL_TOKEN
Step 4: Deployment Output
Successful deployments return JSON-compatible metadata:
{
"url": "https://project-name-abc123.vercel.app",
"inspectUrl": "https://vercel.com/team/project/deployment-id",
"projectId": "prj_abc123",
"deploymentId": "dpl_abc123",
"readyState": "READY"
}
Use --json flag for machine-readable output:
vercel --json
Step 5: Post-Deployment Verification
vercel inspect <deployment-url>
vercel logs <deployment-url>
vercel list
Configuration Options
Environment Variables
vercel env add VARIABLE_NAME production
vercel env add VARIABLE_NAME preview
vercel env add VARIABLE_NAME development
vercel -e KEY=value -e KEY2=value2
Build Configuration
Override auto-detected settings in vercel.json:
{
"buildCommand": "npm run build",
"outputDirectory": "dist",
"installCommand": "npm install",
"framework": "vite",
"rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}
Custom Domains
vercel domains add example.com
vercel alias <deployment-url> example.com
Framework-Specific Patterns
Next.js
{
"framework": "nextjs",
"buildCommand": "next build",
"outputDirectory": ".next"
}
Next.js deployments automatically enable:
- Edge Runtime for middleware
- ISR (Incremental Static Regeneration)
- Image Optimization via
next/image
- Server Actions
Vite / React SPA
{
"framework": "vite",
"buildCommand": "vite build",
"outputDirectory": "dist",
"rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}
SvelteKit
{
"framework": "sveltekit",
"buildCommand": "vite build",
"outputDirectory": ".svelte-kit/output"
}
SvelteKit uses the @sveltejs/adapter-vercel adapter for optimal deployment.
Deployment Strategies
Preview per Pull Request
Configure GitHub integration for automatic preview deployments:
- Connect repository in Vercel dashboard
- Every PR gets a unique preview URL
- Comments added to PR with preview link
- Preview is torn down when PR is closed
Staged Rollouts
vercel --env ENVIRONMENT=staging
vercel promote <deployment-url>
Rollback
vercel list
vercel rollback <deployment-url>
Troubleshooting
Build Fails
- Check build logs:
vercel logs <url>
- Verify
buildCommand matches local build
- Check environment variables are set for the target environment
- Ensure Node.js version matches (use
engines in package.json)
404 on Client-Side Routes
Add rewrites for SPA frameworks:
{
"rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}
Large Bundle Warnings
- Enable tree-shaking in bundler config
- Use dynamic imports for heavy dependencies
- Check Vercel's bundle analysis:
vercel inspect --logs
Timeout Issues
- Serverless functions: Default 10s timeout (configurable up to 300s on Pro)
- Edge functions: 25ms CPU time limit (wall-clock can be longer with I/O)
- Static generation: 45s default timeout
{
"functions": {
"api/heavy-route.ts": {
"maxDuration": 60
}
}
}
Security Considerations
- Never commit
VERCEL_TOKEN to version control
- Use environment variables for secrets (not hardcoded)
- Enable Vercel's DDoS protection for production
- Use
vercel env pull to sync environment variables locally
- Review deployment protection settings for preview URLs
References
Iron Laws
- ALWAYS test the build locally before deploying to ensure the deployment will succeed
- NEVER deploy to production without first creating and validating a preview deployment
- ALWAYS verify environment variables are configured in the Vercel project before deploying
- NEVER store sensitive secrets in deployment commands or public URLs
- ALWAYS check the deployment logs immediately after deployment to confirm the build succeeded
Anti-Patterns
| Anti-Pattern | Why It Fails | Correct Approach |
|---|
| Deploying without local build test | Build fails in Vercel, wasted deployment attempt | Run build locally before vercel deploy |
| Skipping preview before production | Regressions reach users before detection | Always validate preview URL first |
| Hardcoded env vars in deploy command | Secrets exposed in shell history and logs | Configure env vars in Vercel project settings |
| Ignoring post-deploy build logs | Silent failures go undetected | Always check logs after deployment |
| No framework detection verification | Wrong settings cause build failures | Verify auto-detected framework in project config |
Framework Detection Patterns
Vercel CLI auto-detects frameworks by checking project files in this priority order:
| Framework | Detection File | Build Command | Output Dir |
|---|
| Next.js | next.config.* | next build | .next |
| Remix | remix.config.* | remix build | build |
| SvelteKit | svelte.config.* | vite build | build |
| Astro | astro.config.* | astro build | dist |
| Nuxt | nuxt.config.* | nuxt build | .output |
| Vite | vite.config.* | vite build | dist |
| Gatsby | gatsby-config.* | gatsby build | public |
| Angular | angular.json | ng build | dist |
| Vue CLI | vue.config.* | vue-cli-service build | dist |
| Create React App | react-scripts in pkg | react-scripts build | build |
| Docusaurus | docusaurus.config.* | docusaurus build | build |
| Eleventy | .eleventy.js | eleventy | _site |
| Hugo | config.toml (Hugo) | hugo | public |
| Jekyll |
When auto-detection fails, specify framework explicitly:
vercel --build-env FRAMEWORK_PRESET=nextjs
Environment Variable Management
Setting Environment Variables
vercel env add MY_VAR production
vercel env pull .env.local
vercel env ls
vercel env rm MY_VAR production
Environment Scopes
| Scope | When Applied | Use For |
|---|
production | Production deploys only | API keys, secrets |
preview | Preview deploys (PRs) | Staging configs |
development | vercel dev only | Local development |
Monorepo Configuration
For pnpm/npm/yarn workspaces:
{
"buildCommand": "cd ../.. && pnpm build --filter=my-app",
"installCommand": "pnpm install --filter=my-app...",
"rootDirectory": "packages/my-app"
}
Set root directory in Vercel dashboard or vercel.json:
{
"framework": "nextjs",
"buildCommand": "pnpm turbo build --filter=web",
"outputDirectory": "apps/web/.next"
}
Local Development
vercel dev — runs your project locally with Vercel's edge network simulation
- Supports: serverless functions, edge functions, environment variables
- Port: defaults to 3000, use
vercel dev --listen 3001 for custom port
- Hot reload: automatic for Next.js, SvelteKit, Astro, Nuxt
vercel dev
vercel dev --listen 3001
vercel.json Configuration Patterns
{
"rewrites": [{ "source": "/api/(.*)", "destination": "/api/index" }],
"redirects": [{ "source": "/old", "destination": "/new", "permanent": true }],
"headers": [{ "source": "/(.*)", "headers": [{ "key": "X-Frame-Options", "value": "DENY" }] }],
"functions":
Team & Project Config
vercel teams ls
vercel switch <team-slug>
vercel link
vercel project ls
Memory Protocol (MANDATORY)
Before starting:
Read .claude/context/memory/learnings.md
After completing:
- New pattern ->
.claude/context/memory/learnings.md
- Issue found ->
.claude/context/memory/issues.md
- Decision made ->
.claude/context/memory/decisions.md
