Introducing SanityMigrations.com: Migration Guides and Best Practices

Every Sanity project I take on eventually hits the same wall: the content model that felt right in month one needs to evolve by month six. Fields get renamed. References get restructured. A single page type splits into landingPage and article. The content already in production has to come along for the ride — and that's where most teams stall.

So I built SanityMigrations.com — a free, continuously updated library of migration guides and best practices covering every kind of move I've run into as an Official Sanity Partner Studio.

Why I Built It

The Sanity docs are excellent at explaining how the migration API works. What they don't do — and can't really do — is walk you through the messy, specific situations teams actually face:

• You have 40,000 documents in production and need to rename a field without downtime
• You're moving off WordPress and have 15 years of posts with inconsistent metadata
• You inherited a schema with three overlapping content types and need to consolidate
• Your migration worked in dev but the dataset export is too big to run locally
• You need to roll back a migration that only half-completed

Those are the guides I've been writing internally for years. SanityMigrations.com is me putting them in public.

What the Site Covers

1. Schema Migrations

The bread and butter: renaming fields, changing field types, splitting and merging document types, moving from flat fields to portable text, introducing references where strings used to live. Every guide includes the dry-run-first workflow and a rollback plan.

2. CMS-to-Sanity Migrations

Step-by-step playbooks for moving onto Sanity from other platforms:

• WordPress → Sanity — handling the REST API, ACF fields, media library, and redirects
• General CMS-to-Sanity patterns — mapping content types, migrating assets, preserving references, and the traps that show up regardless of source CMS

I'm actively adding more platform-specific guides as I work through them on real projects — Contentful, Prismic, Strapi, Drupal, and custom SQL databases are on the roadmap.

3. Content Restructuring

Patterns for evolving a content model in place: promoting embedded objects into standalone documents, flattening over-normalized references, introducing i18n to a single-locale dataset, and splitting a monolithic dataset into staging / production environments.

4. Asset and Image Migrations

Moving images into Sanity's asset pipeline without breaking hotlinks, rehosting from S3 or Cloudinary, de-duplicating assets, and dealing with EXIF and metadata preservation.

5. GROQ and Query Migrations

When the schema changes, every query that touched it has to change too. The site includes patterns for auditing query surface area, writing queries that work across schema versions, and safely retiring deprecated fields.

The Best Practices I Actually Follow

A few principles show up in every guide on the site because they've saved me on every client project:

Always dry-run first. Sanity's migration API supports it — use it. Every guide starts with the read-only version before touching production.

Migrate drafts separately. Published and draft versions of the same document have different IDs. Forgetting that is the single most common migration bug I see.

Keep migrations idempotent. If a run fails halfway, you should be able to run it again without creating duplicates or corrupting records. Every script on the site is written this way.

Version-control the migration itself. The migration file is production-critical code. It lives in the repo, gets reviewed, and runs through CI like anything else.

Have a rollback plan before you start. For anything non-trivial, export the dataset first. sanity dataset export is a 30-second insurance policy.

Who It's For

• Developers working in Sanity who want a second pair of eyes on their migration plan
• Agencies onboarding a client off a legacy CMS
• Content teams trying to understand what's possible and what the trade-offs look like
• Anyone evaluating Sanity who wants to know what evolving a schema actually looks like over a project's lifetime

What's Next

The site is live with the core guides and I'm adding more every week based on what comes up in my own client work and what the community asks for. If there's a migration you're stuck on, let me know — if I haven't written it up yet, I probably will.

Visit the site: sanitymigrations.com

---

Zephyr Pixels is an Official Sanity Partner Studio based in Missoula, Montana. I help teams migrate to Sanity, evolve existing Sanity projects, and build headless solutions that hold up over time. If you have a migration coming up, let's talk.