deploy-to-vercel
Deploy a Next.js application to Vercel. Covers project linking, environment variables, preview deployments, custom domains, and production deployment configuration. Use when deploying a Next.js app for the first time, setting up preview deployments for pull requests, configuring custom domains, or managing environment variables in a production Vercel deployment.
- License 许可
- MIT
- 最近更新
- 2026-05-19
- Stars
- ★ 10
- Forks
- 2
01 前言 Front Matter
- name
- deploy-to-vercel
- locale
- caveman-lite
- license
- MIT
- metadata
- { "tags": "vercel, deployment, nextjs, hosting, ci-cd", "author": "Philipp Thoss", "domain": "web-dev", "version": "1.0", "language": "TypeScript", "complexity": "basic" }
- translator
- Julius Brussee homage — caveman
- description
- Deploy a Next.js application to Vercel. Covers project linking, environment variables, preview deployments, custom domains, and production deployment configuration. Use when deploying a Next.js app for the first time, setting up preview deployments for pull requests, configuring custom domains, or managing environment variables in a production Vercel deployment.
- allowed-tools
- Read Write Edit Bash Grep Glob
- source_commit
- 82c77053
- source_locale
- en
- translation_date
- 2026-04-23
03 SKILL.md 正文
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
Got: Build succeeds with no errors.
If fail: Fix build errors before deploying. Common: TypeScript errors, missing dependencies, invalid imports.
Step 2: Install Vercel CLI
npm install -g vercel
Got: The vercel command is available globally and vercel --version prints the installed version.
If fail: 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
Got: Preview URL provided (e.g., https://my-app-xxx.vercel.app).
If fail: 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.
Got: vercel env ls shows all required environment variables configured for the correct environments (production, preview, development).
If fail: 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
Got: Production URL available (e.g., https://my-app.vercel.app).
If fail: 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
Got: The Vercel dashboard shows the GitHub repository connected, and subsequent pushes to main trigger production deployments automatically.
If fail: 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).
Got: vercel domains ls shows the custom domain as configured, and after DNS propagation (up to 48 hours), the domain resolves to the Vercel deployment.
If fail: 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" }
]
}
]
}
Got: vercel.json is saved in the project root and the next deployment picks up the configuration (visible in the Vercel dashboard build logs).
If fail: 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 buildsucceeds 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
Pitfalls
- Build failing on Vercel but not locally: Vercel uses a clean environment. Ensure all dependencies are in
package.json, not installed globally. - Environment variables missing: Variables must be added to Vercel, not
.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.jsonengines field. - Large deployments: Vercel has size limits. Use
.vercelignoreto 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
04 同仓库更多 Skills
zarr-python
Chunked N-D arrays for cloud storage. Compressed arrays, parallel I/O, S3/GCS integration, NumPy/Dask/Xarray compatible, for large-scale scientific computing pipelines.
youtube-downloader
Download and process YouTube content for research. Use when: downloading competitor videos for analysis; extracting audio for podcasts; getting transcripts for content repurposing; archiving webinars; research content curation
yc-pitch-deck
Create a compelling startup pitch deck that follows the structure proven to raise billions from top investors. Master the YC and Sequoia formats that get founders funded. Use when: **Fundraising** to create investor pitch decks; **YC application** to structure your narrative; **Demo Day prep** to craft your 2-minute pitch; **Angel investors** to communicate your opportunity; **Partnership pitches** to structure compelling asks
x-twitter-scraper
Use when the user needs X (Twitter) data or confirmation-gated X actions through Xquik: tweet search, user lookup, follower extraction, media download, monitoring, webhooks, MCP, SDKs, posting, likes, DMs, and profile updates. Requires a Xquik API key. Never ask for X login material.
write-vignette
Create R package vignettes using R Markdown or Quarto. Covers vignette setup, YAML configuration, code chunk options, building and testing, and CRAN requirements for vignettes. Use when adding a Getting Started tutorial, documenting complex workflows spanning multiple functions, creating domain-specific guides, or when CRAN submission requires user-facing documentation beyond function help pages.
write-validation-documentation
Write IQ/OQ/PQ validation documentation for computerized systems in regulated environments. Covers protocols, reports, test scripts, deviation handling, and approval workflows. Use when validating R or other software for regulated use, preparing for a regulatory audit, documenting qualification of computing environments, or creating and updating validation protocols and reports for new or re-qualified systems.