Deploy to Vercel

Deploy a Next.js application to Vercel with production configuration.

When to Use

• Deploying a Next.js app for the first time
• Setting up preview deployments for pull requests
• Configuring custom domains
• Managing environment variables in production

Inputs

• Required: Next.js application that builds successfully locally
• Required: GitHub repository (recommended) or local project
• Optional: Custom domain
• Optional: Environment variables for production

Procedure

Step 1: Verify Local Build

npm run build

Expected: Build succeeds with no errors.

On failure: Fix build errors before deploying. Common: TypeScript errors, missing dependencies, invalid imports.

Step 2: Install Vercel CLI

npm install -g vercel

Expected: The vercel command is available globally and vercel --version prints the installed version.

On failure: If permission errors occur, use sudo npm install -g vercel or configure npm to use a user-local prefix. Verify Node.js is installed with node --version.

Step 3: Link and Deploy

# Login to Vercel
vercel login

# Deploy (first time: creates project)
vercel

# Follow prompts:
# - Set up and deploy? Y
# - Which scope? (select your account)
# - Link to existing project? N (for new projects)
# - Project name: my-app
# - Directory: ./
# - Override settings? N

Expected: Preview URL provided (e.g., https://my-app-xxx.vercel.app).

On failure: If vercel login fails, check internet connectivity and try browser-based authentication. If the deploy fails, review the build output for errors -- Vercel uses a clean environment, so all dependencies must be in package.json.

Step 4: Configure Environment Variables

# Add environment variables
vercel env add DATABASE_URL production
vercel env add API_KEY production preview

# List environment variables
vercel env ls

Or configure through the Vercel dashboard: Project Settings > Environment Variables.

Expected: vercel env ls shows all required environment variables configured for the correct environments (production, preview, development).

On failure: If variables are not appearing at runtime, verify the target environment matches (production vs preview). Redeploy after adding variables -- existing deployments do not pick up new variables automatically.

Step 5: Deploy to Production

vercel --prod

Expected: Production URL available (e.g., https://my-app.vercel.app).

On failure: Check deployment logs with vercel logs or in the Vercel dashboard. Common issues include missing environment variables in the production environment and build commands differing from local setup.

Step 6: Connect GitHub for Auto-Deploy (Recommended)

1. Go to https://vercel.com/new
2. Import your GitHub repository
3. Vercel automatically deploys on:
   • Push to main -> Production deployment
   • Pull request -> Preview deployment

Expected: The Vercel dashboard shows the GitHub repository connected, and subsequent pushes to main trigger production deployments automatically.

On failure: If the repository does not appear in the import list, check that the Vercel GitHub app has access to the repository. Go to GitHub Settings > Applications > Vercel and grant access.

Step 7: Configure Custom Domain

vercel domains add my-domain.com

Or through dashboard: Project Settings > Domains.

Update DNS records as instructed by Vercel (typically CNAME or A record).

Expected: vercel domains ls shows the custom domain as configured, and after DNS propagation (up to 48 hours), the domain resolves to the Vercel deployment.

On failure: If the domain shows "Invalid Configuration," verify DNS records match Vercel's instructions exactly. Use dig my-domain.com or an online DNS checker to confirm propagation.

Step 8: Optimize Configuration

Create vercel.json for advanced settings:

{
  "framework": "nextjs",
  "regions": ["iad1"],
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "no-store" }
      ]
    }
  ]
}

Expected: vercel.json is saved in the project root and the next deployment picks up the configuration (visible in the Vercel dashboard build logs).

On failure: If the configuration is ignored, verify vercel.json is valid JSON with jq . vercel.json. Check the Vercel docs for your framework version, as some settings may have moved to next.config.ts.

Validation

• npm run build succeeds locally
• Preview deployment works and is accessible
• Production deployment serves the application correctly
• Environment variables are available in production
• Custom domain resolves (if configured)
• GitHub integration triggers deployments on push

Common Pitfalls

• Build failing on Vercel but not locally: Vercel uses a clean environment. Ensure all dependencies are in package.json, not just installed globally.
• Environment variables missing: Variables must be added to Vercel, not just .env.local. Different environments (production, preview, development) have separate variable sets.
• Node.js version mismatch: Set the Node.js version in Project Settings or package.json engines field.
• Large deployments: Vercel has size limits. Use .vercelignore to exclude unnecessary files.
• API route timeouts: Vercel serverless functions have a 10s timeout on the Hobby plan. Optimize or upgrade.

Related Skills

• scaffold-nextjs-app - create the app to deploy
• setup-tailwind-typescript - configure styling before deployment
• configure-git-repository - Git setup for auto-deploy integration