Sanity to Payload Migration: Moving to a Self-Hosted CMS

Sanity and Payload are both good headless CMSs, and moving between them is a real project, not a weekend export. This guide covers the decision first, then the mechanics: how Portable Text maps to Payload's Lexical editor, what breaks, and the order we'd do the work in. If you're still comparing every option, start with our headless CMS migration guide, which covers moves between Contentful, Sanity, Payload and Strapi.

Should you migrate from Sanity to Payload?

You should migrate from Sanity to Payload if owning your content and infrastructure is worth a few weeks of engineering, and you already run a Next.js site. You shouldn't migrate if your current Sanity setup works, your editors are happy and the only motive is a vague preference for open source.

The honest test is to write down the problem Sanity is causing. Good answers sound like this: our usage-based bill is hard to predict, legal wants content in our own database, we need the CMS and the front end in one repo and one deploy, or we want to query content with plain TypeScript instead of GROQ. A migration only pays back if it removes a specific, recurring cost.

For a side-by-side view of the two platforms beyond migration, our Sanity vs Payload comparison for Next.js marketing sites goes deeper on editing, hosting and developer experience.

Why do teams look for a self-hosted Sanity alternative?

Teams look for a self-hosted Sanity alternative mainly for data ownership, predictable costs and a simpler stack. Payload is open source, written in TypeScript, and since version 3 it installs directly into a Next.js app, so the admin panel and your marketing site share one codebase and one deployment.

• Your database, your data. Payload stores content in Postgres, MongoDB or SQLite that you control. Sanity stores content in its hosted Content Lake; you can export it, but you don't run it.
• One repo. With Payload, schema, admin and front end live together, and content queries run through Payload's Local API with no network hop.
• Cost shape. Sanity's plans are priced around seats and usage. Payload itself is free; you pay for hosting and a database. Check Sanity's current plan page before you do any break-even math.
• TypeScript all the way. Payload generates types from your collections, which many teams find easier than maintaining GROQ projections.

None of these is a reason on its own. Together, for a team that already deploys Next.js and has a developer on hand, they often are. We run Payload in production ourselves and wrote up what we learned in setting up Payload CMS for a marketing site.

When is Sanity's hosted model still the better call?

Sanity's hosted model is still the better call when you have no one to own infrastructure, when several editors work on the same documents at once, or when your editors rely on its visual editing and preview workflow. Self-hosting moves responsibility onto you: backups, database upgrades, uptime and security patches.

How does Portable Text convert to Lexical in Payload?

Portable Text converts to Lexical through a script that walks each Portable Text block and writes the matching Lexical node. Both formats are structured JSON, so nothing is guessed from HTML, but they're shaped differently: Portable Text is a flat array of blocks with marks, while Lexical is a nested tree under a root node.

There are two routes. The direct route maps JSON to JSON, as above, and keeps everything. The shortcut renders Portable Text to HTML, then uses the HTML-to-Lexical converter that ships with Payload's Lexical package. The shortcut is faster to write, but custom blocks and internal reference links tend to flatten into plain HTML, so we only use it for simple blog bodies.

How do you migrate Sanity to Payload step by step?

You migrate Sanity to Payload by modeling the new collections first, exporting the dataset, transforming documents and assets with a script, importing through Payload's Local API, then rewriting queries and redirects before cutover. Do it in that order and keep Sanity live until the last step.

1. 1

   Audit and remodel the schema

   List every Sanity document type and decide what becomes a collection, a global or a block. This is the moment to drop unused fields, as our guide to content modeling for a CMS migration explains.

2. 2

   Export the dataset

   Use the Sanity CLI dataset export, which produces an NDJSON file of documents plus your assets. Skip draft documents unless editors need them.

3. 3

   Move assets first

   Upload every image and file into a Payload upload collection, and store a map of old asset IDs to new media IDs. Carry alt text and crop or hotspot data across.

4. 4

   Transform and import documents

   Run the Portable Text to Lexical script, swap references for new Payload IDs, and create documents through the Local API in dependency order: authors and categories before posts.

5. 5

   Rewrite the front end queries

   Replace each GROQ query with a Payload query and check that every page renders the same fields.

6. 6

   Check URLs and SEO

   Keep slugs identical where you can, add redirects where you can't, and compare titles, descriptions and canonical tags page by page.

7. 7

   Freeze, re-run, cut over

   Freeze edits in Sanity, re-run the import for a final delta, switch the site to Payload and keep the Sanity project read-only for a while.

What breaks in a migration from Sanity to Payload?

The things that break are rarely the text. They're images, references, preview and the queries that tie it all together. Plan for each before you start.

• References. Sanity references point to document IDs, and arrays carry their own keys. Every reference needs remapping to a new Payload ID.
• Drafts and versions. Sanity drafts are separate documents with a drafts prefix. Decide whether to import them as Payload drafts or discard them.
• Live preview. Sanity's Presentation tool doesn't come with you. Payload has its own live preview, but it has to be wired to your pages.
• Asset URLs. Any image URL hard-coded to Sanity's CDN in content or code will break once you close the project.

If an AI coding agent is doing the bulk transform work, these are exactly the points a human still has to check. Our piece on AI-assisted website migration covers where agents help and where they don't.

Payload vs Sanity: which should you choose after weighing the move?

Choose Payload if you want a CMS that lives in your codebase and database; choose to stay on Sanity if you want a hosted platform that someone else runs. The table below sums up the trade-offs we see most often.