@domain-migration

Plan and validate an SEO site move with a URL inventory, redirect map, canonical cutover and backlink-update drafts.

Domain Migration

When to Use

Use when changing a site's domain, consolidating slugs or moving a subdomain into a folder. Produce a URL inventory, permanent redirect map, cutover changes, verification results and optional outreach drafts. The examples use illustrative hosts.

Work on a branch or staging environment. Record the starting analytics and crawl state, affected hosts, activation order and rollback procedure. Require explicit authority before changing DNS, deploying to production, submitting Change of Address or sending mail.

Decision tree: which migration is this

Migration type
├── Full domain change (billbox.io → invoicekit.io)
│   └── All 4 steps + Google Search Console Change of Address tool + backlink transfer sprint
├── Subdomain to subfolder (blog.deployfast.dev → deployfast.dev/blog)
│   └── Steps 1-3. Backlink sprint only for the top 10 referring pages to the subdomain.
├── Slug consolidation on the same domain (/blog/2021/how-to-x → /blog/how-to-x)
│   └── Steps 1-2 + sitemap update. No Change of Address.
└── Merging 2 sites into 1
    └── All 4 steps for the retired site. Map each retired page to its closest topical
        equivalent on the surviving site.

Step 1: Full URL inventory

Build the union of every source below. Each catches URLs the others miss.

  1. Old sitemap.xml (and nested sitemaps): the URLs the site currently advertises.
  2. Repo route tree: every static route plus every slug generated by dynamic routes (content/**, data files, CMS export).
  3. Google Search Console: Pages report, last 16 months, every URL with at least 1 click or 10 impressions.
  4. Ahrefs Best by links (or the backlink tool the user has): every old URL with at least 1 referring domain. This is the list that saves retired posts with strong backlinks.
  5. Analytics landing pages: every landing page with at least 1 session in the last 12 months.

Normalize before deduping: lowercase host, strip query strings and fragments, and pick one trailing-slash form. Write the result to seo/url-inventory.csv with columns old_url,source,clicks_16mo,referring_domains.

Step 2: Deterministic 1-to-1 redirect map

Assign every inventory row a destination:

Old URL
├── Same content, same path on the new domain
│   └── Map the exact path
├── Same content, new slug
│   └── Explicit 1-to-1 entry
├── Content merged into another page
│   └── Explicit entry to the page that absorbed it
├── Content deleted, has referring domains or clicks
│   ├── A page on the same topic exists → explicit entry to that page
│   └── No topical equivalent → restore the page on the new domain, then map it 1-to-1
└── Content deleted, 0 referring domains, 0 clicks
    └── Let it return 410. Never point it at the homepage.

Then collapse chains: if the site already has redirects (/old-slug → /new-slug), resolve every entry to its final destination so each old URL reaches its target in exactly 1 hop.

Write seo/redirect-map.csv with header old_url,new_url. Every new_url must return 200 on the new domain before cutover.

Ship the config for the user's host

Next.js (next.config.mjs on whichever deployment answers the old host). permanent: true returns 308, which Google treats the same as 301.

import { readFileSync } from 'node:fs'

const explicit = readFileSync('./seo/redirect-map.csv', 'utf8')
  .trim().split('\n').slice(1)
  .map((line) => line.split(','))
  .map(([oldUrl, newUrl]) => ({ from: new URL(oldUrl).pathname, to: newUrl }))

export default {
  async redirects() {
    return [
      // Explicit 1-to-1 entries first: Next.js uses the first matching rule.
      ...explicit.map(({ from, to }) => ({
        source: from,
        has: [{ type: 'host', value: '(www\\.)?billbox\\.io' }],
        destination: to,
        permanent: true,
      })),
    ]
  },
}

Escape (, ), :, *, and ? in old paths before using them as source; Next.js parses those characters as pattern syntax.

Cloudflare Bulk Redirects (CSV upload to a Bulk Redirect List, then enable a Bulk Redirect Rule for it):

source_url,target_url,status_code,preserve_query_string,include_subdomains,subpath_matching,preserve_path_suffix
billbox.io/blog/2021/send-invoices-faster,https://invoicekit.io/blog/send-invoices-faster,301,true,false,false,false
billbox.io/,https://invoicekit.io/,301,true,false,false,false

The last row matches the homepage only. Scope each rule to approved subdomains.

Nginx:

map $uri $redirect_target {
  default "";
  include /etc/nginx/billbox-redirects.conf;  # lines like: /blog/2021/send-invoices-faster https://invoicekit.io/blog/send-invoices-faster;
}

server {
  listen 80;
  listen 443 ssl;
  server_name billbox.io www.billbox.io;
  # ssl_certificate lines stay: the old domain must keep valid HTTPS to serve its redirects.

  if ($redirect_target) { return 301 $redirect_target$is_args$args; }
  return 404;
}

Both listeners serve the same explicit map. Configure reviewed 410 responses for intentionally removed URLs before the 404 fallback.

Verify the redirect map

Run the bundled verifier with Bash and curl against a reviewed map:

bash scripts/verify-redirects.sh seo/redirect-map.csv

Each row must contain exactly two unquoted HTTP(S) URLs with no commas, credentials, whitespace or fragments. List the HTTP variants explicitly when they should also redirect in one hop. The verifier makes bounded GET requests to the listed old and new URLs without following any redirects. It checks that the old URL returns 301 or 308 with a redirect URL equal to the destination and that the destination answers 200 directly. Check host-imposed HTTP-to-HTTPS upgrades separately if the edge prevents one-hop redirects.

Run against an authorized staging deployment before cutover and against authorized live hosts afterward. Verify coverage against the inventory, including intentional removals, separate from this positive redirect-map check.

Step 3: Canonical, sitemap, schema, and hreflang cutover

Pre-launch blockers

Inspect production-bound robots rules, page-level robots metadata and X-Robots-Tag headers on affected templates. Preserve staging protections and ensure intended production pages remain indexable.

Edits in the repo

  1. Base URL: update metadataBase (Next.js), site (Astro), baseURL (Hugo), or the canonical helper so every canonical, OG URL, and sitemap entry uses the new origin. grep -rn "billbox.io" . must return only the redirect config, the alternateName, and the /about history line.

  2. Sitemap: the new domain's sitemap.xml lists only new URLs. Keep the old domain's sitemap reachable at its old URL, listing the old URLs, for 60 days. Googlebot re-fetches those URLs, hits the 301s, and processes the move faster than waiting for natural recrawl.

  3. hreflang: every alternate points to new-domain URLs, and each locale page still links back reciprocally.

  4. Organization schema:

    {
      "@context": "https://schema.org",
      "@type": "Organization",
      "name": "invoicekit.io",
      "alternateName": ["BillBox", "billbox.io"],
      "url": "https://invoicekit.io",
      "sameAs": ["https://x.com/invoicekit", "https://www.linkedin.com/company/invoicekit"]
    }
    
  5. /about history line: invoicekit.io (formerly BillBox) has helped freelancers send invoices since 2021. Years of reviews, forum posts, and articles name BillBox. This sentence plus alternateName lets LLMs and Google connect those mentions to the new brand instead of treating BillBox as a dead product.

  6. Google Search Console: verify both properties, then plan the authorized Change of Address submission from the old property (full domain changes only).

  7. Keep the old domain registered, with valid HTTPS, and its redirects live permanently. Backlinks to old URLs keep sending equity only while the 301 exists.

A 301 passes equity, but a direct link to the new URL is stronger and teaches every crawler, including AI crawlers, the new brand name in context.

  1. Export backlinks to the old domain. Filter: dofollow, 1 link per referring domain, referring domain rating >= 20, referring page has organic traffic > 0.
  2. Sort by referring domain rating, then referring page traffic. Keep the top 30-50.
  3. For each, record: referring page URL, current anchor text, the old URL it points to, the mapped new URL, and a contact (author byline, site contact page, or author's public profile).
  4. Write seo/backlink-transfer-emails.md, one draft per row. Rotate across the 3 variants below and personalize line 1 with something specific from their page. Draft only for relevant contacts with published business channels.

Email rules

  • Under 90 words.
  • Name the exact page, the exact old link, and the exact replacement. Make the edit a 30-second job.
  • 1 ask per email. No link-swap offers, no guest-post pitch.

Variant A

Subject: Quick link update on your "[article title]" post

Hi [Name],

Your post on [topic] links to BillBox (billbox.io/[path]). We rebranded to invoicekit.io, and that page now lives at:

invoicekit.io/[new-path]

The old link still redirects, so nothing is broken. If you have a minute to swap the text to "invoicekit.io" and the URL to the new one, readers land on the right page directly.

Thanks for including us in the first place.
[Sender]

Variant B

Subject: BillBox is now invoicekit.io

Hi [Name], [one specific line about their article].

You mention BillBox in the [section name] section. Same product, new name: invoicekit.io. Updated link: invoicekit.io/[new-path]

Would you update it when you next edit the post?

[Sender]

Variant C

Subject: Small fix for [site name]

Hey [Name],

Heads up: [article title] links to billbox.io/[path]. We renamed the product to invoicekit.io last month. Replacing "BillBox (billbox.io)" with "invoicekit.io (invoicekit.io/[new-path])" keeps the reference accurate for your readers.

Appreciate it either way.
[Sender]

Post-launch monitoring

  • Day 1: verify-redirects.sh prints 0 failed on production. GSC shows no spike in "Blocked by robots.txt" or "Excluded by noindex".
  • Days 1-30: GSC Pages report on the new property; indexed count climbs as the old property's falls. Investigate a persistently flat index count alongside crawl and indexing evidence.

Output

Every run ends with:

  1. seo/url-inventory.csv and seo/redirect-map.csv.
  2. The redirect config for the user's host (Next.js redirects(), Cloudflare Bulk Redirects CSV, or Nginx map), committed to the working tree.
  3. scripts/verify-redirects.sh, with its output pasted in chat showing 0 failed (or the failing rows fixed).
  4. Base URL, sitemap, hreflang, Organization schema, and /about edits.
  5. seo/backlink-transfer-emails.md with 30-50 personalized drafts. Never send them.

Do not

  • Redirect inner pages to the homepage
  • Ship any redirect that takes more than 1 hop
  • Block the old domain in robots.txt after cutover
  • Let the old domain's SSL certificate or registration lapse
  • Remove redirects after the traffic recovers
  • Send outreach emails on the user's behalf

Example

Moving https://old.example/docs/setup to https://new.example/guide/setup produces one explicit redirect row. Expect a permanent redirect directly to the new URL, a 200 there, a self-canonical on the new page and internal links updated to the new URL. Keep unmatched URLs in the inventory with a disposition.

Limitations

Redirect checks cover only listed URL pairs. Verify query-dependent routes, canonical and indexing state, edge behavior and route completeness separately. Compare traffic over equivalent periods. A migration can change rankings despite a correct cutover.

Adapted from Ilias Ism’s upstream skill.