@autorender/sanity

AutoRender integration for Sanity Studio v3+. Browse, upload to, and pick from your AutoRender media library (images, video, and other files) without leaving the Studio.

AutoRender is a media/DAM (digital asset management) platform with a built-in image and video CDN. This plugin lets content editors browse, upload, and pick AutoRender assets directly from Sanity Studio, either as a source for Sanity's native image/file fields, or through a dedicated autorender.asset schema type that keeps the asset's AutoRender metadata (dimensions, tags, folder, etc.) attached to the document.

Table of Contents

• Quick Start
• Plugin Features
• Prerequisites
• Installation
• Usage
  • 1. autorenderAssetSourcePlugin — AutoRender as an asset source
  • 2. autorenderSchemaPlugin — AutoRender as a custom schema type
  • Uploading new files
• Security
• Asset Data Structure
• Working with Asset Data
• Advanced Topics
• License
• Documentation

Quick Start

npm install @autorender/sanity

// sanity.config.ts
import {defineConfig} from 'sanity'
import {autorenderAssetSourcePlugin, autorenderSchemaPlugin} from '@autorender/sanity'

const autorenderConfig = {apiKey: process.env.SANITY_STUDIO_AUTORENDER_API_KEY!}

export default defineConfig({
  // ...
  plugins: [
    autorenderAssetSourcePlugin(autorenderConfig), // adds "AutoRender" to image/file field pickers
    autorenderSchemaPlugin(autorenderConfig), // adds the `autorender.asset` schema type
  ],
})

That's enough to browse, upload, and pick AutoRender assets from any image/file field. Read on for the autorender.asset schema type (keeps assets served from the AutoRender CDN with full metadata attached) and the rest of the configuration options.

This plugin only talks to your AutoRender workspace's own endpoints (GET /files, GET /folders, POST /uploads) — it does not rename or delete assets, and it does not manage your DAM beyond that.

Plugin Features

• Browse AutoRender folders and files from inside Sanity Studio, with search and pagination.
• Upload new files straight to AutoRender from the same dialog — no need to leave the Studio to add something new to your DAM.
• Use AutoRender as an asset source for standard image and file fields — Sanity downloads the selected asset into its own asset pipeline, same as any other third-party asset source.
• Or use the autorender.asset object schema type to store the asset's AutoRender metadata (file number, folder, tags, dimensions, custom metadata, …) directly on your document, and keep serving the file from the AutoRender CDN.
• "Add multiple" support for arrays of autorender.asset objects.
• Diff view and document previews for autorender.asset fields.
• Zero required dependencies beyond @sanity/ui and @sanity/icons — the browsing UI is built with Sanity's own design system, no iframes or third-party widgets.

Prerequisites

Before you begin, you need:

• A Sanity Studio project (v3 or later) and a local instance of it running. Refer to Sanity's official documentation if you haven't set one up yet.
• Node.js and npm/yarn/pnpm installed.
• An AutoRender workspace and API key (from your AutoRender dashboard).

Installation

To install the plugin in your Sanity Studio instance, run one of the following commands from your project's root directory:

# Using npm
npm install @autorender/sanity

# Using yarn
yarn add @autorender/sanity

# Using pnpm
pnpm install @autorender/sanity

Usage

This package ships two plugins that can be used independently or together.

1. autorenderAssetSourcePlugin — AutoRender as an asset source

Add AutoRender as a source editors can pick from when filling in a normal image or file field.

// sanity.config.ts
import {defineConfig} from 'sanity'
import {autorenderAssetSourcePlugin} from '@autorender/sanity'

export default defineConfig({
  // ...
  plugins: [
    autorenderAssetSourcePlugin({
      apiKey: process.env.SANITY_STUDIO_AUTORENDER_API_KEY!,
      // baseUrl: 'https://upload.autorender.io/api/v1', // optional, this is the default
      // title: 'AutoRender', // optional, label shown in the asset source list
    }),
  ],
})

With this installed, any image or file field in your schema shows an "AutoRender" entry alongside "Upload" and "Browse" in the asset selection menu. Picking an asset there hands Sanity a plain CDN url; Sanity fetches it and creates a normal Sanity asset document, exactly like any other asset source.

2. autorenderSchemaPlugin — AutoRender as a custom schema type

Use this when you want to keep serving assets from the AutoRender CDN (instead of Sanity's), and want the asset's AutoRender metadata (tags, folder, dimensions, custom metadata) available in GROQ queries.

// sanity.config.ts
import {defineConfig} from 'sanity'
import {autorenderSchemaPlugin} from '@autorender/sanity'
import {schemaTypes} from './schemas'

export default defineConfig({
  // ...
  plugins: [
    autorenderSchemaPlugin({
      apiKey: process.env.SANITY_STUDIO_AUTORENDER_API_KEY!,
    }),
  ],
  schema: {
    types: schemaTypes,
  },
})

Then reference the autorender.asset type from your own document schemas:

// schemas/post.ts
import {defineType} from 'sanity'

export default defineType({
  name: 'post',
  type: 'document',
  fields: [
    {name: 'title', type: 'string'},
    {name: 'coverAsset', type: 'autorender.asset', title: 'Cover'},
    {
      name: 'gallery',
      type: 'array',
      title: 'Gallery',
      of: [{type: 'autorender.asset'}],
    },
  ],
})

A single autorender.asset field renders a preview plus "Select…"/"Remove" buttons. An array of autorender.asset gets an extra "Add multiple" button so editors can pick several assets from one browsing session.

Both plugins can be installed together — they share the same apiKey/baseUrl config shape, so most Studios simply call each with the same object.

Uploading new files

Both the asset-source dialog and the autorender.asset field's browser include an "Upload new" button, so editors can add a file straight to AutoRender without leaving Sanity. Uploads go to whichever AutoRender folder is currently open in the dialog (shown just below the folder breadcrumb). A successful upload is selected immediately — same behavior as Sanity's own native "Upload" button on an image field.

Security

Browsing your Autorender library (GET /files, GET /folders) requires a private API key — Autorender's public key is refused with a 403 on everything except uploading. Sanity Studio is a client-side React application, so the private key you pass into either plugin's config is bundled into the Studio's JavaScript and is visible to anyone with access to the Studio — including via browser devtools or the network tab, not just people you'd consider "developers". A private key can do everything the Autorender API offers in your workspace (list, upload, rename, delete), not just browse and upload.

• Restrict who has access to your Studio deployment appropriately for the sensitivity of your AutoRender workspace — this is the only real mitigation, since browsing requires a private key and there is currently no scoped or read-only key tier to fall back to.
• Never rely on this plugin, or Studio access control alone, as your only barrier to your AutoRender account — treat the key as public-ish, the same way you'd treat any other client-exposed credential.

Asset Data Structure

The autorender.asset object stores a camelCase mirror of the fields AutoRender returns from GET /files:

{
  "_type": "autorender.asset",
  "_key": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "fileNo": "f_8f3a2c1b",
  "name": "hero-banner.jpg",
  "url": "https://assets.autorender.io/wB5HrlVhGq/marketing/hero-banner.jpg",
  "thumbnail": "https://assets.autorender.io/wB5HrlVhGq/marketing/hero-banner.jpg",
  "width": 2400,
  "height": 1350,
  "format": "jpg",
  "mimeType": "image/jpeg",
  "size": 482113,
  "path": "marketing/hero-banner.jpg",
  "folderNo": "fo_1a2b3c4d",
  "folderName": "marketing",
  "tags": ["hero", "homepage"],
  "createdAt": "2026-01-14T10:32:00.000Z",
  "updatedAt": null,
  "metadata": {
    "alt_text": "Hero banner for the spring campaign",
    "photographer": "J. Rivera"
  }
}

A note on metadata keys

Sanity requires every object key stored on a document to match /^\$?[a-zA-Z0-9_-]+$/. AutoRender's custom metadata field is arbitrary and user-defined in your AutoRender workspace, so it can contain keys with spaces, dots, or other characters Sanity would reject.

This plugin sanitizes metadata keys automatically before writing them to a document: any character outside [a-zA-Z0-9_-] is replaced with _ (a leading $ is valid under the regex above and is left as-is). For example, an AutoRender metadata key of "Alt Text" is stored as "Alt_Text". Sanitization recurses into nested objects and arrays, and two different keys that happen to sanitize to the same string (e.g. "a b" and "a.b") get a numeric suffix so neither value is lost. createAutorenderClient applies this sanitization automatically while mapping API responses. The same logic is also exported separately as sanitizeMetadataKeys, if you want to reuse it elsewhere.

Working with Asset Data

URL usage

Assets picked through autorenderSchemaPlugin's autorender.asset type keep their AutoRender CDN url as plain data — use url (and thumbnail for a poster/preview image) directly:

function CoverImage({coverAsset}: {coverAsset: {url: string; name: string} | undefined}) {
  if (!coverAsset) return null
  return <img src={coverAsset.url} alt={coverAsset.name} />
}

There is no signed-URL or private-file concept in AutoRender — url/thumbnail are always plain public CDN links, safe to use directly in <img>/<video> tags or to pass straight through to your frontend.

GROQ query example

*[_type == "post"]{
  title,
  "cover": coverAsset{
    url,
    thumbnail,
    "alt": metadata.alt_text
  },
  gallery[]{
    fileNo,
    url,
    thumbnail,
    mimeType
  }
}

Advanced Topics

Custom base URL

If your AutoRender workspace is served from a different API host, pass baseUrl:

autorenderSchemaPlugin({
  apiKey: process.env.SANITY_STUDIO_AUTORENDER_API_KEY!,
  baseUrl: 'https://upload.example.com/api/v1',
})

Reusing the API client

createAutorenderClient is exported so you can call the same endpoints this plugin uses from your own custom Studio components (e.g. a custom input or dashboard widget):

import {createAutorenderClient} from '@autorender/sanity'

const client = createAutorenderClient({apiKey: process.env.SANITY_STUDIO_AUTORENDER_API_KEY!})

const {files, meta} = await client.listFiles({folderNo: 'fo_1a2b3c4d', limit: 24})
const {folders} = await client.listFolders({})

const asset = await client.uploadFile({
  file: someFile, // a browser File, or a Blob together with `fileName`
  // fileName: 'hero.jpg', // required when `file` is a plain Blob (it has no name of its own)
  folder: 'marketing', // optional — omit to upload to the root
  tags: ['hero'], // optional
})

Environment variables in Sanity Studio

Studio only exposes environment variables prefixed with SANITY_STUDIO_ to client code (see the Sanity docs on environment variables). Make sure your AutoRender API key is set as SANITY_STUDIO_AUTORENDER_API_KEY (or similar) in your Studio's .env file, and remember the Security section above: this value ends up in the client bundle regardless of the variable name.

License

MIT © Autorender

Documentation

See the full AutoRender documentation for API reference beyond this plugin. For plugin-specific bugs or feature requests, open an issue in this repository's issue tracker.