Step-by-step guide using Vercel CLI to build Next.js locally, prepare .vercel/output, and deploy with --prebuilt for…
In-depth Next.js guides covering App Router, RSC, ISR, and deployment. Get code examples, optimization checklists, and prompts to accelerate development.
No spam. Unsubscribe anytime.
You're building a static Next.js site with assets or data sources that only exist locally — Figma MCP for design assets, a local Payload CMS instance, or a development API running on localhost:3845. When you push to Vercel, the build fails because Vercel doesn't have access to these local resources. This guide is for developers who need to build where their resources are accessible and ship to Vercel without a remote rebuild. By the end, you'll have a repeatable deploy workflow using vercel build and --prebuilt that ships exactly what you built locally.
The standard approach — letting Vercel rebuild your site — doesn't work here. You need to build where your resources are accessible, then deploy that build to Vercel without it trying to rebuild.
This guide shows you exactly how to do that using the Vercel CLI with the --prebuilt flag.
This isn't just a workaround for development. This workflow is genuinely useful for:
The key insight is this: Vercel doesn't have to build every time you deploy. You can build locally where your development tools live, then push the pre-built output directly to Vercel.
Before starting, make sure you have:
next build working locallyFirst, install the Vercel CLI globally so you can use it from anywhere:
pnpm add -g vercel
Next, authenticate with your Vercel account:
vercel login
This opens a browser window to authenticate. Once complete, you're ready to link projects.
Navigate to your project directory and link it:
vercel link
The CLI will ask you a few questions:
? Set up and deploy "~/Documents/Projects/your-project"? yes
? Which scope should contain your project? [Your Account/Team Name]
? Found project "your-account/your-project". Link to it? yes
This creates a .vercel/ directory in your project with metadata about the Vercel deployment. You can .gitignore this directory if you prefer, or commit it—either works.
Since you're building locally where assets are available, you want Next.js to prerender everything as static. Add this to your app entry point:
// File: src/app/page.tsx
export const dynamic = 'force-static'
This tells Next.js to prerender your pages at build time, creating fully static HTML files. This is crucial because it ensures all your Figma MCP assets and localhost data are baked into the HTML during the local build.
Build your project where all your local resources are available:
pnpm run build
You should see output showing successful compilation:
✓ Compiled successfully
✓ Finished TypeScript
✓ Collecting page data
✓ Generating static pages
At this point, your site is built and ready. All your Figma assets are fetched and included in the static output.
Run the Vercel build command locally. This doesn't rebuild your Next.js project—instead, it converts your .next folder into Vercel's output format (.vercel/output):
npx vercel build
You might see a prompt asking to pull project settings:
? No Project Settings found locally. Run `vercel pull` for retrieving them? yes
Confirm this. The command then creates .vercel/output containing your pre-built site ready for Vercel's infrastructure.
The output confirms everything is ready:
✅ Build Completed in .vercel/output [18s]
Now deploy your pre-built output. For a preview deployment first:
npx vercel --prebuilt
This deploys to a preview URL, letting you verify everything looks correct before going to production. The output shows:
🔍 Inspect: https://vercel.com/[your-project]/[deployment-id]
✅ Preview: https://[preview-url].vercel.app [6s]
Once you've verified the preview looks good, promote it to production:
npx vercel --prod
This makes your preview deployment the live production site. Your site is now live on Vercel without Vercel ever attempting to rebuild it.
You can create a simple shell script to automate the full workflow:
#!/bin/bash
# File: scripts/deploy.sh
echo "Building locally..."
pnpm run build
echo "Preparing Vercel output..."
npx vercel build --prod
echo "Deploying to Vercel..."
npx vercel deploy --prod --prebuilt
echo "✅ Deployment complete!"
Make it executable:
chmod +x scripts/deploy.sh
Then deploy anytime with:
./scripts/deploy.sh
In a standard Vercel deployment, the flow is: Code pushed → Vercel builds → Vercel deploys. With pre-built deploys, it's: Build locally → Vercel deploys only. You skip the build step entirely.
This is powerful because:
localhost:3845, Figma MCP, and other local toolsThe tradeoff is that you're manually triggering deployments instead of automatic deploys on every git push. For static sites with local assets, this is usually the right choice.
When to use this approach: Your site is truly static with all data available at build time, or you control when content updates happen.
When not to use this: If you need automatic deployments when content changes in a CMS, or when you want CI/CD to manage builds, stay with standard Vercel builds and ensure your resources are available during Vercel's build step (usually via environment variables or APIs with proper authentication).
Git considerations: You typically don't commit .next/ or .vercel/output/ to git. These are build artifacts. Just commit your source code, and the build happens locally each time you want to deploy.
This workflow is perfect for the current phase of your project where you're working with design assets via Figma MCP and building your component system. When you eventually integrate with a real backend that's production-accessible, you can switch back to standard Vercel builds with automatic deployments on every push.
For now, you have full control: build locally where your tools live, deploy instantly to Vercel without rebuild delays, and maintain a completely static site that loads at maximum speed.
For static sites built this way, the unstable_cache vs use cache comparison for Next.js is worth reading when your data layer grows and you need fine-grained revalidation. If you're deploying a full-stack Next.js + Payload CMS app to your own infrastructure instead, the self-hosted Next.js 16 + Payload deployment guide covers Docker, CI/CD, and production configuration. To cut Vercel bandwidth costs as traffic grows, reducing Vercel ISR fast origin transfer covers the caching levers available on the platform.
Let me know in the comments if you have questions about this workflow, and subscribe for more practical development guides.
Thanks, Matija