Note: Cloudinary integration is only available with our paid plans. However, you can evaluate it in local development mode. Cloudinary has a free tier.

Cloudinary is the leading platform for managing, transforming, optimizing, and delivering media assets.

Cloudinary integrates both with leading CMS platforms supported by Stackbit (e.g. Contentful, Sanity, etc.) and with Stackbit itself. Meaning that any field that is configured as Cloudinary-managed in the CMS is automatically recognized by Stackbit.

The additional benefit which Stackbit provides over using just a CMS is editing images in context. When picking and manipulating images, you immediately see the effect of your changes on the page.

Moreover, Cloudinary-specific functionality such as AI-based image cropping or various image enhancements can be brought directly into the content editors' hands within the visual editor, by modeling your content and components to provide whatever degree of control is desired.

Setting up

Get Your CMS Configured

First, if you're using a headless CMS, make sure you've installed the Cloudinary app/plug-in for that CMS. Then, any fields in the content model that are to point to Cloudinary images should be configured as such in the CMS.

This stage is CMS-specific. For example, in Contentful you'd need to create a JSON-type field and set its appearance to Cloudinary:

Cloudinary-managed field in Contentful

Configure & Use in Your Stackbit Project

Open the Project Settings dialog (via the Gear icon at the top-left of the visual editor) and switch to the Integrations tab to set up the integration. You will need your cloud name in Cloudinary (i.e. your account name) and your API key.

Configure Cloudinary in Stackbit

After this one-time configuration for your project, the Cloudinary widget will appear for any relevant field:

Cloudinary Widget in Stackbit

  • With a headless CMS, any field which is to be managed with Cloudinary must be configured as such. Default image fields are still managed by the CMS, and edited in Stackbit via our native image picker.
  • If your content is stored in Git rather than a headless CMS, you can use either Cloudinary or Stackbit's native image picker. Your content model can specify for each image field whether it is to be managed only through Cloudinary, or maintain compatibility with Git-based assets as well (see notes below).

Working with Cloudinary as a Developer

When a user selects an image in the Cloudinary widget, the widget returns a JSON object with full image metadata. This object is stored back in the field. The object format is documented here.

All CMSs supporting Cloudinary use essentially the same format (e.g. see Sanity's docs).

The returned object usually contains an array of assets, even though in Stackbit you can only select a single image for a single field.

For each asset, a link to the original image is returned with an HTTPS URL in the secure_url attribute, and if the user has applied any transformations, an array of transformed images is returned under the derived attribute. Make sure you know the JSON format and which attributes you need to use from it.

Having the image metadata is useful for multiple reasons, e.g.

  • Knowing the width & height of images you can optimize your markup to reduce Layout Shift and improve your site's performance score.

  • Content editors can associate custom data tags with an image, and as a developer you'll have these available wherever the image is used.

Check out the example project on GitHub.

Image metadata with Git CMS

By default, when using our built-in Git-based CMS rather than connecting to a headless CMS, image fields only hold a single string: the URL to the image.

This allows content editors to freely toggle between selecting images from Cloudinary and choosing from image files in the repository. However, the full JSON image metadata is not stored, and as a developer you only get the secure_url of that asset.

To have the full metadata object stored, add the property source: cloudinary to the definition of any relevant image field. For fields configured in this way, only Cloudinary images can be selected.

Ensuring Great Image Quality

Visitors to your site can enjoy both great image quality AND small file sizes. This is no myth - and also not very hard to achieve when using Cloudinary.

Follow this recipe:

Upload images to Cloudinary in their original format and resolution. If you apply any resizing or conversions before uploading, you're downgrading the image quality from the get-go. Instead, you should use the platform to perform resizing and format conversion.

Ensure that automatic format selection a.k.a f_auto is applied to the image URL. JPEG and PNG are tried and true formats, but they're far from optimal for either lossy or lossless images. All major browsers nowadays support at least one of the more modern image formats such as WebP and AVIF, but developers and content editors usually shy away from using them. With f_auto, Cloudinary will select the best format for the browser at serving time, and you'll see significantly lower file sizes. Seriously.

Sizing images: properly sizing images for a user's device is unfortunately not well understood by many. It definitely pays off to read up about it (for example here).

If you're spending your workday working with a standard-definition monitor, don't assume that's how everyone else views your site. High definition displays (a.k.a "2X", or "Retina" in Apple-speak) are pretty common in laptops and mobile devices, and gradually getting to the desktop with 4k displays. Use the srcset and sizes HTML attributes to provide multiple differently-sized URLs, at least for the images you care about the most (e.g. in the site's hero banner).

If your server returns HTML with these attributes baked in, the browser will be able to select the proper size and start downloading the image early in the process. Using a web framework such as Next.js coupled with server-side or static rendering, visitors hitting your site will receive a pre-rendered HTML document rather than having to wait for Javascript code to be run (as is the case with vanilla React and other SPA's).

Master this once and you can develop a few helper functions which will ease the process of adopting these optimizations everywhere in your code.

Limitations

  1. Stackbit supports only a single image per field. You can use list fields to hold multiple images.
  2. When using a headless CMS, a given field is either configured as a "native" image field or as a Cloudinary-managed field. The content editor cannot switch between using Cloudinary or not for a specific instance of content.
  3. When using file content from Git, image fields by default either hold a link to an image file in the project's repository or a link to a Cloudinary image, but without storing the full image metadata from Cloudinary. To change that, see above.