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#
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.
| Option | What it is |
|---|---|
url | The Payload server |
collections | Collection slugs, or collection configs for the exact schema |
globals | Global slugs or configs |
token | An 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 |
authorization | A full Authorization header value |
locales | Locale codes, the default first; with several, the source reads locale=all |
file, data | A payload.json bundle instead of the API, such as one a Galerne export wrote |
How content maps#
| Payload | Galerne |
|---|---|
| Collection | Document type; admin.useAsTitle becomes the preview title |
| Global | Singleton |
| Document id | Document id |
| Upload collection | Media; focalX and focalY become the hotspot |
| text, textarea, email, number, checkbox, date, select, radio | The matching field types |
| relationship (also polymorphic) | reference, or a list of references |
| upload | image or file, or blocks with hasMany |
| richText (Lexical or Slate) | Rich text |
| array, blocks | blocks |
| group | object |
| point | geopoint |
| json, code | code |
| row, collapsible, tabs | Their fields, flattened |
| Localized fields | Localized 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.
uiandjoinfields 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#
galerne export --to payload --out ./payload-export| Option | What it is |
|---|---|
mediaSlug | Slug 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
focalXandfocalY. - Document-level translations get
languageandtranslationOffields andcustom: { i18n: 'doc' }. - Embeds become Lexical block nodes, and
relationshipembeds relationship nodes. Each rich text field lists its blocks undercustom.blocks; add them to the editor withBlocksFeature.