· By John Kavanagh

Changing a CMS Field Whilst Two Next.js Releases are Live

Photograph of scaffolding supporting work on a city building.
Image by Julian Tong, licensed from Unsplash.

The new page looks fine. The old deployment is still serving traffic. Somebody has just deleted the field it needs.

A CMS field rename can look like a small piece of housekeeping, particularly when the editor interface and the latest application agree about the new name. The difficulty is everything which hasn't moved yet: another running instance, a preview deployment, a queued build, or the release you'd like to roll back to.

For a Next.js site, I want the previous renderer in the migration test. Checking only the new one misses the requests still reaching the old release.

My example changes an event's venue string into a linked location with localised names. The link is useful; removing the string too early is the problem.


Keep Both Contracts Available First

The starting model has a title and a localised venue. The old renderer knows nothing about location entries. An expanded model adds an optional location reference and keeps the venue field available with its existing meaning.

That last part matters. A field which still exists but now contains a location ID instead of display text isn't backwards compatible merely because its name survived.

The new renderer first tries the resolved location's name, then falls back to the legacy venue. My fallback policy checks the requested locale and then British English within each source. It does not confuse an unresolved reference with a usable location.

const venue =
  pickLocale(event.location?.name, locale) ||
  pickLocale(event.venue, locale);

if (!venue) {
  throw new Error('No compatible venue');
}

Here, pickLocale returns non‑empty display text according to that explicit locale policy. It isn't a cast which makes an arbitrary CMS response trustworthy. Both readers still reject an event which has no renderable venue.

I covered the wider modelling decisions in my headless CMS content‑model guide. For this change, the extra requirement is that the old meaning remains usable until every eligible reader has stopped depending on it.


Run Two Renderers Against One Changing Source

A Next 14 Pages Router page can fetch its event in getServerSideProps and pass the normalised display value to the component. The versioned Next.js documentation describes that request‑time boundary.

I use it here to make changes visible on the next request. This keeps the experiment about content compatibility rather than about when a cached page happens to regenerate.

My lab runs the old and tolerant readers as separate production applications. They share one local CMS fixture. A small proxy exposes both through the same browser origin, so the test can ask either release to render the same event without rebuilding it.

The checks inspect the visible venue, page title, and meta description. A page which shows the new location in its body but the old value in search metadata has not finished making up its mind.

My production‑request testing article explains why I take the assertion through the built application. A helper returning the right string is useful evidence, but it cannot establish what the page actually sends.


Stop Halfway through the Data

The fixture contains two events. I expand the model, migrate one, and stop. Both renderers must still serve both events: one now has a location reference and one still relies entirely on its venue.

That mixed state is the normal acceptance case, not an embarrassing exception. A migration which only works before its first write and after its last write needs an unusually accommodating production system.

The next pass migrates the remaining event. Another pass makes no changes. The example uses deterministic location IDs and skips already‑linked events; it is deliberately small. It does not pretend that an in‑memory loop solves remote retries, concurrent writes, or uncertain API responses.

Those operational details need their own migration design. Here, the question is narrower: can each eligible application release render the content left behind at every stage?


Decide How Editors Can Change the Value

Keeping two fields briefly means deciding who keeps them consistent.

My fixture's editor operation updates the old value and its linked counterpart together. The test edits the first migrated event before migrating the second, then confirms that both renderers show the revised name.

This is an explicit lab policy. Two remote CMS updates do not become a transaction because the JavaScript calls are adjacent. In a real system, I would choose and document a supported dual‑write workflow, reconciliation process, or bounded editorial freeze, including what happens when only one write succeeds.

A general instruction to editors to "keep both fields right" is not much of a consistency mechanism. It also gives them an unnecessary second job.

Before contraction, the fixture checks every existing localised venue value against its replacement. Deliberately changing only the French location name blocks removal. The English page looking correct doesn't settle the French page's migration.


Preview Gets a Separate Row in the Test

A linked location may exist in preview but be unpublished in the delivery source. My fixture makes that difference explicit.

With a draft location name, the tolerant preview reader shows the draft value. The public reader falls back to the retained venue because that linked entry isn't available there. A genuinely missing link takes the same public fallback path.

This is why I wouldn't use a successful preview screenshot as evidence that published content is complete. I covered the different content sources and access boundary in my Next.js preview guide.

The lab's preview query is only a local fixture selector. It does not implement authenticated CMS preview access and should not be copied into a public application as one.


Make Removal a Separate Decision

Once every event has a usable replacement, the old release still works because its venue remains present. The test deliberately returns to that release after migration and an editor change.

Only then does it exercise contraction. The guard requires the old release to be retired, the agreed rollback window to be closed, and the replacement data to be published and consistent. These are explicit test inputs, not a deployment detector hiding in the migration script.

After removal, the tolerant reader succeeds. Sending the same request to the old reader produces the expected failure. Deleting a linked location then makes the new reader fail too, because the legacy fallback has gone.

My CMS release‑compatibility lab keeps those failures alongside the passing cases. They mark the point at which the rollback promise changes.

Rolling code back does not restore deleted content. Keep the old field whilst that promise still matters, and make its eventual removal a reviewed release step with evidence from every content source the application serves.

Postscript

November 2026: I've added a runnable companion using Next.js 16.4.6 and React 19.3.1. It retains the Pages Router request boundary and tests two production builds against a local fixture; its lockfile is a current baseline, not a recovered June 2024 environment. For a Contentful implementation, the scripted‑migration guidance and content‑type deployment workflow cover the service‑specific operations. My lab does not establish that changing an environment alias makes content and application releases atomic.

Downloadable Resource

  • Next.js CMS Schema Release Lab

    Run old and tolerant Next.js releases against a changing local CMS. Check partial migration, editor changes, preview, locales, and unsafe rollback.

    Download ZIP

Planning a platform change?

I help teams make difficult platform work clearer, from architecture decisions and migrations to launch recovery, performance, and search visibility.