Migrate from Sanity to Payload

The freeze-and-load approach stops editing in Sanity for a defined window, takes a full dataset export, loads it into Payload, verifies the result and then opens Payload for editors. It is the simplest model to reason about because the export is a single consistent snapshot, and no change has to be merged after the fact. The cost is editor downtime, which grows with the amount of work that must be verified before the switch. Because the export tarball carries document history along with the documents, the load step must decide what to do with drafts and published versions in Payload's versions and drafts model before anyone edits.

• Editor instructions: Editors publish or discard pending drafts before the freeze, and they stop creating content in Studio once the window opens.
• Export point: Run the sanity dataset export command after the freeze begins so the snapshot contains no late edits.
• Draft handling: Load published documents as the live version and load unpublished drafts as Payload drafts, then confirm each one in the admin panel.
• Asset check: Compare the asset files in the tarball against the documents that reference them, since the export skips assets that return 401, 403 or 404 responses.
• Rollback path: Keep Sanity read-only until the Payload site has passed content review.

Confirm with your editorial leads how long the freeze can run before publishing schedules are affected, and confirm the rollback steps with the team that owns the Sanity dataset.

The delta-sync approach keeps Sanity open for editing while you load a baseline export into Payload, then replays only the documents changed after the export point. Editors keep working with little interruption, and the window for disruption is reduced to the final cutover. The trade-off is engineering work: the team must identify changed documents reliably, map each change through the same schema translation used for the baseline, and handle deletions and conflicting edits. Drafts need extra attention because a document can be edited in Sanity during the sync while a Payload draft already exists for it.

• Change detection: Record the export timestamp and select documents with later revisions for the replay, then test that deletions are captured separately.
• Conflict rule: Decide in advance whether Sanity or Payload wins when the same document changed on both sides, and document that rule for editors.
• Draft reconciliation: Replay draft changes into Payload drafts rather than published versions, so approvals still happen in the Payload workflow.
• Repeat runs: Run the delta several times before the final cutover, and check that each run is idempotent.
• Cutover signal: Announce a short final freeze, run the last delta, and switch the public site once counts and sample checks match.

Confirm with your Sanity administrator how revision data is exposed in the export so the delta logic matches what the dataset actually records.

The content-by-content approach moves one content group at a time, such as a section of the site or a single document type, and leaves the rest in Sanity until its turn. It suits smaller sites or sites with clearly separate content areas, and it lets the team learn the schema mapping on low-risk content first. Each group runs its own cutover, so editors work in two systems for a period. That split needs clear routing: the public site must know which source serves which page, and cross-references between groups must resolve correctly on both sides.

• Group selection: Start with content that has few references to other document types and a small editor audience.
• Routing map: Document which front-end routes read from Sanity and which read from Payload, and update that map with each group.
• Reference handling: Where a Payload document points to a Sanity document not yet moved, decide whether to store a temporary link or wait for the target group.
• Draft handling: Move drafts with their group, so an editor never has pending work in a system that no longer serves that content.
• Permissions: Set Payload access control for each group before its editors are given access, since Payload field-level access is configured in code.

Confirm with your editorial and engineering leads how many groups the site will carry and whether the split still makes sense once cross-group references are counted.

A small team with a handful of document types and one public site usually has the smallest migration. The schemas fit in one Payload config, the dataset is a single export, and the main work is rebuilding the front end against Payload's generated types. Because Payload installs into a Next.js /app folder, the team can often keep one codebase for the Studio-equivalent admin and the site.

• Schema scope: Count the document types, references and Portable Text fields, then map each to a Payload collection, global or block.
• Front end scope: Confirm whether the existing GROQ queries and image pipeline are rewritten or replaced, since this is often larger than the content move.
• Drafts and history: Decide whether editors need past versions in Payload or only the current published and draft states.
• Hosting: Confirm where the Next.js app and database will run, and who holds the backups.
• Editors: Plan a short walkthrough of the new admin panel before the old Studio is switched off.

For a single-site estate, check that the export tarball holds every asset the live site renders before the hosted dataset is retired.

An estate with several sites, many datasets or several locales needs a mapping exercise before any data moves. Each dataset may hold a different schema version, and shared document types can be used differently by each brand. Payload's localization and versions features cover much of this, but the team must decide how each dataset maps to one collection set, one tenant or separate installations.

• Dataset inventory: List each dataset, its schema version and which sites read from it, then decide which ones merge.
• Locale mapping: Confirm how Sanity's language fields and translation documents map to Payload's localized fields and locale codes.
• Cross-dataset references: Identify any references or shared assets that point across datasets, because these need new IDs.
• Import order: Load shared taxonomies and assets before the entries that reference them, and run the import once per dataset in a staging copy.
• Parity checks: Confirm that each locale renders the same entries, slugs and redirects as before.

For a multi-locale estate, ask whether the team wants one Payload instance for all sites or separate instances, because that choice drives the database and deployment plan.

A regulated team, such as one in banking, healthcare or the public sector, usually needs to show where content, assets, drafts and backups are stored. Moving content out of Content Lake into a database the team controls changes that picture entirely, but it also moves the team's obligations to its own infrastructure. Sanity Studio being MIT licensed does not, on its own, move the content, so the residency question has to be answered for the data itself.

• Data location: Confirm the region and provider for the database, object storage, backups and the export tarball during the migration.
• Access control: Map who can read drafts and history in Sanity today to Payload's field-level access rules and admin roles.
• Export handling: Confirm how the dataset export is stored, encrypted and deleted after import, and who approves that step.
• Evidence: Record the import logs, the skipped assets list and the reconciliation results as part of the change record.
• Assessor input: Ask the internal audit or compliance team which controls they expect to see in evidence before the cutover date is set.

DeployOpen prepares systems, controls and evidence for assessment, but the audit conclusion comes from the independent assessor the organization engages.