Migrating Content Models Without Breaking the Frontend

This guide, part of Content Modeling Best Practices, describes how to change a content model that is already in production, renaming fields, splitting types, converting embedded objects to references, without a moment where the deployed frontend and the stored content disagree.

A content model change has two halves that deploy separately: the CMS schema and content on one side, the frontend code on the other. There is always a window where one has changed and the other has not, and editors keep publishing throughout. The safe pattern is the same one used for database migrations: expand the model so both shapes are valid, move the data, switch the frontend, then contract the model. Each step is small, reversible and deployable on its own.

The Problem

A team renamed the summary field on articles to excerpt and changed it from plain text to rich text, in one release. The CMS change went live first, as part of a scheduled model update, and the frontend deploy was delayed by an unrelated failing test. For two hours, the live site showed empty excerpts on every article listing, because the deployed code read summary. Worse, editors who published articles during that window wrote into excerpt, and when the team rolled the model back, those edits were lost.

How Safe Migrations Work

Every model change can be expressed as a sequence of steps that keep both halves compatible.

Expand. Add the new field or type alongside the old one. Nothing reads it yet, so nothing breaks. Deploy the model change through a migration script, first to a branch environment and then to production.

Dual-read. Deploy frontend code that reads the new field when present and falls back to the old one. The site renders every entry correctly whether it has been migrated or not.

Migrate. Run a script that fills the new field from the old one for every entry, in batches, preserving publish state: published entries are republished, drafts stay drafts. Mark the old field read-only or hide it in the editor so new edits go to the new field.

Switch and contract. Once all entries are migrated and verified, deploy frontend code that reads only the new field, then remove the old field from the model. If anything goes wrong before the contract step, rolling back is trivial because the old data is still there.

Implementation

Model and content changes live in versioned migration scripts, run by CI against a branch environment created from production. The example uses Contentful’s migration tooling; Sanity, Strapi and Hygraph offer equivalent schema and content APIs.

// migrations/2026-09-12-excerpt.cjs: expand step (run with `contentful space migration`)
module.exports = function (migration) {
  const article = migration.editContentType("article");
  article.createField("excerpt").name("Excerpt").type("RichText").localized(true);
  article.changeFieldControl("summary", "builtin", "singleLine", {
    helpText: "Deprecated: use Excerpt. This field will be removed on 2026-09-24.",
  });
  article.moveField("excerpt").afterField("title");

  // Content step: copy summary into excerpt as a single rich text paragraph.
  migration.transformEntries({
    contentType: "article",
    from: ["summary"],
    to: ["excerpt"],
    shouldPublish: "preserve",
    transformEntryForLocale(fields, locale) {
      const text = fields.summary?.[locale];
      if (!text) return;
      return {
        excerpt: {
          nodeType: "document",
          data: {},
          content: [{ nodeType: "paragraph", data: {}, content: [{ nodeType: "text", value: text, marks: [], data: {} }] }],
        },
      };
    },
  });
};

The frontend reads both shapes during the transition, in one mapping function, so no component changes twice.

// lib/cms/article-mapper.ts
import type { Document } from "@contentful/rich-text-types";

interface RawArticle { fields: { title: string; summary?: string; excerpt?: Document } }

export function toExcerpt(raw: RawArticle): Document | null {
  if (raw.fields.excerpt) return raw.fields.excerpt;
  if (raw.fields.summary) {
    // Transitional: remove after the contract step on 2026-09-24.
    return {
      nodeType: "document" as Document["nodeType"],
      data: {},
      content: [{ nodeType: "paragraph", data: {}, content: [{ nodeType: "text", value: raw.fields.summary, marks: [], data: {} }] }],
    } as Document;
  }
  return null;
}

Testing the migration before production

Create a branch environment from production, run the migration there, point a preview deployment of the dual-read frontend at it, and compare pages. A visual diff of the most visited pages between production and the migrated branch catches mistakes in the transform function. With environment aliases, the whole migrated environment can even become production by switching the alias, which makes the cutover atomic, as long as edits made in the old environment during the migration are replayed or frozen.

Configuration Reference

Gotchas & Edge Cases

• Publishing during migration. Editors publishing between the migrate and freeze steps can write to the old field after it was copied. Freeze first, or run the content step twice, the second time for recently updated entries only.
• Losing publish state. A script that publishes every migrated entry also publishes drafts and pending changes. Preserve state: republish only entries that were published and unchanged.
• Webhook storms. Migrating ten thousand entries fires ten thousand publish webhooks. Pause webhooks or let the debouncing layer collapse them, and run a single full revalidation afterwards.
• Forgetting the contract step. Dual-read code and deprecated fields accumulate. Put the contract date in the help text and the code comment, and track it as a ticket.

Worked Example

After the lost-edits incident, the team adopted the four-step pattern with scripts in the repository and a checklist in the pull request template. The next change, converting embedded author objects to references, ran over nine days: expand on Monday, dual-read deployed the same day, migration in a branch environment on Tuesday with visual diffs of 200 pages, production migration on Wednesday with webhooks paused, the switch on Thursday of the following week and the contract step two days later. Editors kept publishing throughout, and no page rendered an empty byline at any point.

Keeping migrations in the repository

The most durable improvement was not any single script but the habit of keeping every model change in the frontend repository as a numbered migration, next to the code that depends on it. A pull request that changes a content type now shows the migration, the dual-read mapping and the tests together, and reviewers can see whether the contract step has been scheduled. CI runs pending migrations against a fresh branch environment on every pull request that touches the migrations folder, so a script that fails on real data fails before review, not during the production run. The migration history also answers the question that used to take hours of archaeology: when and why a field changed shape.

Treat the production run as a deploy. Announce it to editors with the time window and what will change in their interface, run it from CI rather than a laptop, and record which migration ran against which environment. When a migration environment is later promoted by switching an alias, record that too, since it changes what production serves without any code deploy.

Rollout Checklist

• Write every model change as a versioned migration script, reviewed like code.
• Expand the model before changing the frontend; never rename in place.
• Deploy dual-read code before migrating content.
• Migrate in a branch environment first and compare rendered pages.
• Preserve publish state and manage webhook volume during content migration.
• Freeze the old field, switch the frontend, then contract after verification.

Frequently Asked Questions

Related

• Content Modeling Best Practices
• Content Modeling for Scalable Frontend Apps
• References vs Embedded Objects in Headless Content Models