Migrate from Vercel to Build
Build runs Next.js through standard application deployment, so your frontend builds and deploys from the same repository.
Server-side code is where the two platforms differ. Vercel runs it as Functions, invoked per request. Build runs processes that stay up, so code written as a Function becomes a route in a persistent web process, or a worker. That switch is the bulk of the work in a Vercel migration.
There are two parts to a migration: your application, and your data.
For a comparison of the two platforms, see Compare Build & Vercel.
1. Work out what has to be rewritten
Section titled “1. Work out what has to be rewritten”Go through what Vercel runs for you and sort it:
- Moves as-is = Pages, static assets, and anything that builds from your repository.
- Becomes a route in a persistent process = Functions and Fluid Compute that serve requests.
- Becomes a worker or a scheduled job = Cron jobs, Workflows, and anything durable or long-running.
Work split into invocations purely to fit Vercel’s model often simplifies here, because a process that stays up can just hold the connection or the state.
If you are unsure about any part of your Vercel setup, particularly edge middleware or framework-specific features, Build’s support team can help map it.
2. Create the app on Build
Section titled “2. Create the app on Build”Open the team you are deploying into and click New app. Set the team, the pipeline, and the stage.
Connect your GitHub repository and set the stack and buildpacks, or point Build at a Dockerfile. Build builds container images, which Vercel does not, so a Dockerfile is a reasonable choice if you want full control of the runtime. See Deploying applications.
3. Define your processes
Section titled “3. Define your processes”Your application’s processes live in a Procfile. A typical Next.js application needs only a web process. Add worker processes for anything that was a Function doing background work, and scheduled jobs for anything that was cron.
The difference worth internalizing: a Build scheduled job is an application process, not a trigger that invokes a function.
4. Bring your environment variables across
Section titled “4. Bring your environment variables across”Copy your Vercel environment variables into the Build app’s config vars, keeping your preview, development and production values separate across the stages of your pipeline.
Leave database connection strings until you have provisioned the database.
5. Deploy and check
Section titled “5. Deploy and check”Scale your web process to one dyno, then open the app and confirm it serves as it does on Vercel.
Check the things Vercel did for you that now belong to your application or to Build: caching behavior, image handling, and any redirects or rewrites that lived in Vercel configuration rather than your code.
Your database
Section titled “Your database”Vercel provides data through marketplace integrations with third-party providers. Those are not portable, so the equivalent Build add-on is provisioned and the data migrated. Postgres is replaced by Schema To Go.
- Provision the database on Build. Set
import_urlto your existing database when you create it, and Build pulls the data across for you. - Attach it to your app. In the add-on’s Attachments section, choose Attach to App and set the attached-as name to
DATABASE, so your app seesDATABASE_URL. - Redeploy.
If your data lives with a third-party provider rather than on Vercel itself, you may prefer to keep it there at first and point the Build app at it, then move it separately once the application is stable.
Engineer-led migration support is included on Enterprise plans. Talk to us before you move production data.
6. Cut over
Section titled “6. Cut over”When you are satisfied, move traffic by pointing DNS at Build. Your Vercel deployment keeps running, so you can point DNS back if you need to.
Need help
Section titled “Need help”See Get support, or talk to an engineer about your migration.
