sanity-plugin-air

Browse and insert assets from your Air workspace directly in Sanity Studio.

Features

• Custom Field Type — Use air.asset fields to store Air asset references in your documents
• Asset Picker — Browse, search, and select assets from Air without leaving the Studio
• Editable Metadata — Edit name, description, tags, and alt text inline
• Version Control — Choose between static (pinned) and dynamic (latest) asset URLs

Installation

npm install sanity-plugin-air

Setup

Add the plugin to your sanity.config.ts:

import { defineConfig } from 'sanity'
import { airPlugin } from 'sanity-plugin-air'

export default defineConfig({
  // ...
  plugins: [
    airPlugin({ workspaceId: '<your-air-workspace-id>' }),
  ],
})

The workspaceId is required. You can find it in your API Access page.

Usage

Adding an asset field

Use the air.asset type in your schema definitions:

import { defineField, defineType } from 'sanity'

export default defineType({
  name: 'article',
  title: 'Article',
  type: 'document',
  fields: [
    defineField({
      name: 'title',
      title: 'Title',
      type: 'string',
    }),
    defineField({
      name: 'featuredImage',
      title: 'Featured Image',
      type: 'air.asset',
    }),
  ],
})

When editors click the field, a picker dialog opens where they can browse and select assets from Air.

Querying asset data

Use GROQ to query the stored asset data:

*[_type == "article"] {
  title,
  featuredImage {
    name,
    alt,
    type,
    urls {
      selected,
      static,
      dynamic,
      thumbnail
    },
    width,
    height,
    aspectRatio
  }
}

Rendering in your frontend

// Example with Next.js
import type { AirAssetValue } from 'sanity-plugin-air'

function Article({ featuredImage }: { featuredImage: AirAssetValue }) {
  return (
    <img
      src={featuredImage.urls.selected}
      alt={featuredImage.alt ?? featuredImage.name}
      width={featuredImage.width}
      height={featuredImage.height}
    />
  )
}

Type guard

Use isAirAssetValue() to check if a value is a valid Air asset:

import { isAirAssetValue } from 'sanity-plugin-air'

if (isAirAssetValue(data.featuredImage)) {
  // data.featuredImage is typed as AirAssetValue
  console.log(data.featuredImage.urls.selected)
}

Configuration

| Option | Type | Required | Description | |--------|------|----------|-------------| | workspaceId | string | Yes | Your Air workspace ID | | assetTypes | AssetFileKind[] | No | Filter by asset type. If omitted, all types are shown | | fileExtensions | string[] | No | Filter by file extension (e.g., ['jpg', 'png', 'pdf']) | | openSelectedAssetModal | boolean | No | Auto-open the asset detail modal when a selected asset is provided. Defaults to false |

Asset type filter values

'image' | 'video' | 'audio' | 'vector' | 'presentation' | 'document' | 'pdf' | 'rive' | 'compressed' | 'spreadsheet' | 'threeD' | 'other'

Note: Only image is fully supported at this time. Support for additional asset types is coming soon.

Example with filters

airPlugin({
  workspaceId: '<your-air-workspace-id>',
  assetTypes: ['image'],
  fileExtensions: ['jpg', 'png', 'webp'],
})

Asset data reference

AirAssetValue

The object stored in your Sanity document when an asset is selected:

| Field | Type | Description | |-------|------|-------------| | assetId | string | Asset ID from Air (groups versions together) | | versionId | string | Specific version ID of the asset | | workspaceId | string | Workspace ID where the asset belongs | | type | string | Asset type ('image', 'video', 'audio', etc.) | | urls | AirAssetUrls | Asset URLs (see below) | | name | string | Asset filename | | description | string? | Asset description (editable in Sanity) | | tags | string[]? | Asset tags (editable in Sanity) | | alt | string? | Alt text for accessibility (editable in Sanity) | | customFields | AirCustomField[]? | Custom fields defined in Air | | width | number? | Width in pixels | | height | number? | Height in pixels | | aspectRatio | number? | Aspect ratio | | versionReference | 'static' \| 'dynamic'? | Which URL mode the user selected |

AirAssetUrls

| Field | Type | Description | |-------|------|-------------| | static | string | Pinned to a specific asset version (imgix URL for images, HLS stream for videos) | | dynamic | string \| null | Always points to the latest version (CDN link). null if no CDN link has been set | | selected | string | The URL the user chose — either static or dynamic | | thumbnail | string | Thumbnail preview image |

Version reference modes

• Static — urls.static points to the exact version that was selected. The URL will not change if the asset is updated in Air.
• Dynamic — urls.dynamic always resolves to the latest version of the asset. Use this if you want your content to automatically reflect asset updates.

The urls.selected field contains whichever URL the user chose, so you can simply use urls.selected in most cases.

Troubleshooting

Plugin not appearing in Sanity Studio

1. Verify the plugin is installed: npm ls sanity-plugin-air
2. Ensure airPlugin() is in the plugins array in sanity.config.ts
3. Restart Sanity Studio

Asset picker shows a blank screen

1. Check the browser console for errors
2. Ensure your Air workspace ID is correct
3. Verify you have an active Air account with access to the workspace

Domain not approved

Domains on sanity.studio are automatically approved. localhost is also always allowed so you can build and test your Studio locally without any configuration. If you use a custom domain for your Studio (e.g., cms.your-company.com), add it in your Air workspace settings under approved domains.

GraphQL deploy fails with "anonymous inline object" error

If you run sanity graphql deploy and see an error like:

HelpfulError: Encountered anonymous inline object "urls" for field/type "AirAsset"

Make sure you are on sanity-plugin-air v0.1.0-beta.3 or later. Earlier versions defined urls and customFields as anonymous inline objects which are not supported by Sanity's GraphQL codegen. The fix extracts them into named top-level types (air.asset.urls and air.asset.customField).

Peer dependencies

This plugin requires:

• react >= 18
• react-dom >= 18
• sanity >= 3

License

MIT