Migration runbook

Move a Next.js App Off Vercel

Convert a Vercel-bound Next.js project into a portable Node.js deployment before choosing or changing infrastructure.

By HostNextJS Editorial TeamReviewed by HostNextJS Technical Review Published Updated
01Typemigration
02Last reviewed
03Update policyReview every 90 days and within 14 days of material Next.js self-hosting or Vercel runtime changes.
Controlled change

Migration controls

01

Inventory

  • All vercel.json routes, headers, redirects, crons, functions, regions, and runtime settings
  • Environment variable names by Production, Preview, Development, and integration ownership
  • Blob, database, cache, analytics, image, email, authentication, and webhook dependencies
  • ISR, revalidation, streaming, Proxy or middleware, Server Functions, and after() usage
02

Validation

  • The production artifact starts with only documented runtime files and variables
  • NEXT_PUBLIC values are correct in the built client and server-only values are unavailable to the browser
  • Dynamic routes, images, streaming, ISR, revalidation, Server Functions, and shutdown behavior pass
  • Cron, uploads, webhooks, authentication, payments, email, and analytics reach the intended replacement services
03

Rollback

  • Keep the current Vercel production deployment unchanged while portability tests run
  • Make replacement service writes reversible or dual-readable before any traffic switch
  • Tag the last portable artifact and preserve the exact configuration manifest used to validate it
  • Do not remove Vercel integrations until their replacement data and events reconcile
  1. 01

    Produce a portable artifact

    Enable standalone output or a controlled next start build, copy required public and static assets, and run the artifact without Vercel CLI.

  2. 02

    Replace platform interfaces

    Move scheduled requests, object storage, configuration, analytics, and other managed dependencies behind documented services and application-owned adapters.

  3. 03

    Reproduce runtime behavior

    Add a reverse proxy, process supervision, health checks, graceful shutdown, persistent cache behavior, logs, and alerting in a production-like environment.

  4. 04

    Prove the same commit

    Run representative routes and business transactions against Vercel and the portable target, then record intentional differences before provider cutover.

Make the application portable before provisioning its final home. This separates code and service compatibility failures from provider networking and server setup, which makes both testing and rollback easier to reason about.

Establish a plain Node.js baseline

Run a production build outside Vercel using next start or standalone output. Copy .next/static and public when using standalone output, bind the service only behind a reverse proxy, and confirm the process handles SIGTERM with enough drain time for in-flight work and after() callbacks.

Treat filesystem cache as a deliberate choice. A single persistent instance can use the default disk cache. Multiple or ephemeral instances need a durable shared cache, coordinated tag invalidation, a consistent Server Functions encryption key, and a deployment identifier.

Remove hidden platform coupling

Search code and configuration for Vercel SDKs, request headers, regions, cron declarations, Blob calls, analytics, and integration-provided variables. Record replacement ownership before changing code. A portable interface is useful only when its data model, access mode, retries, and failure behavior are also understood.

Scheduled work needs authentication, overlap protection, retries, and observable outcomes. Object storage needs an explicit public/private policy, migration verification, and a plan for old URLs. Never assume a similarly named service has identical semantics.

Compare behavior, not just status codes

Exercise the same commit on both environments. Verify HTML, headers, cookies, redirects, streamed responses, optimized images, revalidation, uploads, callbacks, and business events. Capture latency and errors, but also inspect whether writes, scheduled work, and external side effects happen exactly once.

Only after this baseline passes should the provider-specific cutover begin.

Methodology

How this resource was produced

This guide isolates application portability work from infrastructure cutover. It maps Vercel-managed runtime, configuration, storage, and scheduling behavior to explicit portable interfaces, then tests one production build outside Vercel.

Limitations
  • 01

    This guide cannot infer hidden integration configuration, undocumented data flows, or code that depends on Vercel-specific request metadata.

  • 02

    Replacing managed services can change latency, consistency, security, and failure behavior even when the API looks similar.

FAQ

Questions about move a next.js app off vercel.

No fog. Just the practical details developers need before moving a production app.

Do I need to rewrite Next.js to leave Vercel?

Usually no. Start with a normal Node.js or standalone build, then replace only platform-specific services and assumptions found in the inventory.

Can one Docker image move between environments?

Yes, but NEXT_PUBLIC values are embedded during next build. Runtime server values can vary when the application reads them during dynamic rendering.

Next step

Turn the resource into a deployment decision.

Generate a dependency checklist