By Mehdi HassanPlenty of teams on Strapi v4 are at the same fork: run the major upgrade to v5, or use the moment to switch to Payload. Both involve real work on your API layer, and picking without comparing is how teams end up doing both. This guide helps you choose, then lays out how the move works if Payload wins. It's part of our headless CMS migration guide, which covers every route between Contentful, Sanity, Payload and Strapi.
Should you upgrade Strapi v4 to v5 or switch to Payload?
Upgrade Strapi v4 to v5 if your code is mostly standard content types and the official upgrade tool covers it. Switch to Payload if you already run a Next.js front end, you have several custom plugins or controllers that need rewriting anyway, or you want to stop running a separate CMS server.
The reason it's a real choice: Strapi v5 changed how the API works. It introduced the Document Service API in place of the Entity Service, a string documentId as the main identifier, and a flatter REST response without the nested attributes wrapper. Strapi provides an upgrade tool with codemods, but any front-end code that reads the v4 response shape, and any custom back-end code, has to be checked and often changed.
Option | Best when | Main cost |
|---|---|---|
Upgrade to Strapi v5 | Standard types, few custom plugins, team knows Strapi | Front-end query changes, plugin compatibility |
Switch to Payload | Next.js front end, custom code to rewrite anyway | Rebuilding schema, logic and content import |
Stay on v4 for now | No budget this quarter, site is stable | Growing upgrade debt and plugin drift |
Staying on v4 is a short-term option, not a plan. Check Strapi's current support policy for v4 before you decide how long to wait.
Why do teams choose Payload as a Strapi alternative?
Teams choose Payload as a Strapi alternative because it's code-first, TypeScript throughout and installs into a Next.js app, so the CMS and the website share one repo, one deploy and one set of types. Like Strapi, it's open source and self-hosted, so you keep your data in your own database.
- One app instead of two. Strapi usually runs as its own Node server; Payload's admin and API live inside Next.js.
- Schema in code. Payload collections are TypeScript config, reviewed in pull requests like any other code.
- Local API. Pages query content directly in the server process, with no HTTP round trip.
- Familiar databases. Payload supports Postgres, MongoDB and SQLite, so a team already on Postgres can stay on it.
Strapi still has strengths: a visual content-type builder that non-developers can use, a large plugin marketplace and a managed hosting option. If those matter to you, the upgrade route is probably right. Our comparison of Contentful, Sanity, Payload and Strapi weighs all four for marketing sites.
How do Strapi content types map to Payload?
Strapi content types map closely to Payload: collection types become collections, single types become globals, components become groups or arrays, and dynamic zones become blocks fields. The concepts line up well, which is why this is one of the more mechanical headless migrations.
Strapi | Payload | Notes |
|---|---|---|
Collection type | Collection | Slugs and IDs change; keep a map |
Single type | Global | Settings, navigation, footer |
Component (single) | Group field | Same fields, nested |
Component (repeatable) | Array field | Order is preserved |
Dynamic zone | Blocks field | One Payload block per component |
Relation | Relationship field | Remap IDs after import |
Media field | Upload field | Re-upload files to an upload collection |
Rich text (Markdown or Blocks) | Lexical rich text | Needs a converter script |
Lifecycle hooks | Collection hooks | Rewrite in TypeScript |
Converting Strapi rich text to Lexical
Strapi has two rich-text formats. The older Rich text field stores Markdown, and the newer Blocks editor stores structured JSON.
Markdown content can go through the Markdown-to-Lexical converter in Payload's Lexical package. Blocks JSON is a node tree, much like Lexical's, so a short script can map paragraphs, headings, lists, links and images node by node. Test either route on your longest and oldest entries first, since that's where unusual formatting hides.
How do you migrate from Strapi to Payload step by step?
You migrate from Strapi to Payload by rebuilding the schema in Payload, porting custom logic, importing media and then content, switching the front end's queries, and cutting over once a final import has run. Keep Strapi running read-only until the new setup is proven.
Inventory the Strapi project
List content types, components, dynamic zones, plugins, custom controllers, lifecycle hooks and roles. Custom code is what sets the timeline.
Rebuild the schema in Payload
Write collections, globals and blocks in TypeScript. Drop fields nobody uses, as our guide to content modeling for a CMS migration recommends.
Port custom logic
Turn lifecycle hooks into Payload hooks and custom controllers into Payload endpoints or Next.js route handlers.
Import media
Download files from the Strapi media library or its storage provider and upload them to a Payload upload collection, saving an old-to-new ID map.
Import content
Read entries from the Strapi API or database, convert rich text, remap relations and media, and create documents through the Local API.
Switch the front end
Replace Strapi REST or GraphQL calls with Payload queries, and compare rendered pages with the live site.
Cut over
Freeze Strapi edits, re-run the import, deploy, and keep the Strapi database backed up.
Can AI coding agents speed up a Strapi to Payload migration?
Yes, AI coding agents can speed up a Strapi to Payload migration because much of the work is mechanical: reading Strapi schema files and writing matching Payload collection configs, drafting import scripts, and rewriting query code. A human still has to check relations, permissions and rendered pages.
Strapi stores each content type's schema as JSON in the project, which gives an agent a clean, complete input to work from. The judgment calls, such as which fields to drop and how to model blocks, stay with the team. Our guide to AI-assisted website migration explains where agents help and where they don't, and our notes on setting up Payload CMS for a marketing site cover what to configure once you land.
What's our verdict on Strapi vs Payload for a migration?
Our verdict depends on how much custom code you have and where your front end lives. The more your Strapi project looks like a standard CMS with a Next.js site in front, the more a switch to Payload simplifies things.
