Media Library

Migrate assets from Media Plugin to Media Library

Moving from Media Plugin to Media Library requires that you move your assets, re-link them to your documents, and update any references.

This is a paid feature

This feature is available as an addon for certain Enterprise plans.

In this guide, we'll look at one approach to migrate assets from the Media Plugin to Media Library. At the end of this guide, we've included an example migration script and instructions on how to run it. You can go directly to the code if you aren't interested in the core parts of the script.

In the future, we plan to offer a more direct dataset to Media Library migration tool. For now, we recommend adapting this code to your needs.

Limitations and tips

  • This approach is intended for assets stored in a Sanity dataset that you want migrated to Media Library. If you have assets stored elsewhere, you'll need to adjust the download/upload approach. For example, if you use an external asset source, you'll need to download those assets and adjust how you identify their connection to documents.
  • Keep rate limits and API quota in mind. Downloading all assets, and making high volumes of document mutations, can drastically affect your usage.

Migration overview

Migrating from dataset-stored assets to Media Library involves the following process.

  • Export your dataset and assets.
  • Upload assets to Media Library.
  • Link assets to your dataset.
  • Update (mutate) documents in the dataset with new reference to each new ML asset.
  • Optional: Migrate legacy metadata to a Media Library aspect.

Export your dataset and gather assets

While you can use the APIs to download each asset, search for it across documents, and write changes, we find it is easiest to download your entire dataset and assets to work with the files locally.

From your Sanity project, export the dataset with the sanity CLI:

Replace dataset-name with the name of your dataset. Follow the prompts to select a download location and filename.

Next, uncompress the file (production.tar.tz, if your dataset was production) and you're left with a directory containing your data (data.ndjson, asset document data (assets.json), and an images directory.

Upload assets to Media Library

We'll use Media Library's HTTP API to upload each image. The process looks like this:

  • Iterate over each image in the images directory.
  • Upload the image to Media Library using the /upload endpoint.
  • Store the response, which contains the assetId and the assetInstanceId. You'll need these to link the asset to your dataset.

Learn more about the upload process in this guide.

Link assets to your dataset

Media Library connects assets to your datasets with a Global Document Reference (GDR). The process is as follows:

  • Iterate over each asset, and use the assetId, assetInstanceId, and mediaLibraryId to make a request to the /assets/media-library-link endpoint.

Update documents to the new reference

Next, you need to iterate over the documents in the data.ndjson file, identify the location of each asset reference, then patch all instances with the correct reference to the asset in Media Library. This process is:

  • Iterate over the lines of data.ndjson
  • Check if a the line (document) contains an image reference, and if so store the document's _id and the image path.
  • Iterate over the matching documents and patch them with a media object containing the GDR to the asset in Media Library.

Learn more about the linking and patching assets process.

Optional: Migrate metadata to aspect

Media Library offers aspects for managing internal metadata. This differs from the Media Plugin's tags and additional fields (like title, alt text, description), but can be a useful place to store these during migration.

To migrate the metadata to an aspect, the process is:

  • Create a new aspect that matches the shape of the Media Plugin's metadata.
  • After uploading assets to Media Library, collect metadata from the old assets using the assets.json export.
  • Map the metadata onto the new Media Library assets, and patch it into the aspects field.

Learn more about adding aspects to uploaded assets.

Migration example script

In a new directory, initialize an NPM/PNPM project. If you prefer, you can use an existing Sanity project, but we'll be adding some development dependencies.

Experimental

Install types and dependencies:

And finally types:

Next, create a .env file with the following values:

  • SANITY_TOKEN: Run npx sanity debug --secrets to obtain your auth token. You'll need read/write access to the source dataset and Media Library.
  • SANITY_PROJECT_ID: Copy your projectId from sanity.io/manage.
  • SANITY_SOURCE_DATASET: Set to the dataset containing the documents and images you wish to update.
  • SANITY_MEDIA_LIBRARY_ID: Set to your Media Library ID. You can obtain this from the Media Library URL. See this guide for details.
  • IMAGES_DIR: Set to the path to the images folder in the exported dataset archive. This path is relative to the current directory.
  • FILES_DIR: Set to the path to the files folder in the exported dataset archive. This path is relative to the current directory.
  • DATA_FILE_PATH: The path to the data.ndjson file relative to the current directory.
  • ASSETS_FILE_PATH: The path to the assets.json file relative to the current directory.

Finally, create a TypeScript file and add code below. We'll name ours migrate-media.ts.

You can run the code with tsx.

It comes with a few options:

  • --dry-run: Explains what the script would do based on your options, but won't perform any writes.
  • --verbose: Outputs all logging details as each image is uploaded, linked, etc.
  • --test-image <image-name>: You can pass an individual image name to see how the script will act on an individual image.
  • --include-aspects: Use this flag to also map Media Plugin metadata onto aspects when available. Make sure to create a new aspect named metadata. See the example aspect file.

Was this page helpful?