vercel-deployment
Vercel deployment workflows, environment management, domain configuration, and build troubleshooting. Use when deploying, checking deployment status, reviewing build logs, or managing environments.
git clone --depth 1 https://github.com/monkilabs/opencastle /tmp/vercel-deployment && cp -r /tmp/vercel-deployment/src/orchestrator/plugins/vercel ~/.claude/skills/vercel-deploymentSKILL.md
# Vercel Deployment
Vercel-specific deployment patterns and MCP tool usage. For project-specific deployment architecture, environment variables, and key files, see [deployment-config.md](../../.opencastle/stack/deployment-config.md).
## Deployment Model
Branch → Environment mapping:
| Branch pattern | Environment |
|----------------|-------------|
| `main` | Production deployment (auto) |
| `feature/*`, `fix/*` | Preview deployment (auto) |
## MCP Tools
The Vercel MCP server provides these tools through `https://mcp.vercel.com`:
| Tool | Purpose |
|------|---------|
| `deploy_to_vercel` | Trigger a deployment |
| `get_deployment` | Check deployment status and metadata |
| `get_deployment_build_logs` | Read build output for debugging |
| `get_runtime_logs` | Read runtime logs for debugging |
| `list_deployments` | List recent deployments |
| `get_project` | Get project configuration |
| `list_projects` | List all projects in the team |
| `list_teams` | List available teams |
| `search_vercel_documentation` | Search Vercel docs |
| `check_domain_availability_and_price` | Domain availability check |
## Environment Variables
### Vercel Environment Scoping
Vercel supports three environment scopes — set variables for each appropriately:
| Scope | When Applied | Use For |
|-------|-------------|---------|
| **Production** | `main` branch deploys | Live secrets, production API keys |
| **Preview** | All non-production branches | Staging/test API keys |
| **Development** | `vercel dev` local server | Local development overrides |
### Best Practices
Verify required env vars exist in production and preview scopes; see REFERENCE.md for details.
## Build Troubleshooting
When builds fail, follow this workflow:
1. **Read build logs** — use `get_deployment_build_logs` to get the full output
2. **Check common causes:**
- Missing environment variables
- Node.js version mismatch (check `engines` in `package.json`)
- Build command mismatch (verify in project settings)
- Dependency resolution issues (lockfile out of sync)
3. **Check runtime logs** — use `get_runtime_logs` for post-deploy errors
4. **Verify deployment status** — use `get_deployment` to check state and error details
### Example troubleshooting commands (MCP payloads)
1) Get build logs:
```json
// tool: vercel/get_deployment_build_logs
{ "deployment_id": "dpl_abc123" }
```
2) Get runtime logs:
```json
// tool: vercel/get_runtime_logs
{ "deployment_id": "dpl_abc123", "limit": 200 }
```
3) Re-deploy a specific commit after fixing an issue:
```json
// tool: vercel/deploy_to_vercel
{ "project_id": "proj_xxx", "gitCommitSha": "abcd1234" }
```
After re-deploying, re-check `get_deployment_build_logs` and `get_runtime_logs` to confirm the fix. Repeat until build succeeds.
## Cron Jobs (vercel.json)
Configure cron jobs in `vercel.json` under `crons[]` with path and schedule.Creates pages/layouts, defines content collections, configures hydration directives, and wires integrations. Use when adding or modifying Astro pages, layouts, components, or content collections. Trigger terms: Astro, content collection, client:load, client:visible, astro:content
Drive real browsers via Chrome DevTools MCP: navigate pages, capture snapshots, run responsive checks, and collect console/perf traces. Use when the user mentions: 'validate UI change in Chrome', 'capture a screenshot', 'run responsive checks', or 'collect console logs'. Trigger terms: browser testing, DevTools, console logs, screenshot, responsive testing
Creates and deploys Cloudflare Workers, configures wrangler.toml bindings, sets up KV/D1/R2 storage and Durable Objects, manages Pages deployments, and implements edge function patterns. Use when building or deploying Cloudflare Workers, setting up Pages, working with KV/D1/R2 storage, configuring wrangler.toml, or deploying edge applications.
Creates Contentful content types, queries entries via GraphQL/REST, runs CLI migrations, and manages assets and locales. Use when building or modifying Contentful content models, writing queries, or migrating content.
Convex reactive database patterns, schema design, real-time queries, mutations, actions, authentication, migrations, performance optimization, and component creation. Use when designing Convex schemas, writing queries/mutations, managing the Convex backend, setting up auth, migrating data, optimizing performance, or building Convex components.
Deploys applications, databases, and services on self-hosted Coolify instances, manages environments and env vars, runs infrastructure diagnostics, and performs batch operations. Use when deploying apps to Coolify, managing Coolify servers, debugging deployment issues, setting up databases, or managing Coolify infrastructure.
Writes Cypress E2E/component tests, configures `cy.intercept()` and `cy.session()`, authors custom commands, and wires CI artifacts. Use when creating E2E specs, component tests, or CI test pipelines. Trigger terms: cypress, e2e, component test, cy.intercept, cy.session
Drizzle ORM schema definition, type-safe queries, relational queries, CRUD operations, transactions, migrations with drizzle-kit, and database setup for PostgreSQL, MySQL, and SQLite. Use when defining database schemas, writing queries or joins, managing migrations, setting up a new Drizzle project, or working with drizzle-kit.