Agent-Skills.md

Agent Skills: Vercel Deploy

Deploy applications and websites to Vercel. Use this skill when the user requests deployment actions such as "Deploy my app", "Deploy this to production", "Create a preview deployment", "Deploy and give me the link", or "Push this live". No authentication required - returns preview URL and claimable deployment link.

UncategorizedID: oimiragieo/agent-studio/vercel-deploy

Repository

oimiragieo/agent-studio
oimiragieo
19

Install this agent skill to your local

pnpm dlx add-skill https://github.com/oimiragieo/agent-studio/tree/HEAD/.claude/skills/vercel-deploy

Skill Files

Browse the full folder contents for vercel-deploy.

Download Skill

Loading file tree…

.claude/skills/vercel-deploy/SKILL.md

Skill Metadata

Name
vercel-deploy
Description
Zero-auth Vercel deployment workflow with automatic framework detection for 20+ frameworks. Use when deploying web applications to Vercel, creating preview deployments, or setting up deployment pipelines. Supports Next.js, Vite, Remix, SvelteKit, Astro, Nuxt, and more.

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:

# Install globally
npm install -g vercel

# Or use npx (no install needed)
npx vercel

Step 2: Project Setup (First Time Only)

For new projects not yet linked to Vercel:

# Interactive setup -- creates .vercel/project.json
vercel link

# Or create a new project
vercel --yes

Step 3: Deploy

Preview Deployment (Default)

# Deploy to preview environment
vercel

# Output:
# Vercel CLI 34.x.x
# Linked to username/project-name
# Inspect: https://vercel.com/username/project-name/abcdef
# Preview: https://project-name-abc123.vercel.app

Production Deployment

# Deploy to production
vercel --prod

# Output includes production URL:
# Production: https://project-name.vercel.app

Zero-Auth Deployment (Agent Mode)

For automated deployments without authentication prompts:

# Using VERCEL_TOKEN environment variable
VERCEL_TOKEN=your-token vercel --yes --token=$VERCEL_TOKEN

# Or with npx for zero-install
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

# Check deployment status
vercel inspect <deployment-url>

# View deployment logs
vercel logs <deployment-url>

# List recent deployments
vercel list

Configuration Options

Environment Variables

# Set environment variables for deployment
vercel env add VARIABLE_NAME production
vercel env add VARIABLE_NAME preview
vercel env add VARIABLE_NAME development

# Or pass inline
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

# Add a custom domain
vercel domains add example.com

# Assign domain to project
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:

  1. Connect repository in Vercel dashboard
  2. Every PR gets a unique preview URL
  3. Comments added to PR with preview link
  4. Preview is torn down when PR is closed

Staged Rollouts

# Deploy to staging first
vercel --env ENVIRONMENT=staging

# Promote to production after validation
vercel promote <deployment-url>

Rollback

# List recent deployments
vercel list

# Rollback to a previous deployment
vercel rollback <deployment-url>

Troubleshooting

Build Fails

  1. Check build logs: vercel logs <url>
  2. Verify buildCommand matches local build
  3. Check environment variables are set for the target environment
  4. 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

  1. Enable tree-shaking in bundler config
  2. Use dynamic imports for heavy dependencies
  3. 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

  1. ALWAYS test the build locally before deploying to ensure the deployment will succeed
  2. NEVER deploy to production without first creating and validating a preview deployment
  3. ALWAYS verify environment variables are configured in the Vercel project before deploying
  4. NEVER store sensitive secrets in deployment commands or public URLs
  5. 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 | _config.yml (Jekyll) | jekyll build | _site | | Static HTML | index.html only | none | . |

When auto-detection fails, specify framework explicitly:

vercel --build-env FRAMEWORK_PRESET=nextjs

Environment Variable Management

Setting Environment Variables

# Add env var (prompts for value)
vercel env add MY_VAR production

# Add from .env file
vercel env pull .env.local

# List all env vars
vercel env ls

# Remove env var
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                    # Start local dev server on port 3000
vercel dev --listen 3001      # Custom port

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": { "api/heavy.js": { "memory": 3009, "maxDuration": 60 } },
  "crons": [{ "path": "/api/cron", "schedule": "0 * * * *" }]
}

Team & Project Config

vercel teams ls                 # List teams
vercel switch <team-slug>       # Switch active team
vercel link                     # Link local dir to Vercel project
vercel project ls               # List projects in current team

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