sanity-plugin-cloudinary

Installation

pnpm add sanity-plugin-cloudinary

or

npm install --save sanity-plugin-cloudinary

or

yarn add sanity-plugin-cloudinary

Usage

There are three plugins in this package:

• cloudinaryAssetSourcePlugin - use this if you intend to serve Cloudinary images from the Sanity CDN
• cloudinarySchemaPlugin - use this if you intend to serve Cloudinary images from the Cloudinary CDN
• cloudinaryReferencePlugin - use this if you want to reference Cloudinary assets as document references

Also see notes below on how Cloudinary config should be provided.

Cloudinary as a Sanity asset

Add Cloudinary as an asset source to all images

import {defineConfig} from 'sanity'
import {cloudinaryAssetSourcePlugin} from 'sanity-plugin-cloudinary'

export default defineConfig({
  /*...*/
  plugins: [cloudinaryAssetSourcePlugin()],
})

Fine tune image sources

import {defineConfig} from 'sanity'
import {cloudinaryImageSource} from 'sanity-plugin-cloudinary'

export default defineConfig({
  /*...*/
  form: {
    image: {
      assetSources: (previousAssetSources, context) => {
        if (context.currentUser?.roles.includes('cloudinaryAccess')) {
          // appends cloudinary as an asset source
          return [...previousAssetSources, cloudinaryImageSource]
        }
        if (context.currentUser?.roles.includes('onlyCloudinaryAccess')) {
          // only use cloudinary as an asset source
          return [cloudinaryImageSource]
        }
        // don't add cloudinary as an asset source
        return previousAssetSources
      },
    },
  },
})

Cloudinary assets

import {defineConfig} from 'sanity'
import {cloudinarySchemaPlugin} from 'sanity-plugin-cloudinary'

export default defineConfig({
  /*...*/
  plugins: [cloudinarySchemaPlugin()],
})

Now you can declare a field to be cloudinary.asset in your schema

    {
      type: "cloudinary.asset",
      name: "image",
      description: "This asset is served from Cloudinary",
    }

Cloudinary Reference Assets

This plugin mode allows you to store Cloudinary assets as document references, which can be useful for reusing the same asset across multiple documents.

import {defineConfig} from 'sanity'
import {cloudinaryReferencePlugin} from 'sanity-plugin-cloudinary'

export default defineConfig({
  /*...*/
  plugins: [cloudinaryReferencePlugin()],
})

Now you can declare a field to be a reference to a Cloudinary asset:

{
  type: "cloudinaryAssetReference",
  name: "image",
  description: "This is a reference to a Cloudinary asset document",
}

The plugin creates and maintains document references automatically. When you select an asset through the Cloudinary Media Library, it will:

1. Create a cloudinaryAssetDocument if the asset doesn't exist yet in your dataset
2. Update the asset if it already exists
3. Store a reference to the asset document in your current document

This approach is particularly useful for:

• Reusing the same assets across multiple documents
• Updating assets in one place and having the changes reflected everywhere
• Managing assets separately from the content that uses them

Config

Includes easy configuration of your cloudname and api key, stored safely in your dataset as a private document.

Uses Cloudinary media library for selecting assets and transformations

In arrays

If you use this type in an array, you will have additional array functions for adding multiple assets at once, and for configuring the connection to Cloudinary.

{
  type: "array",
  name: "cloudinaryList",
  description: "This asset is served from Cloudinary",
  of: [{ type: "cloudinary.asset" }]
}

Content

Here is an example of which data is stored on your document after selecting an asset.

{
  "public_id": "29b4a88182b4cb50330011d23a29bcb371bd5886-2400x1344_lzcx7x",
  "resource_type": "image",
  "type": "upload",
  "format": "jpg",
  "version": 1616474653,
  "url": "http://res.cloudinary.com/dzwiku20l/image/upload/v1616474653/29b4a88182b4cb50330011d23a29bcb371bd5886-2400x1344_lzcx7x.jpg",
  "secure_url": "https://res.cloudinary.com/dzwiku20l/image/upload/v1616474653/29b4a88182b4cb50330011d23a29bcb371bd5886-2400x1344_lzcx7x.jpg",
  "width": 2400,
  "height": 1344,
  "bytes": 547710,
  "duration": null,
  "tags": [],
  "context": {
    "custom": {
      "alt": "alternative text for image"
    }
  },
  "created_at": "2021-03-23T04:44:13Z",
  "access_mode": "public",
  "_version": 1,
  "_type": "cloudinary.asset"
}

Note: The _version in the data here refers to the schema version of this plugin, should the way it stores the data from Cloudinary change in the future.

Transformations

You can create a transformation when selecting the asset, and this information is previewed and stored

{
  "public_id": "29b4a88182b4cb50330011d23a29bcb371bd5886-2400x1344_lzcx7x",
  "resource_type": "image",
  "type": "upload",
  "format": "jpg",
  "version": 1616474653,
  "url": "http://res.cloudinary.com/dzwiku20l/image/upload/v1616474653/29b4a88182b4cb50330011d23a29bcb371bd5886-2400x1344_lzcx7x.jpg",
  "secure_url": "https://res.cloudinary.com/dzwiku20l/image/upload/v1616474653/29b4a88182b4cb50330011d23a29bcb371bd5886-2400x1344_lzcx7x.jpg",
  "width": 2400,
  "height": 1344,
  "bytes": 547710,
  "duration": null,
  "tags": null,
  "context": {
    "custom": {
      "alt": "alternative text for image"
    }
  },
  "created_at": "2021-03-23T04:44:13Z",
  "derived": [
    {
      "url": "http://res.cloudinary.com/dzwiku20l/image/upload/a_45/v1616474653/29b4a88182b4cb50330011d23a29bcb371bd5886-2400x1344_lzcx7x.jpg",
      "secure_url": "https://res.cloudinary.com/dzwiku20l/image/upload/a_45/v1616474653/29b4a88182b4cb50330011d23a29bcb371bd5886-2400x1344_lzcx7x.jpg",
      "raw_transformation": "a_45"
    }
  ],
  "access_mode": "public",
  "_version": 1,
  "_type": "cloudinary.asset"
}

Video

Video assets gets a video player preview in the Studio

{
  "public_id": "Make_it_happen_together.-WWa8qtgD0f0_nucpr9",
  "resource_type": "video",
  "type": "upload",
  "format": "mp4",
  "version": 1616474928,
  "url": "http://res.cloudinary.com/dzwiku20l/video/upload/v1616474928/Make_it_happen_together.-WWa8qtgD0f0_nucpr9.mp4",
  "secure_url": "https://res.cloudinary.com/dzwiku20l/video/upload/v1616474928/Make_it_happen_together.-WWa8qtgD0f0_nucpr9.mp4",
  "width": 1920,
  "height": 1080,
  "bytes": 3937717,
  "duration": 24.1,
  "tags": [],
  "metadata": [],
  "created_at": "2021-03-23T04:48:48Z",
  "access_mode": "public",
  "_version": 1,
  "_type": "cloudinary.asset"
}

License

MIT-licensed. See LICENSE.