Migration runbook

Migrate Next.js from Vercel

Inventory, test, cut over, validate, and roll back a Next.js migration from Vercel without treating DNS as the whole migration.

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

Migration controls

01

Inventory

  • Production, preview, development, and integration-managed environment variables
  • Functions, regions, timeouts, cron jobs, queues, and background work
  • Blob or object storage, databases, caches, analytics, email, and authentication integrations
  • Domains, redirects, rewrites, headers, image sources, and callback URLs
  • ISR, cache invalidation, streaming, middleware or Proxy, and Edge runtime usage
02

Validation

  • Critical pages and APIs return expected status, content, headers, and latency
  • Authentication, payments, email, webhooks, uploads, and scheduled work complete
  • Logs, error alerts, health checks, backups, and restore instructions are usable
  • TLS, redirects, canonical URLs, robots, sitemap, analytics, and callbacks use the production hostname
03

Rollback

  • Keep the last known-good Vercel production deployment and its required integrations active
  • Record the previous DNS values and the exact authority required to restore them
  • Define thresholds and one decision owner for rollback before cutover begins
  • After rollback, verify writes and external events created during the target window
  1. 01

    Inventory platform dependencies

    Map every Vercel-managed capability and secret to an explicit target service or implementation.

  2. 02

    Build the target in parallel

    Deploy the same commit behind a temporary hostname with production-equivalent configuration.

  3. 03

    Exercise a written test plan

    Verify critical journeys, callbacks, jobs, caching, images, streaming, logs, and recovery before DNS changes.

  4. 04

    Cut over with a rollback window

    Lower DNS TTL in advance, freeze risky changes, switch traffic, and monitor both technical and business signals.

A safe migration moves capabilities, configuration, and operational ownership before it moves DNS. Start by proving that the target can run the same commit under production-like conditions while the current Vercel deployment remains intact.

Inventory before building

Export a list of variable names by environment without placing secret values in tickets or documents. Identify which values are added by integrations, which NEXT_PUBLIC_ values are frozen into the client bundle, and which server values must be available at build time or request time.

Trace every managed dependency: functions, scheduled work, storage, databases, analytics, email, identity, webhooks, redirects, headers, image handling, cache behavior, and preview workflows. Assign an owner and target for each one.

Test the target as a system

Deploy the production commit to a temporary hostname. Use production-equivalent data carefully, or a representative isolated environment when real data is unsafe. Test user journeys and external callbacks, not only the homepage.

Verify the behavior that differs most outside Vercel: streaming through proxies, persistent and multi-instance caches, image optimization, process shutdown, health checks, logs, scaling limits, and release rollback.

Cut over and observe

Lower the DNS TTL before the change, avoid unrelated releases during the window, and record the source and target states. Switch traffic only after the target passes the written checks. Watch error rate, latency, conversion events, queues, webhooks, and resource saturation.

Keep Vercel available until the rollback window closes. If thresholds are crossed, one named owner should restore the prior traffic path and verify whether writes or external events need reconciliation.

Methodology

How this resource was produced

The migration sequence separates dependency discovery, target validation, traffic cutover, and rollback. It assumes the source deployment remains available until the new production path is proven.

Limitations
  • 01

    This checklist cannot discover undocumented external services, integration-managed secrets, or application-specific data flows.

  • 02

    DNS propagation and third-party callback updates may prevent an instant rollback even when the old deployment remains healthy.

FAQ

Questions about migrate next.js from vercel.

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

Should I delete the Vercel project after cutover?

Not immediately. Keep the known-good source available through the agreed rollback window, then remove or downgrade it only after data, callbacks, and traffic are verified.

Can I copy NEXT_PUBLIC variables at runtime?

Those values are inlined during next build, so the target build must use the intended production values.

Next step

Turn the resource into a deployment decision.

Review the migration with us