Skip to content

Official plugin for integrating Sanity Studio with Cloudinary

License

Notifications You must be signed in to change notification settings

sanity-io/sanity-plugin-cloudinary

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

84 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

sanity-plugin-cloudinary

This is a Sanity Studio v3 plugin. This combines the sanity-plugin-cloudinary AND sanity-plugin-asset-source-cloudinary plugins previously for V2, into a single plugin for V3.

For the v2 versions of these, please refer to the v2-branch for sanity-plugin-cloudinary and sanity-plugin-asset-source-cloudinary.

Installation

npm install --save sanity-plugin-cloudinary

or

yarn add sanity-plugin-cloudinary

Usage

There are two 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

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 {defineConfg} from 'sanity'
import {cloudinaryAssetSourcePlugin} from 'sanity-plugin-cloudinary'

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

Fine tune image sources

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

export default defineConfg({
  /*...*/
  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 clooudinary as an asset source
          return [cloudinaryImageSource]
        }
        // dont add cloudnary as an asset sources
        return previousAssetSources
      },
    },
  },
})

Cloudinary assets

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

export default defineConfg({
  /*...*/
  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",
    }

Config

Includes easy configuration of your cloudname and api key, stored safely in your dataset as a private document. Screen Shot 2021-03-22 at 10 55 56 PM

Uses Cloudinary media library for selecting assets and transformations

Screen Shot 2021-03-22 at 10 33 58 PM

Screen Shot 2021-03-22 at 10 07 52 PM

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" }]
}

image

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

Screen Shot 2021-03-22 at 10 37 27 PM

{
    "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

Screen Shot 2021-03-22 at 10 42 04 PM

{
  "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.

Develop & test

This plugin uses @sanity/plugin-kit with default configuration for build & watch scripts.

See Testing a plugin in Sanity Studio on how to run this plugin with hotreload in the studio.

Release new version

Run "CI & Release" workflow. Make sure to select the main branch and check "Release new version".

Semantic release will only release on configured branches, so it is safe to run release on any branch.