Migration
How do you plan a CMS migration to Sanity, from content audit to cutover?
Short answer
A content management system (CMS) migration to Sanity, from content audit to cutover, turns on three decisions: the export route, the content model mapping and a rerunnable import with stable IDs (Sanity Learn; its migration principles, October 2026). A content API (application programming interface) lets the last run read live content, so any freeze stays short (Sanity Learn, October 2026).
- Best export route
- A content API: no content freezeFile or database exports need manual steps on every run, and scraping is the fallback when no export tooling existsSource: Sanity Learn (Planning a re-platforming project)
- Growth document quota
- 25,000 included, 50,000 with the add-onThe Increased quota add-on is $299 a month, as of October 2026. Growth has no document overage; the quota counts across all datasets, so a staging copy counts. Drafts count; assets don'tSources: Sanity (Plans that scale with you); Sanity Docs (Plans and payments, Technical limits)
- Datasets on Free and Growth
- 2, so staging takes the secondEvery dataset copy counts toward the plan's limit; extra datasets on Growth are $999 a month each, as of October 2026Sources: Sanity Docs (Development, staging, and production environments); Sanity (Plans that scale with you)
- Rich text converter
- @portabletext/block-toolsHeadings, paragraphs and lists convert without configuration; images and other objects need custom rules; tables need a declared table type from Studio v6.6.0Sources: Sanity Learn (Migrating to block content); Sanity Docs (Configure the Portable Text Editor)
Deploi’s call
Plan a migration to Sanity around your export route and your content model, not around an importer. Start when you can rerun the import against live content and someone owns the model; until both are true, fix those gaps or move one low-risk section first.
MigrateStart planning a migration to Sanity now when
- Your content management system (CMS) gives you an export route you can rerun, an application programming interface (API) or a repeatable export, so the final import comes from fresh content and the content freeze stays short.
- You have, or can crawl, the full list of live URLs, because the URL map and the content model start from one inventory.
- Someone owns content model decisions and editors can review the Sanity model before any import.
- Your document count, staging copy included, fits the Sanity plan you'll pay for, as of October 2026: Growth includes 25,000 documents across all datasets, or 50,000 with the $299 a month add-on.
StayStay on your current content management system for now when
- Scraping is your only exit and most pages are presentation-built layouts, so every page becomes hand work.
- Nobody can own the content model, so you'd lift the old structure as-is, which Sanity warns recreates the same problems.
- A domain change and a redesign are already booked in the same window, because Google advises one site change at a time.
- Page speed is the only complaint and hosting or caching fixes haven't been tried.
Which export route does your current content management system give you, and how does it shape the plan?
The export route your content management system (CMS) offers is the first fork in a migration plan to Sanity, because it decides how often you can rerun the import and how long editors stop publishing. Sanity's planning lesson names three routes: a content API (application programming interface), file or database exports, and web scraping when there's no export tooling at all (Sanity Learn, Planning a re-platforming project, October 2026).
| Export route | Content freeze at go-live | What you script |
|---|---|---|
| Content API | Sanity's lesson says none: the last run reads live content | Paged reads, rerun until launch |
| File or database export | A fresh export before each run | Parsers for XML, SQL or JSON dumps |
| Web scraping | A fresh crawl before each run | A crawler and extraction rules per template |
Sanity's MCP (Model Context Protocol) server lists guided migration paths from Contentful, WordPress, Strapi and Drupal (Sanity blog, October 2026), and Sanity's August 2026 migration skill is "agent-scaffolded, not fully automated" (Sanity's August 2026 releases). The hub's source playbooks cover the specifics: moving WordPress posts and plugins, mapping Contentful content types, exporting from Drupal, leaving Adobe Experience Manager and leaving Sitecore.
How do your content types map to Sanity documents, objects and references?
Your content types map to Sanity by what each item is, not by the template that displays it. So Sanity's remodeling lesson stores a staff profile as a person document and a store as a location document (Sanity Learn, remodeling lesson, October 2026).
| Source content | Sanity target | Decision it forces |
|---|---|---|
| Template pages | Typed documents, such as person | Which templates are entities |
| Posts and pages | post and page documents | Which fields survive |
| Categories and tags | Taxonomy documents and references | Merge or keep each vocabulary |
| Authors | author documents | Which bylines need a login |
| Media library | Image and file assets | Which files are still used |
| Search metadata plugin fields | An seo object | Override and fallback rules |
| Redirect plugin rows | redirect documents | Which rows still get traffic |
| Locales | Document-level or field-level localization | Publish languages together or apart |
| Form and plugin data | A service or a schema type | Rebuild, replace or retire |
How does rich text from any CMS become Portable Text?
Rich text from any content management system (CMS) becomes Portable Text, Sanity's JSON format for rich text and block content, through a conversion script built on @portabletext/block-tools. The package converts headings, paragraphs and lists without configuration; images and other complex objects need custom rules that parse them out of the HTML (Sanity Learn, Migrating to block content, October 2026).
The conversion cost follows the source. Sanity says the job is "more difficult the more presentation-focused your source content is" (Sanity Learn), so pages built from layout blocks cost more to convert than articles written in a plain editor. Log every HTML element your rules don't handle, because each one is a schema decision (Deploi's judgment).
Tables don't block the move. The Portable Text Editor has built-in table editing from Studio v6.6.0; it is disabled by default and needs a table schema type you declare (Sanity Docs, Configure the Portable Text Editor, October 2026; Sanity's August 2026 releases). A migrated HTML table still needs a conversion rule that fills your table type (Deploi's judgment). Each source playbook covers its own conversion, and how Portable Text stores rich text explains the format.
What content problems should you plan for before writing the migration script?
Plan for content entropy, the inconsistency a content management system (CMS) collects when it lacks validation. Sanity's planning lesson says to expect "broken links, references to media, images, and users that no longer exist, empty paragraphs, lines with whitespace, and mismatched encoding" (Sanity Learn, Planning a re-platforming project, October 2026). Three rules for the migration script follow from Sanity's courses:
- Fail loudly. Sanity suggests you
throwon errors so scripts don't import invalid data, because logging alone may not help (Sanity Learn, General migration principles, October 2026). - Validate in the script. Schema validation rules run only in Sanity Studio, so application programming interface (API) writes and imports aren't checked against them (Sanity Docs, Import data, October 2026). Sanity suggests a runtime validator such as Zod, then
sanity documents validateonce content lands (Sanity Learn, Migrating without downtime). - Leave dead content behind. Sanity's lesson ranks content by its role and its analytics and moves only what still serves (Sanity Learn). A content audit before the move builds that list.
How many Sanity documents will a migration use once staging is counted?
A migration uses the documents in every dataset added together, staging included, because Sanity's document quota applies across all datasets in a project (Sanity pricing; Sanity Docs, Plans and payments, October 2026). Growth includes 25,000 documents and allows no document overage; the $299 a month Increased quota add-on raises the total to 50,000, Growth's ceiling, and past that the path is Enterprise, as of October 2026 (Sanity pricing; Technical limits).
Three rules decide your total:
- Staging doubles the count. Free and Growth include 2 datasets, and every dataset copy counts toward that limit (Sanity Docs, Development, staging, and production environments, October 2026), so a full staging copy takes the second dataset and adds a second set of documents.
- Drafts count. A draft with unpublished changes is a separate document; image and file assets don't count (Sanity Docs, Plans and payments; Technical limits).
- Remodeling raises the count. Splitting template pages into typed documents adds documents (Deploi's judgment), so count after the model review.
What Sanity's Free and Growth plans include and what counts as a Sanity document go further.
What happens to users, roles, editorial workflow and plugins in a move to Sanity?
Each user and plugin in your old content management system (CMS) needs a named home in Sanity, because roles, workflow and plugin features don't arrive with the exported content (Deploi's judgment). Editors become project members with roles, bylines become author documents, approval steps need their own plan, and plugins become schema types, front-end code or a separate service.
- Roles. Free has Administrator and Viewer, Growth has five fixed roles, and custom roles are an Enterprise feature, as of October 2026 (Sanity Docs, Roles and permissions; Sanity pricing, October 2026). Map each old role to its closest Growth role and list the gaps; what each Sanity role can do has the matrix.
- Workflow. Sanity Workflows is in early access with pre-1.0 packages, as of October 2026, so don't count it as a finished replacement for your current moderation steps (Sanity Docs, Workflows; How early access works, October 2026).
- Plugins. Search engine optimization (SEO) fields move to an
seoobject with an override and a fallback (Sanity Learn, SEO schema types and metadata), and redirects become documents (Sanity Docs, Managing redirects with Sanity). Sanity's Webflow course says forms need "a full replacement" (Sanity Learn, Set up forms, redirects, and sitemap, October 2026). - Training. Sanity says training is "absolutely required for content creators" (Sanity Learn), so put editors in the model review.
What is the step-by-step plan for a CMS migration to Sanity, and who owns each step?
A content management system (CMS) migration to Sanity runs in eight steps, and the script reruns from step four to seven. Sanity's course says migration scripts "usually have to be run multiple times", so IDs derived from the source let a rerun update documents, not duplicate them (Sanity Learn, General migration principles, October 2026); sanity datasets import needs --replace for that.
Planning a CMS migration to Sanity
- Inventory and crawl. Count each content type and crawl every live URL. Owner: content and search leads.
- Prove the export route. Pull ten real items through it, the messiest included. Owner: developer.
- Review the model with editors. Agree types, references and what to retire. Owner: content lead.
- Write an idempotent script. Derive each document ID from its source ID and throw on bad data. Owner: developer.
- Import safely. Load staging first unless nothing public reads the dataset yet; safe imports into Sanity covers flags, webhooks and rollback. Owner: developer.
- Verify. Compare counts per type, validate documents and test every old URL against the search and redirect plan. Owner: developer and search lead.
- Cut over. Run the last import from fresh content and switch, following cutover and rollback. Owner: developer.
- Sign off and monitor. Close the migration checklist and watch errors and search traffic. Owner: project owner and search lead.
When should you not start a migration to Sanity yet?
Don't start a migration to Sanity until your plan has room to rehearse the import and your export route has worked on real items, because both gaps surface after the scripting has begun (Deploi's judgment). Booked site changes are the other hold: Google's site move guidance says to plan changes "one after the other, not everything at the same time", naming a content management system (CMS) change among its examples (Google Search Central, Site Moves and Migrations, October 2026). Redesigning and replatforming together weighs that choice.
If only part of the site is ready, start there. Sanity's remodeling lesson suggests low-risk content first, such as terms of service or support pages, then expanding the rollout (Sanity Learn, remodeling lesson, October 2026).
Deploi’s point of view
- Where we disagree
- The common pitch treats a CMS migration as an export and an import: pick a tool, move the content, switch the domain. The work that sets the cost sits elsewhere. The export route decides how often you can rerun, the model mapping decides how much content gets reshaped, and plugins turn into separate builds. A one-to-one copy of pages moves the old CMS's problems onto Sanity, which Sanity's own course warns against.
- What we’ve seen
- Deploi has moved its own Sanity content with the discipline a migration needs. In September 2026 Deploi moved its FAQ content and chatbot settings from a standalone Sanity project into a shared one, with a dry-run cutover script and an import that never overwrote editors' versions. The same month, scripts that change nothing unless told to apply moved 256 live FAQ answers on deploi.ca to shorter URLs, skipping any document edited since the snapshot. Both were changes inside Sanity.
- What we'd tell you to do first
- Before any schema work, get three things: a count of every content type, a crawl of every live URL, and ten real items pulled through your export route, the messiest included. The counts pick the plan, the crawl sizes the redirect work, and the ten items show which export route you actually have.
When this answer changes
- Sanity changes the Growth document quota, the $299 Increased quota add-on or the 50,000 ceiling
- Sanity changes the datasets included on Free and Growth or the $999 extra dataset price
- Sanity rewrites or retires its re-platforming or refactoring courses
- Sanity ships an official importer for a source CMS or changes the MCP server's migration paths
- @portabletext/block-tools changes its default conversions, or Portable Text tables are enabled by default
- Sanity Workflows leaves early access
Follow-up questions
Sources
Every source opened and checked on 25 October 2026.
- Sanity Learn, Planning a re-platforming project
- Sanity Learn, Re-modelling your existing content
- Sanity Learn, Migrating without downtime
- Sanity Learn, General migration principles
- Sanity Learn, Migrating to block content
- Sanity Docs, Import data
- Sanity Docs, Plans and payments
- Sanity, Plans that scale with you
- Sanity Docs, Roles and permissions
- Sanity Docs, Development, staging, and production environments
- Sanity Docs, Technical limits
- Sanity Docs, Configure the Portable Text Editor
- Sanity, What’s new in August: inline tables, functions calling functions, and visual editing without React
- Sanity Docs, Localization
- Sanity Learn, SEO schema types and metadata
- Sanity Docs, Managing redirects with Sanity
- Sanity Learn, Set up forms, redirects, and sitemap
- Sanity, You’ll need a CMS eventually. Let your agent set it up.
- Google Search Central, Site Moves and Migrations
- Sanity Docs, Workflows
- Sanity Docs, How early access works
- Sanity Docs, How to implement multi-tenancy with Sanity