Blueprints

Configure Media Library with Blueprints

Configure Media Library fields as code with defineMediaLibraryConfig, a singleton config resource.

Media Library is Sanity's organization-wide asset management. With Blueprints, you can manage its configuration as code with a singleton config resource, deployed alongside your other infrastructure.

Beta

In this guide, you'll define a Media Library configuration resource with Blueprints and deploy the blueprint to Sanity.

Prerequisites:

  • The latest version of the sanity CLI is recommended to interact with Blueprints. You can always run the latest CLI commands with npx sanity@latest.
  • An organization with Media Library and permission to configure it.
  • @sanity/blueprints 0.26.0 or later.
Before you can configure Media Library, you need a blueprint.

Initialize a new blueprint

This resource needs an organization-scoped stack. If you already have one, skip to the next section. If you have a project-scoped stack, promote it to organization scope instead of creating a new one.

To initialize a blueprint and an organization-scoped stack in the current directory, run:

npx sanity@latest blueprints init . --type ts --organization-id YOUR_ORGANIZATION_ID --stack-name production

The command creates a sanity.blueprint.ts file in the current directory and a new stack in your organization:

  • YOUR_ORGANIZATION_ID: Your organization ID. To list your organizations and their IDs, run npx sanity@latest organizations list.
  • --type ts: The blueprint file format. Use js or json for a JavaScript or JSON file.
  • --stack-name production: The name of the new stack. Use any name.

Configure Media Library

Use defineMediaLibraryConfig to declare the custom fields your Media Library exposes. Blueprints resolves your organization's Media Library installation automatically.

import {defineBlueprint, defineMediaLibraryConfig} from '@sanity/blueprints'

export default defineBlueprint({
  resources: [
    defineMediaLibraryConfig({
      name: 'media-library',
      root: './media-library',
      fields: [{name: 'brand', title: 'Brand', src: './src/fields/brand.tsx'}],
    }),
  ],
})
  • name: The resource name, unique within the blueprint.
  • root: The config directory, relative to the blueprint file. It contains the config's package.json.
  • fields: The custom fields. Declare at least one. Each field has a unique name, a title, a src path relative to root, and an optional public flag that makes the field readable outside your organization.

Fields use the same shape as unstable_defineMediaLibrary in sanity.cli.ts. For what a field's src file exports, see the Extension API reference.

Deploy the blueprint

Next, deploy the blueprint.

npx sanity blueprints deploy

After the deployment finishes, your Media Library configuration is applied to your organization.

If you need to make changes, update the blueprint file (sanity.blueprint.ts) and run the deploy command again.

Destroy a deployed blueprint

Sometimes you want to remove a deployed resource so it won't run anymore or affect any future usage quotas.

To remove a resources created with a blueprint, you need to either:

  • Remove the definition from the blueprint, and run the deploy command again.
  • Destroy the blueprint with the destroy command.

The blueprints destroy command removes, or undeploys, the blueprint and all of its resources from Sanity's infrastructure. It does not remove your local files.

npx sanity blueprints destroy

To remove the resource from the blueprint locally, you can remove it from the resources array in the sanity.blueprint.ts file, then delete any associated files.

Redeploying a destroyed blueprint

When you run blueprints destroy, it's as if you never used blueprints init during setup. The only difference is you still have all the files in your directory. To use this blueprint again and redeploy it, you'll need to let Sanity know about it. You can do this by running init again:

npx sanity blueprints init

This launches an editing interface that lets you reconfigure the blueprint, if needed, and it reconnects the blueprint to Sanity. Now you can add more functions or redeploy. Keep in mind that any environment variables added before destroying the blueprint will not carry over.

Learn more about Media Library

Was this page helpful?

Sanity logosanity.ioAll Systems Operational© Sanity 2026
Change site theme