Step-by-step plan for deploying a Next.js app to Vercel
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
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.
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.
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
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
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.
Ask the user if they want to:
