docs menu

Migrate from Payload

The Payload source reads collections and globals through the Payload REST API, published and draft for collections with drafts, in every locale. Give the collection configs to get the exact schema; with slugs only, the schema is inferred from the content.

Import#

bash
galerne import --from payload --url https://cms.example.com --collections posts --source-token <api-key> --dry-run
galerne import --from payload --url https://cms.example.com --collections posts --source-token <api-key>

On the CLI, list options take a single value. For several collections, globals or locales, use the import_from tool, @galerne/migrate in code, or a bundle file.

Options go after --from as flags in kebab case (projectId is --project-id). With the import_from tool, they go in options. See the migration overview for the shared flags, the report and re-runs.

OptionWhat it is
urlThe Payload server
collectionsCollection slugs, or collection configs for the exact schema
globalsGlobal slugs or configs
tokenAn API key, sent as users API-Key <key>; values starting with JWT, Bearer or <collection> API-Key are sent as they are. On the CLI: --source-token
authorizationA full Authorization header value
localesLocale codes, the default first; with several, the source reads locale=all
file, dataA payload.json bundle instead of the API, such as one a Galerne export wrote

How content maps#

PayloadGalerne
CollectionDocument type; admin.useAsTitle becomes the preview title
GlobalSingleton
Document idDocument id
Upload collectionMedia; focalX and focalY become the hotspot
text, textarea, email, number, checkbox, date, select, radioThe matching field types
relationship (also polymorphic)reference, or a list of references
uploadimage or file, or blocks with hasMany
richText (Lexical or Slate)Rich text
array, blocksblocks
groupobject
pointgeopoint
json, codecode
row, collapsible, tabsTheir fields, flattened
Localized fieldsLocalized fields; custom.i18n: 'doc' gives document-level translations
_status: 'draft'A draft; never published when the published view is a draft too

What the import loses#

The report lists each of these when it happens.

  • Relationships to collections you did not import keep their ids as text, with a warning; uploads from collections you did not import are dropped from rich text.
  • ui and join fields are skipped; other unknown field types are dropped with a warning.
  • In Lexical, subscript and superscript are dropped and checklists become bullet lists. Rich text in another format is dropped.

Lexical blocks become embeds of a block type with the block's slug, with fields from its config when a blocks field or the rich text field's custom.blocks lists it, and inferred from the values otherwise. Relationship nodes become embeds of a relationship block that holds a reference.

Export to Payload#

bash
galerne export --to payload --out ./payload-export
OptionWhat it is
mediaSlugSlug of the upload collection, default media; other files go to <mediaSlug>Files

The folder holds payload.json (format galerne-payload/1), data per collection in data/ and data/globals/, media.json, collection and global configs (collections/<slug>.ts, globals/<slug>.ts), a payload.config.fragment.ts with localization, a seed.ts to load the data, and a README.md.

The export loses:

  • Every collection gets drafts turned on, so draft and published versions both come across.
  • Image sub-fields are dropped, with a warning; the hotspot becomes focalX and focalY.
  • Document-level translations get language and translationOf fields and custom: { i18n: 'doc' }.
  • Embeds become Lexical block nodes, and relationship embeds relationship nodes. Each rich text field lists its blocks under custom.blocks; add them to the editor with BlocksFeature.