Get concise advice on choosing the right CMS, understanding migration costs, and avoiding expensive implementation mistakes before they become roadmap problems.
By Matija, the developer behind Build with Matija. In the second week of November 2026 I was preparing two migrations onto Payload CMS at once: a large bilingual WordPress site with about 8,600 legacy URLs, and a small farm shop moving from its own Payload site into a multi-tenant storefront. This article is written from the tools I built for both and from their first real runs against staging. Versions: Payload 3, Next.js 15 and 16 (App Router), PostgreSQL 17, Node 24, TypeScript scripts run with tsx. Last updated 2026-11-12.
A migration is ready for cutover when a script can show that every legacy URL and every legacy record has a known fate on the new site, and that the evidence was produced against the exact build you are about to ship. "We spot-checked the important pages" does not meet that bar. On the large site I wrote one tool per launch question (URLs, content, crawl health, exposure, visual parity), had each one write a small verdict.json, and added an aggregator that turns those verdicts into GO, NO-GO or STALE per launch gate. Its first run said NO-GO. That was the useful result: it named 53 legacy URLs with no working destination, among them the single most visited broken URL on the old site, and it refused to count any audit that had run on an earlier deploy.
Why counts and spot checks are not enough
My CMS migration checklist ends Phase 5 with "verify record counts and spot-check content in staging", and the WordPress to Payload migration guide says to run the full URL list through a redirect checker before go-live. Both are right, and both leave the hard part open: what counts as "verified", who decides an exception is fine, and how you know the check still holds after the last deploy.
On a site with a few thousand pages, spot checks find the problems you already expected. The issues that hurt after launch sit in the long tail: an old hub page that redirects to an error, PDFs that were linked from newsletters for years, a localized path that changed so a thousand internal links now pass through a redirect. Each of those surfaced in the first runs below, and none of them was on anyone's spot-check list.
Rule 1: every legacy URL gets exactly one disposition
The URL tool joins three inputs that were captured beforehand: the redirect map (what we intend), a crawl of the legacy site (what it serves today) and Search Console clicks plus analytics sessions per URL (what people actually use). The legacy site is never fetched during the check. Then it asks the staging site for each URL and sorts the real answer into one of five buckets:
The gate is simple: unmapped plus broken must be zero, minus entries in an accepted.json file, and every accepted entry needs a written reason that cites a decision. A 410 is allowed only as a reviewed last resort, so the tool flags any 410 whose legacy URL is still served or still gets traffic.
Keys are normalized the same way the redirect middleware normalizes them (lower case, decoded, no trailing slash, tracking parameters dropped), otherwise the tool and the site disagree about which URL is which.
The first run against staging covered 8,593 legacy URLs: 2,678 recreated, 5,422 redirected, 440 gone, 30 unmapped and 23 broken. The gate failed with 53. Sorting both failure lists by traffic made them easy to act on:
The top broken URL was the old resources hub, with 1,314 clicks and sessions in the capture window. The map said keep, staging answered with a redirect to a 503.
Most unmapped URLs were noise: bots asking for /products.json, /wp-login.php, old pages and URLs with pasted text glued onto them. Those go into with a reason.
If your redirects live in Payload, the redirects plugin article covers the uniqueness and locale problems that tend to show up here as "broken".
Rule 2: prove nothing was lost, per type and per locale
The content tool compares the WordPress export with the Payload database, per content type and per locale: published in WordPress, excluded by rule, skipped by the importer, expected, present and published in Payload, matched, missing, and extra. Items are joined on the WordPress id the importer stores, with slug plus locale as the fallback.
Three choices made the result trustworthy:
The first run found all 593 expected items present and published, 40 excluded by rule, and all 905 media references resolving. It still failed, on 17 items with a featured image in WordPress and none in Payload. All 17 were items added after the media export had been taken: the content export was a week newer than the media export. The gap was in the inputs, and only a tool that compares item by item would have shown it.
The small version: schema-driven parity for a Payload to Payload move
The farm shop was a much smaller job: 138 products, a few recipes, customers and orders, three locales, moving from a single-tenant Payload site into one tenant of a multi-tenant storefront. A launch dashboard would have been overkill. Two artifacts were enough.
The first is a parity checker that lets the schema drive the comparison, so I did not have to write a rule per collection:
every legacy table with rows and no _parent_id is a root collection;
child tables (arrays, blocks, _locales) are compared as ordered lists under their parent, _locales rows per locale;
_rels rows are compared as multisets of path and target;
Both databases are read inside read-only transactions. The summary on stdout contains no values, because the tables include customer data; the optional details file masks personal-data tables and is written with mode 600. The result went into the migration docs as "100% of legacy records present on staging and production".
The second is a redirect map with a class per row. Most rows are English and Russian product URLs whose slugs moved to the shop's own language; the map tags them SOFT_404 and sends each to its new product with a 301. One redirect needed a code change: a rewrite in next.config does not reach tenant hosts, so the tenant proxy now sends the old English "about us" path to the new page with a 308. The multi-tenant SEO guide covers the rest of the per-tenant SEO setup.
So the thesis scales down. On a small site the proof is two scripts and a CSV. On a large one it needs gates, owners and freshness, which is the rest of this article.
Rule 3: crawl the new site the way a search engine will
The URL tool asks about old URLs. A crawl of the new site asks whether the site is internally consistent. On staging it found 211 sitemap problems (venue pages answering 307, course pages answering 404, 113 indexable pages missing from the sitemap), 1,002 internal links that went through a redirect because the French product path had moved from /products/ to /produits/, 19 internal links to 404s, and 28 hreflang targets that did not answer 200. Canonicals were clean and no page linked back to the legacy host.
The 1,002 redirected links are the kind of finding that never shows up as a visible bug. Every link works for a visitor. Search engines spend crawl budget on the extra hop, and the hreflang and canonical setup only holds if the alternates you declare answer 200 directly. If you do not want to build your own crawler, the FreeCrawl guide gets you most of these numbers.
Rule 4: scan what the new site exposes before anyone else does
A new stack brings new surfaces: an admin panel, a REST API per collection, preview and developer tools. The exposure scan checks security headers, which routes answer, which collections can be read without a session, and whether the JavaScript bundles contain anything that looks like a secret. Staging had no high findings and 11 medium ones: the Content Security Policy was still report-only, there was no clickjacking protection, three developer tools answered on production-like staging, and one collection allowed anonymous reads. That collection was empty, so nothing had leaked yet. The report put it plainly: it would leak as soon as data existed. Today that is an access-control change; after launch it would be an incident.
Rule 5: evidence expires when the code changes
Every tool writes the same small file next to its report:
json
The readiness aggregator maps these verdicts to 13 launch gates from the project's ledgers (redirects green, every legacy URL accounted for, nothing lost, sitemap clean, hreflang valid, no runtime dependency on WordPress, admin and API not exposed, Core Web Vitals no worse than before, and so on). Each gate has an owner. Some owners are me and some are the coding agents that build and run the tools, which is how I keep track of who has to act. The rules fit in four lines:
The deployed commit comes from the staging response itself where possible, so the check compares against the build that is actually running. Two more rules came from thinking about how the gates could be gamed by accident. The visual parity tool, which ranks legacy-versus-new screenshots of the top pages by traffic, always reports warn: pixel differences are a worklist, and the gate stays open until a human review is imported. And the summary ends with a reminder that re-running a tool whose last run failed only refreshes the failure.
The first aggregate run on 10 November: GO 0, NO-GO 2, STALE 11 of 13. Two gates had no run at all against the new staging environment, and the other eleven had evidence from a commit that was replaced on staging minutes after the last audit finished. Without the freshness rule, that evening's audits would have looked like a nearly finished launch.
What this costs, and when it is worth it
For a decision-maker, the question is whether this is gold-plating. My answer depends on the size of the site and on what traffic is worth.
The farm shop needed a parity script, a redirect map and a manual check of a handful of pages.
The large site needed the full set because it has thousands of URLs with real search traffic, two locales, email campaigns and old PDFs that still send visitors to legacy paths, and several people and agents changing staging every day.
The tools are cheap compared with the alternative. A redirect gap on a high-traffic URL costs rankings for weeks, and an anonymous API read costs trust. A GO/NO-GO page also changes the launch conversation with the client: the discussion moves from "does it feel ready" to "these two gates are open, here is why, here is who owns them". That is the part I would keep even on a mid-sized project.
FAQ
Do I need all five tools for a small site?
No. Start with URL accounting and content parity. Add the crawl when the site has more than a few hundred pages or more than one locale, and the exposure scan whenever the new stack has an admin or API that the old one did not.
Why not accept the 404s for bot traffic silently?
Because the next person cannot tell a reviewed decision from an oversight. An accepted.json entry with a reason costs one line and keeps the gate meaningful.
Why three days for freshness?
The commit check does most of the work; the age limit catches environments where content changes without a deploy.
Can this run in CI?
The tools exit non-zero on a failed gate, so yes, against a staging deploy. I run them by hand and from agent sessions before each release candidate.
anything else: redirect to a non-200, a 404, a 5xx, no answer
// File: scripts/url-accounting/classify.ts (simplified sketch of the pattern)
type
MapRow
action
'keep'
'redirect'
'gone'
target
string
type
Answer
finalStatus
number
null
hops
number
// after following up to 3 same-host redirects
export
type
Disposition
'recreated'
'redirected'
'gone'
'unmapped'
'broken'
export
function
classify
row: MapRow | undefined, answer: Answer
Disposition
if
return
finalStatus
404
'unmapped'
'broken'
if
action
'keep'
hops
0
finalStatus
200
return
'recreated'
if
action
'redirect'
hops
0
finalStatus
200
return
'redirected'
if
action
'gone'
finalStatus
410
return
'gone'
return
'broken'
.htm
accepted.json
A few unmapped URLs were real: two PDF guides under an old /images/docs/ path that still got visits. They needed a redirect to the rehosted file.
267 of the 440 planned 410s were flagged for review because the legacy URL was still live or still had traffic.
Exclusions are rules with reasons. Drafts stay drafts. Content the client decided not to migrate is listed by id, and those ids must not exist in Payload at all, so a forgotten exclusion shows up as an error. Form entries are out of scope and the report says so. Every rule cites the decision it came from, which is what lets read the report without asking me what a number means. The content triage article describes how those decisions get made; this tool is where they become checkable.
The database is read only, three ways. Only a single SELECT or WITH statement passes the query guard, the session runs inside BEGIN READ ONLY, and the connection sets default_transaction_read_only=on. A parity tool that can write is one bug away from "fixing" the evidence.
Media is checked by reference. For every document, every media reference must point at an existing media document with a filename and a non-zero size, and none may still point at a WordPress URL.
foreign keys are mapped to the target's natural key on both sides (slug, email, order number, filename), so different ids do not count as differences.
{
"tool"
:
"url-accounting"
,
"version"
:
1
,
"target"
:
"staging"
,
"sha"
:
"92ef6fb9"
,
"finishedAt"
:
"2026-11-10T21:07:43.908Z"
,
"status"
:
"fail"
,
"summary"
:
"30 unmapped, 23 broken (53 failing the gate)"
,
"gates"
:
[
"P6.4"
]
}
// File: scripts/launch/readiness/freshness.ts (simplified sketch of the rules)