docs.stackbit.com Open in urlscan Pro
34.141.11.154  Public Scan

Form analysis
0 forms found in the DOM

Text Content

This app works best with JavaScript enabled.
DocumentationShow Menu
 * Documentation
 * Blog
 * Sign In
 * Get Started

Navigate Docs
 * HomeSubmenu⌘K
   Getting StartedSubmenu
   * Next.js + MarkdownSubmenu
     * Stackbit Setup
     * Content Modeling
     * Inline Editing
     * Component Presets
   * Next.js + ContentfulSubmenu
     * Stackbit Setup
     * Basic Editing
     * Inline Editing
     * Component Presets
   Add New Project
   For DevelopersFeaturesSubmenu
   * Content Editor
   * Create from GitHub
   * Form Submissions
   * Global Styles
   * Local Development
   * Publishing
   GuidesReferenceSubmenu
   * @stackbit/cli
   * create-stackbit-app
   * stackbit.yaml
   * .stackbit/modelsSubmenu
     * Model Properties
     * Field Properties
     * Field & Component Styles
   * data-sb-*Submenu
     * data-sb-object-id
     * data-sb-field-path
     * @stackbit/annotations
   * .stackbit/presets
   * Automatic Content Reload
   ConceptsSubmenu
   * How Stackbit Works
   * Structured Content
   * Content Presets
   * Managed Hosting
   IntegrationsSubmenu
   * Connecting Accounts
   * Hosting ProvidersSubmenu
     * Netlify
     * Vercel
     * Cloudflare Pages
   * Web FrameworksSubmenu
     * Next.js
     * Angular
     * SvelteKit
     * Nuxt 3 (Early Preview)
     * Hydrogen
     * Bring Your Own
   * Contentful
   * Cloudinary
   For EditorsEditor GuidesSubmenu
   * Overview
   * Publishing Changes
   * Collaboration: Previewing & Sharing
   * Building Landing Pages
   * Save as Preset
   SupportTroubleshooting

IntegrationsCloudinary


USE IMAGES FROM CLOUDINARY

Updated: Aug 02, 2022

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:




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.



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



 * 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.




TABLE OF CONTENTS

 * Setting up
   * Get Your CMS Configured
   * Configure & Use in Your Stackbit Project
 * Working with Cloudinary as a Developer
   * Image metadata with Git CMS
 * Ensuring Great Image Quality
 * Limitations

Copyright © 2022 Stackbit. Made with Stackbit

TermsPrivacyLicense

GitHubTwitter