Skip to content
flowcms

Migrate from Contentful

Move a Contentful space to Flow CMS — map content types and locales, export over the CMA, and swap the delivery layer.

Contentful and Flow CMS share the same worldview — structured types, references and API-first delivery — so this migration is mostly mechanical. What changes is where it runs (your infrastructure), the pricing model, and having SEO + AI built into the editor instead of arriving via marketplace apps.

The shape of the migration

  1. Recreate the model (types map almost 1:1).
  2. Export content and assets with Contentful's tooling.
  3. Import assets, then entries, resolving references.
  4. Swap the delivery layer in your front-end.

1. Map the model

Contentful Flow CMS Notes
Content type Collection / Single Same concept
Reference field Reference Expand on read replaces include
Asset Media WebP optimization on upload
Rich text Block editor rich text Embedded entries become components
Locales Localized fields Migrate the default locale first
Environments Draft → published workflow Drafts + preview tokens cover the common case

2. Export the space

Contentful's CLI exports everything as one JSON file (entries, assets, the model), or read the Delivery/Management APIs directly if you want to transform as you go.

3. Import into Flow CMS

  • Assets first: download from the exported asset URLs, upload, keep an old-id → new-id map.
  • Entries next: walk the export, mapping fields; convert rich text documents to the block editor format; resolve reference fields through the id map (import parents after children, or import all then patch references).
  • Publish as a second pass so a half-imported state is never live.

Do the default locale end-to-end first. Additional locales import cleanly once the reference graph exists.

4. Swap the delivery layer

Where the front-end called Contentful's delivery API, point it at REST or GraphQL with a read-only CONTENT token (Settings → API Tokens):

  • include=N becomes explicit expand of the references you need.
  • Preview API → preview tokens for drafts.
  • Webhook-triggered rebuilds → the same pattern with Flow CMS webhooks, or on-demand revalidation instead of full rebuilds.

The @flowcms/client SDK is the tidiest endpoint: typed queries, token handling, pagination.

Budget-wise the shift is structural: Contentful bills per seat/record/locale on their infrastructure; self-hosted Flow CMS costs whatever your Postgres box costs, with editions unlocking governance features. The compare page has the detailed breakdown.