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)
- Go to https://vercel.com/new
- Import your GitHub repository
- 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
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 deploysetup-tailwind-typescript - configure styling before deploymentconfigure-git-repository - Git setup for auto-deploy integration