deploy-app

name	deploy-app
description	Step-by-step plan for deploying a Next.js app to Vercel

Deploy App Implementation Plan

For Claude: Follow this plan task-by-task. If any step fails, notify the user and ask for next steps.

Goal: Deploy a Next.js application to Vercel with proper environment configuration.

Architecture: Vercel handles build, deployment, and hosting. Environment variables are configured via Vercel dashboard or CLI.

Tech Stack: Vercel, Next.js

---

Phase 1: Pre-Deployment Checks

Task 1: Verify Build

Step 1: Run production build

npm run build

Ensure the build completes without errors.

Step 2: Fix any build errors

If there are TypeScript or build errors, fix them before proceeding.

---

Phase 2: Vercel Setup

Task 2: Check Vercel Authentication

Step 1: Check if already logged in

npx vercel whoami

If this returns a username, skip to Task 3.

Step 2: If not logged in

Tell the user: "You need to authenticate with Vercel. Please run npx vercel login in a separate terminal and let me know when you're done."

Wait for the user to confirm before proceeding.

Step 3: Verify login succeeded

npx vercel whoami

Confirm it now returns a username before proceeding.

---

Task 3: Link Project

Step 1: Check if already linked

Check if a .vercel directory exists in the project root. If it does, the project is already linked - skip to Task 4.

Step 2: Check for existing projects

npx vercel projects list

Look for a project with a similar name to the current app. If found, ask "I found a Vercel project named <project-name>. Would you like to link to this existing project, or create a new one?". If creating a new one, generate a new project name and you must confirm the new name with the user.

Step 3: Link to project

Always provide a project name to the following command:

npx vercel link --project=<project-name> -y

---

Phase 3: Configure Environment

Task 4: Set Environment Variables

Step 1: Upload env vars to Vercel

Use the upload_env_to_vercel MCP tool to upload all environment variables from your .env file to Vercel.

This uploads to production and preview environments by default.

Step 2: Handle skipped variables

If the tool reports any skipped_empty variables, warn the user:

"The following environment variables had empty values and were not uploaded: <list>. You'll need to set these manually in the Vercel dashboard or by running npx vercel env add <VAR_NAME> for each one."

Step 3: Verify all env vars are set

npx vercel env ls

---

Phase 4: Deploy

Task 5: Deploy to Vercel

Step 1: Deploy

npx vercel deploy 

Step 2: Verify deployment

Use the open_app MCP tool to open the deployed URL and verify the app works.

---

Task 6: Offer Next Steps

Ask the user if they want to:

• Set up a custom domain
• Configure automatic deployments from GitHub
• Add preview deployments for pull requests