Smart Vercel Tool

Intelligent dispatcher for Vercel CLI operations that auto-detects project context, manages deployments, configures environment variables, and handles domain settings through a unified interface.

When to Use This Command

Run this command when you need to interact with the Vercel platform for deployments, environment management, or project configuration.

• You want to deploy your project to Vercel with automatic framework detection
• You need to manage environment variables across preview, development, and production
• You want to check deployment status, logs, or rollback to a previous deployment
• You need to configure custom domains, redirects, or serverless function settings

Use it also when:

• You are setting up a new Vercel project and linking it to your repository
• You need to inspect build logs or runtime logs for debugging

Quick Start

Copy
# .claude/commands/smart-vercel-tool.md
name: smart-vercel-tool
description: Intelligent Vercel CLI dispatcher
arguments:
  operation: The Vercel CLI operation to execute

Copy
# Deploy to preview environment
claude smart-vercel-tool "deploy"

Expected output:
Deploying to Vercel...
  Framework: Next.js (auto-detected)
  Project: my-saas-app
  Environment: Preview

  Build: SUCCESS (42s)
  URL: https://my-saas-app-abc123.vercel.app

  Deployment ID: dpl_abc123xyz
  Status: READY

Core Concepts

Concept	Description
Deployment	A build and publish of your application to Vercel's edge network
Environment	Target context: production, preview, or development
Project	A Vercel project linked to a git repository
Environment Variable	Key-value pair scoped to specific environments
Domain	Custom domain mapped to a Vercel deployment

Vercel Deployment Flow:
  Source Code ──> Build ──> Deploy ──> Edge Network
       │           │         │            │
       v           v         v            v
  Framework    Serverless   CDN      Global Edge
  Detection    Functions    Assets   Distribution

Configuration

Parameter	Default	Description
operation	required	Vercel CLI command: deploy, env, domains, logs
prod	false	Deploy to production (adds --prod flag)
force	false	Force a new deployment even without changes
env-target	all	Environment scope: production, preview, development
project	auto-detect	Vercel project name or ID

Best Practices

1. Use preview deployments for PRs -- Every pull request should get a preview deployment for testing. Avoid deploying directly to production without review.

2. Scope environment variables to the correct target -- Production secrets should not be available in preview deployments. Use --environment production when adding sensitive variables.

3. Check deployment logs for build failures -- Use vercel logs <deployment-url> to inspect both build-time and runtime errors for debugging.

4. Use vercel.json for advanced configuration -- Redirects, rewrites, headers, and serverless function settings should be defined in vercel.json for version-controlled configuration.

5. Link your project before first deploy -- Run vercel link to connect your local project to a Vercel project. This sets up the .vercel directory for subsequent deployments.

Common Issues

1. Not logged in to Vercel CLI -- Run vercel login to authenticate. The CLI stores credentials locally and requires re-authentication periodically.

2. Build fails with missing environment variables -- Environment variables set locally may not exist in Vercel. Add them with vercel env add for the target environment.

3. Wrong framework detected -- Vercel auto-detects frameworks from package.json. Override with vercel.json settings if detection is incorrect: {"framework": "nextjs"}.