Migrate from Sanity
The Sanity source reads a whole dataset: documents, drafts, translations and assets. It uses the dataset export API, the query API for public datasets without a token, or a file you exported yourself.
Import#
# with a token: drafts and private datasets included
galerne import --from sanity --project-id abc123 --dataset production --source-token sk… --dry-run
# a public dataset, no token: published documents only
galerne import --from sanity --project-id abc123 --dataset production
# a file from `sanity dataset export production production.tar.gz`
galerne import --from sanity --file production.tar.gzOptions 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 |
|---|---|
projectId | Sanity project id. Required without file or data |
dataset | Dataset name. Required without file or data |
token | A read token, for drafts and private datasets. On the CLI: --source-token |
apiVersion | API version, default v2021-10-21 |
file | A .tar.gz or .tar from sanity dataset export (documents, images and files), or an .ndjson file |
data | The NDJSON content inline (tools) |
includeDrafts | false skips drafts. Default: included |
languageField | The field that holds a document's language, default language |
baseLanguage | The source language of translation groups. Default: the first in each group |
urlFiles | Copy files that fields only link to by URL (.mp4, .pdf, images) into Galerne media. Default true |
With a token, the source calls the export endpoint https://<projectId>.api.sanity.io/<apiVersion>/data/export/<dataset>. Without a token, a refused export falls back to the query API, which returns published documents only. --since uses a GROQ filter on _updatedAt.
How content maps#
| Sanity | Galerne |
|---|---|
_type | Document type |
_id | Document id, kept |
drafts.<id> | The draft of <id>; the published document is its published version |
| Portable Text | Rich text, see below |
reference | reference, _weak kept |
slug ({ current }) | slug |
image with hotspot and crop | image with hotspot and crop; extra image fields kept |
sanity.imageAsset, sanity.fileAsset | Media, with alt text, title, description as caption and credit line as credits |
geopoint, color, code, table | geopoint, color (hex), code, table |
| Arrays of objects | blocks, keys kept; images, files and references inside arrays become blocks |
Field-level translations (locale… objects, internationalizedArray…) | Localized fields |
Document internationalization (translation.metadata, __i18n_lang) | Document-level translations with _lang and _translationOf |
| A type with one document whose id is the type name | A singleton |
Portable Text#
| Portable Text | Galerne rich text |
|---|---|
Styles h1 to h6, blockquote | Headings, blockquote |
listItem and level | Nested bullet and ordered lists |
Decorators strong, em, underline, strike-through, code | Bold, italic, underline, strike, code |
| Link annotations | Links, blank kept as a new tab |
| Annotations that reference a document | doc:<id> links |
| Image blocks, code blocks | Images (media:<id>), code blocks |
| Other block objects | Embeds of a block type with the same name, listed in the field's embeds |
Galerne does not run GROQ: rewrite your queries with the query API.
What the import loses#
The report lists each of these when it happens.
- Other text styles become paragraphs, with a warning.
- Inline objects inside text, and unknown marks and annotations, are dropped and listed.
- System documents and unpublished release versions (
versions.*) are skipped: publish the release first. - Hotspot width and height are dropped; Galerne keeps the hotspot point.
- An array mixing plain values and objects keeps only the objects.
- An asset missing from the archive is reported.
Export to Sanity#
galerne export --to sanity --out ./sanity-export --dataset production| Option | What it is |
|---|---|
dataset | Dataset name used in the folder, default production |
The folder holds <dataset>/data.ndjson with images/ and files/, the same as a <dataset>.tar.gz for sanity dataset import, schema types in schemaTypes/ (index.ts, locale.ts and one file per type), and a README.md. A published document is written under its id; a newer draft, or an unpublished document, under drafts.<id>.
The export loses:
- Hotspots are written with a width and height of 1.
- Tables become plain text cells; code fields need
@sanity/code-inputand tables@sanity/tablein your studio. - Images inside rich text that do not point to Galerne media are dropped.
- Horizontal rules become
breakblocks.