# Migrate from Payload

> Import Payload collections and globals into Galerne from the REST API or a file, with Lexical and Slate rich text, and export Galerne content as Payload data, configs and a seed script.

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](/docs/migrate.md) 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.
- `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
```

| 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 `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`.
