@sanity/export

@sanity/export

Exports documents and assets from a Sanity dataset

Installing

npm install --save @sanity/export

Usage

import {exportDataset} from '@sanity/export'

exportDataset({
  // Instance of @sanity/client configured to correct project ID and dataset
  client: someInstantiatedSanityClientInstance,

  // Name of dataset to export
  // Cannot be combined with `mediaLibraryId`.
  dataset: 'myDataset',

  // Path to write tar.gz-archive file to, or `-` for stdout
  outputPath: '/home/your-user/myDataset.tar.gz',

  // Whether or not to export assets. Note that this operation is currently slightly lossy;
  // metadata stored on the asset document itself (original filename, for instance) might be lost
  // Default: `true`
  assets: false,

  // Exports documents only, without downloading or rewriting asset references
  // Default: `false`
  raw: true,

  // Whether or not to export drafts and versions. This also controls the
  // release (`_.releases.*`) and variant definition (`_.variants.*`) system
  // documents those versions depend on.
  // Default: `true`
  drafts: true,

  // Export only given document types (`_type`)
  // Optional, default: all types
  // Includes images/files referenced by these documents. Explicitly include
  // 'sanity.imageAsset' or 'sanity.fileAsset' to include unused assets too.
  types: ['products', 'shops'],

  // Run 12 concurrent asset downloads
  assetConcurrency: 12,

  // What mode to use when exporting documents, can be eiter `stream`(default) or `cursor`.
  // Cursor mode might help when dealing with large datasets, but might yield inconsistent results if the dataset is mutated during export.
  // Default: 'stream'
  mode: 'stream',

  // Export data from a media library, instead of a dataset.
  // Cannot be combined with `dataset`.
  mediaLibraryId: 'myMediaLibrary',

  // Whether to include the `assets.json` assets map. This file is not necessary when creating a
  // media library archive.
  // Caution: customising this option may result in an archive being produced that is impossible to import.
  // Optional, default: `true`
  assetsMap: true,

  // Whether to strictly enforce asset verification (hash and content-length checks against
  // the `x-sanity-sha1` / `x-sanity-md5` response headers). Set to `false` to keep assets
  // that fail verification (with a warning) instead of aborting the export.
  // Caution: disable only when recovering from known-bad source data (e.g. assets where the
  // originally-uploaded bytes are no longer available server-side).
  // Optional, default: `true`
  strictAssetVerification: true,

  // A custom filter function for controlling which documents are exported.
  // Optional, default: `() => true`
  filterDocument: (document) => (document.title ?? '').includes('capybara'),

  // A custom transformation function for controlling how each document is exported.
  // Caution: customising this option may result in an archive being produced that is impossible to import.
  // Optional, default: `document => document`
  transformDocument: (document) => ({
    ...document,
    title: document.title ?? 'capybara',
  }),
})

Future improvements

• Restore original filenames, keep track of duplicates, increase counter (filename (<num>).ext)
• Skip archiving on raw/no-asset mode?

CLI-tool

This functionality is built in to the @sanity/cli package as sanity dataset export

License

MIT-licensed. See LICENSE.

Assets in typed exports

With assets enabled, types: ['blogPost'] includes the posts and their referenced images and files, including nested fields and asset metadata. Shared assets download once. References to other document types, such as authors or categories, are not followed. Include those types when the destination needs those documents too.

Use raw: true to preserve original references without downloading assets when importing back into a dataset that already has them. assets: false removes image/file fields. Explicit asset types include all assets of those types, including unused assets.

Missing asset documents, missing download URLs, and HTTP 401, 403, or 404 responses are skipped. This preserves the existing behavior for unavailable files, but the resulting export may be incomplete. Other download failures still fail the export after any retries. File outputs replace the destination after the archive is complete; a failed export preserves an existing destination. Writable-stream consumers must discard output when the export promise rejects.

Asset documents retrieved separately are read after the selected documents and may have changed since the export started. This does not repair previously broken archives or make imports transactional.