docs menu

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#

bash
# 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.gz

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
projectIdSanity project id. Required without file or data
datasetDataset name. Required without file or data
tokenA read token, for drafts and private datasets. On the CLI: --source-token
apiVersionAPI version, default v2021-10-21
fileA .tar.gz or .tar from sanity dataset export (documents, images and files), or an .ndjson file
dataThe NDJSON content inline (tools)
includeDraftsfalse skips drafts. Default: included
languageFieldThe field that holds a document's language, default language
baseLanguageThe source language of translation groups. Default: the first in each group
urlFilesCopy 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#

SanityGalerne
_typeDocument type
_idDocument id, kept
drafts.<id>The draft of <id>; the published document is its published version
Portable TextRich text, see below
referencereference, _weak kept
slug ({ current })slug
image with hotspot and cropimage with hotspot and crop; extra image fields kept
sanity.imageAsset, sanity.fileAssetMedia, with alt text, title, description as caption and credit line as credits
geopoint, color, code, tablegeopoint, color (hex), code, table
Arrays of objectsblocks, 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 nameA singleton

Portable Text#

Portable TextGalerne rich text
Styles h1 to h6, blockquoteHeadings, blockquote
listItem and levelNested bullet and ordered lists
Decorators strong, em, underline, strike-through, codeBold, italic, underline, strike, code
Link annotationsLinks, blank kept as a new tab
Annotations that reference a documentdoc:<id> links
Image blocks, code blocksImages (media:<id>), code blocks
Other block objectsEmbeds 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#

bash
galerne export --to sanity --out ./sanity-export --dataset production
OptionWhat it is
datasetDataset 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-input and tables @sanity/table in your studio.
  • Images inside rich text that do not point to Galerne media are dropped.
  • Horizontal rules become break blocks.