Define an application with Blueprints

Deploy an SDK app as a blueprint resource with defineApplication and its view definers.

Sanity App SDK applications are custom apps that run in your Sanity organization. With Blueprints, you can deploy an application as a resource, declared in the same sanity.blueprint.ts file as your other infrastructure and deployed with the same workflow.

In this guide, you'll define an application 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 existing project and an organization role with permission to deploy SDK apps (requires the Manage SDK Apps permission).
• @sanity/blueprints 0.26.0 or later.

npx sanity@latest blueprints init . --type ts --project-id <project-id> --stack-name production

pnpm dlx sanity@latest blueprints init . --type ts --project-id <project-id> --stack-name production

yarn dlx sanity@latest blueprints init . --type ts --project-id <project-id> --stack-name production

bunx sanity@latest blueprints init . --type ts --project-id <project-id> --stack-name production

Use defineApplication to define an application. Point root at the app's directory, the one that contains its package.json. Declare the app's views in views and its web workers in webWorkers:

import {
  defineApplication,
  defineAssetSourceView,
  defineBlueprint,
  definePanelView,
  defineTileView,
  defineWebWorker,
  defineWindowView,
} from '@sanity/blueprints'

export default defineBlueprint({
  resources: [
    defineApplication({
      name: 'design-retro',
      title: 'Design Retro',
      root: './apps/design-retro',
      icon: './src/icons/app-icon.svg',
      views: [
        defineWindowView({
          name: 'main',
          title: 'Design Retro',
          src: './src/windows/main.tsx',
          dock: {group: 'applications', order: 10},
        }),
        definePanelView({
          name: 'side',
          title: 'Favorites',
          src: './src/panels/main.tsx',
        }),
        defineTileView({
          name: 'jump-back-in',
          title: 'Jump back in',
          src: './src/tiles/jump-back-in.tsx',
          size: 'banner',
        }),
        defineAssetSourceView({
          name: 'image-picker',
          title: 'Image Picker',
          src: './src/asset-sources/image-picker.tsx',
        }),
      ],
      webWorkers: [
        defineWebWorker({
          name: 'background-refresh',
          title: 'Background Worker',
          src: './src/workers/background-refresh.ts',
        }),
      ],
    }),
  ],
})

Each view and web worker is declared with its own definer:

• defineWindowView: the app's navigable, full-page view. An application can have at most one. Use dock to place it in the dock.
• definePanelView: a view that opens beside the current app from its own dock item.
• defineTileView: a view on the Dashboard home page. size is required, and is small, large, or banner.
• defineAssetSourceView: a custom asset source shown in asset pickers.
• defineWebWorker: a background worker. Declare it in webWorkers, not views.

Each definer's src points at a source file, relative to root, that implements the surface with the Dashboard Extension API. See Render a panel and Run a background service for the panel and worker source files, and the Extension API reference for the full API.

name identifies the resource in your blueprint, and slug sets the app's hostname, defaulting to name. Changing either one destroys the application and creates a new one. An application must declare at least one view.

For the full list of configuration options, see the Application Blueprints reference.

Next, deploy the blueprint.

npx sanity blueprints deploy

pnpm dlx sanity blueprints deploy

yarn dlx sanity blueprints deploy

bunx sanity blueprints deploy

After the deployment finishes, your application appears in your Dashboard. To confirm what was deployed, run npx sanity blueprints info.

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

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

pnpm dlx sanity blueprints destroy

yarn dlx sanity blueprints destroy

bunx 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.

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

pnpm dlx sanity blueprints init

yarn dlx sanity blueprints init

bunx 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.