How we migrated our open source Next.js project to a new domain in 3 hours

We migrated an open source Next.js project to a new domain in a single afternoon without losing traffic. Here's the playbook — written down mostly so I don't have to re-derive it next time.

The three hours

1. Hour 1 — DNS and Vercel

   • Add the new domain in Vercel.
   • Point DNS (A/CNAME) and wait for the SSL cert. This is the part you can't rush.
   • Keep the old domain live — do not remove it yet.

2. Hour 2 — 301s and canonical URLs

   • Add 301 redirects from old domain to new domain in next.config.js (or at the edge).
   • Update every canonical URL, OG image URL, and metadataBase in the app.
   • Rebuild. Deploy. Smoke test the important pages.

3. Hour 3 — The long-tail stuff

   • Update Google Search Console (add new property, submit change-of-address).
   • Update the sitemap URL.
   • Update every hardcoded link: README, social profiles, docs, Vercel env vars, internal Slack, Stripe, Posthog, Sentry.
   • Grep the repo for the old domain one more time. There's always one.

Things we got wrong

• Forgot to update NEXT_PUBLIC_SITE_URL in a preview environment. OG images broke for a day.
• Underestimated how many third-party services hardcoded the old URL. Plan for at least one "oh no, that too" moment.

Three hours is the happy path. Budget half a day and you'll be fine.