Sveltia CMS

Appearance

Cloudinary Integration ​

Cloudinary is a leading cloud-based media management service that offers comprehensive solutions for image and video upload, storage, manipulation, and delivery. The Cloudinary integration enables users to efficiently manage media assets within Sveltia CMS by leveraging Cloudinary’s powerful features.

Requirements ​

  • A Cloudinary account. You can sign up for a free account at cloudinary.com.
  • Your Cloudinary cloud name and API key. These can be found in your Cloudinary dashboard under the "Account Details" section.

CSP Settings

If your site uses a Content Security Policy (CSP), You may need to update it to allow requests to Cloudinary. See the CSP documentation for more details.

Configuration ​

Top-Level Configuration ​

To configure the Cloudinary media storage in Sveltia CMS, add the following configuration to the top level of your CMS configuration file:

yaml
media_libraries:
  cloudinary:
    config:
      cloud_name: YOUR_CLOUD_NAME
      api_key: YOUR_API_KEY
toml
[media_libraries.cloudinary]
[media_libraries.cloudinary.config]
cloud_name = "YOUR_CLOUD_NAME"
api_key = "YOUR_API_KEY"
json
{
  "media_libraries": {
    "cloudinary": {
      "config": {
        "cloud_name": "YOUR_CLOUD_NAME",
        "api_key": "YOUR_API_KEY"
      }
    }
  }
}
js
{
  media_libraries: {
    cloudinary: {
      config: {
        cloud_name: "YOUR_CLOUD_NAME",
        api_key: "YOUR_API_KEY",
      },
    },
  },
}
Legacy media_library Option

Sveltia CMS supports the legacy media_library option for backward compatibility with Netlify/Decap CMS, but it is recommended to use the media_libraries option for new configurations. With the legacy option, only a single media storage provider can be configured. Here is an example of configuring Cloudinary using the legacy option:

yaml
media_library:
  name: cloudinary
  config:
    cloud_name: YOUR_CLOUD_NAME
    api_key: YOUR_API_KEY

The config object includes the Cloudinary Media Library widget options. Here are some important notes regarding the configuration options:

  • The following parameters are required:
    • cloud_name: Your Cloudinary cloud name.
    • api_key: Your Cloudinary API key.
  • default_transformations: Transformations to apply to all uploaded images. Only the first transformation in the array will be applied to uploaded media in Sveltia CMS. See the Image transformations section below for more details on defining transformations.
  • Some options are not applicable in Sveltia CMS and will be ignored if provided, such as button_caption and inline_container.

WARNING

Do not write your Cloudinary API secret in the configuration file, as it should be kept confidential and not exposed in client-side code. The API key can be used safely for public operations, and Sveltia CMS does not require the API secret for its functionality.

There are two Sveltia CMS-specific configuration options that can be added alongside the config object. Both are optional:

  • output_filename_only: When set to true, only the filename will be stored in the CMS instead of the full URL. Defaults to false.
  • use_transformations: Whether to use derived transformation URLs for uploaded media. Defaults to true. No effect if output_filename_only is true.

Breaking change from Netlify/Decap CMS

The use_secure_url option has been removed in Sveltia CMS. All URLs generated by the Cloudinary media storage will use HTTPS by default to ensure secure delivery of media assets.

The complete configuration with these additional options looks like this:

yaml
media_libraries:
  cloudinary:
    config:
      cloud_name: YOUR_CLOUD_NAME
      api_key: YOUR_API_KEY
    output_filename_only: false
    use_transformations: true
toml
[media_libraries.cloudinary]
[media_libraries.cloudinary.config]
cloud_name = "YOUR_CLOUD_NAME"
api_key = "YOUR_API_KEY"
output_filename_only = false
use_transformations = true
json
{
  "media_libraries": {
    "cloudinary": {
      "config": {
        "cloud_name": "YOUR_CLOUD_NAME",
        "api_key": "YOUR_API_KEY"
      },
      "output_filename_only": false,
      "use_transformations": true
    }
  }
}
js
{
  media_libraries: {
    cloudinary: {
      config: {
        cloud_name: "YOUR_CLOUD_NAME",
        api_key: "YOUR_API_KEY",
      },
      output_filename_only: false,
      use_transformations: true,
    },
  },
}

Field-Level Configuration ​

The media_libraries configuration can also be specified at the field level for File and Image fields. This allows you to override the top-level configuration for specific fields. Here is an example of configuring a File field to use the Cloudinary media storage with custom default transformations and storing only the filename:

yaml
fields:
  - name: cover_image
    label: Cover Image
    widget: image
    media_libraries:
      cloudinary:
        config:
          default_transformations:
            - - quality: auto
                fetch_format: auto
        output_filename_only: true
toml
[[fields]]
name = "cover_image"
label = "Cover Image"
widget = "image"
[fields.media_libraries.cloudinary]
[fields.media_libraries.cloudinary.config]
output_filename_only = true
default_transformations = [[{quality = "auto", fetch_format = "auto"}]]
json
{
  "fields": [
    {
      "name": "cover_image",
      "label": "Cover Image",
      "widget": "image",
      "media_libraries": {
        "cloudinary": {
          "config": {
            "default_transformations": [
              [
                {
                  "quality": "auto",
                  "fetch_format": "auto"
                }
              ]
            ]
          },
          "output_filename_only": true
        }
      }
    }
  ]
}
js
{
  fields: [
    {
      name: "cover_image",
      label: "Cover Image",
      widget: "image",
      media_libraries: {
        cloudinary: {
          config: {
            default_transformations: [
              [
                {
                  quality: "auto",
                  fetch_format: "auto",
                },
              ],
            ],
          },
          output_filename_only: true,
        },
      },
    },
  ],
}
Legacy media_library Option

As with the top-level configuration, Sveltia CMS supports the legacy media_library option at the field level for backward compatibility. Here is an example of configuring a File field to use the Cloudinary media storage with the legacy option:

yaml
media_library:
  config:
    default_transformations:
      - - quality: auto
          fetch_format: auto
  output_filename_only: true

Image Transformations ​

You can define default image transformations that will be applied to all uploaded images by specifying the default_transformations option in the Cloudinary media storage configuration. This option accepts an array of transformation objects, where each object defines a set of transformation parameters. Only the first transformation in the array will be applied to uploaded media in Sveltia CMS.

For example, to resize all uploaded images to a width of 800 pixels and a height of 600 pixels with cropping and automatic gravity, you can configure the default_transformations option as follows:

yaml
media_libraries:
  cloudinary:
    config:
      default_transformations:
        - - width: 800
            height: 600
            crop: fill
            gravity: auto
toml
[media_libraries.cloudinary]
[media_libraries.cloudinary.config]
default_transformations = [[{width = 800, height = 600, crop = "fill", gravity = "auto"}]]
json
{
  "media_libraries": {
    "cloudinary": {
      "config": {
        "default_transformations": [
          [
            {
              "width": 800,
              "height": 600,
              "crop": "fill",
              "gravity": "auto"
            }
          ]
        ]
      }
    }
  }
}
js
{
  media_libraries: {
    cloudinary: {
      config: {
        default_transformations: [
          [
            {
              width: 800,
              height: 600,
              crop: "fill",
              gravity: "auto",
            },
          ],
        ],
      },
    },
  },
}

See the Transformation URL API reference for a complete list of available transformation parameters and their options.

Accessing the Storage ​

The Cloudinary media storage can be accessed through the File and Image fields in Sveltia CMS. When uploading media, files will be stored in your Cloudinary account, and you can take advantage of Cloudinary’s transformation capabilities directly from the CMS. You can also select existing media from your Cloudinary storage.

Users are required to authenticate with Cloudinary using their username and password when accessing the media storage provider. The authentication process is handled automatically by Sveltia CMS using the provided API key.

Using Transformations in Page Templates ​

When the output_filename_only option is set to true, only the filename is stored in your entry data files. To generate the full URL with transformations in your site’s page templates, you can use the JavaScript SDK or hardcode transformed URLs based on your Cloudinary account details. Check the Cloudinary documentation for more information on how to construct URLs with transformations.

Released under the MIT License.

Copyright © 2026 Kohei Yoshino