--- url: /en/docs/media/cloudinary.md description: >- Integrate Cloudinary as a media storage provider in Sveltia CMS for efficient cloud-based asset management. --- # Cloudinary Integration [Cloudinary](https://cloudinary.com/) 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](https://cloudinary.com/). * Your Cloudinary cloud name and API key. These can be found in your Cloudinary dashboard under the “Account Details” section. ### CSP If your site uses a Content Security Policy (CSP), you may need to update it to allow requests to Cloudinary. See the [CSP documentation](/en/docs/security#setting-up-content-security-policy) 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: ::: code-group ```yaml [YAML] media_libraries: cloudinary: config: cloud_name: YOUR_CLOUD_NAME api_key: YOUR_API_KEY ``` ```toml [TOML] [media_libraries.cloudinary] [media_libraries.cloudinary.config] cloud_name = "YOUR_CLOUD_NAME" api_key = "YOUR_API_KEY" ``` ```json [JSON] { "media_libraries": { "cloudinary": { "config": { "cloud_name": "YOUR_CLOUD_NAME", "api_key": "YOUR_API_KEY" } } } } ``` ```js [JavaScript] { media_libraries: { cloudinary: { config: { cloud_name: "YOUR_CLOUD_NAME", api_key: "YOUR_API_KEY", }, }, }, } ``` ::: ::: details 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](https://cloudinary.com/documentation/media_library_widget#2_set_the_configuration_options). Here are some important notes regarding the configuration options: * The following parameters are required. A [field-level configuration](#field-level-configuration) inherits them from the top-level configuration, so they don’t need to be repeated there: * `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](#image-transformations) section below for more details on defining transformations. * `max_files`: The maximum number of assets that can be selected at once. The field’s [`max`](/en/docs/fields/file#max) option takes precedence if set. Defaults to `20`. * `multiple`: Whether to allow selecting multiple assets. The field’s [`multiple`](/en/docs/fields/file#multiple) option takes precedence. * Some options are not applicable in Sveltia CMS and will be ignored if provided, such as `button_caption`. ::: 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`. ::: warning 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: ::: code-group ```yaml [YAML]{6-7} media_libraries: cloudinary: config: cloud_name: YOUR_CLOUD_NAME api_key: YOUR_API_KEY output_filename_only: false use_transformations: true ``` ```toml [TOML]{2-3} [media_libraries.cloudinary] output_filename_only = false use_transformations = true [media_libraries.cloudinary.config] cloud_name = "YOUR_CLOUD_NAME" api_key = "YOUR_API_KEY" ``` ```json [JSON]{8-9} { "media_libraries": { "cloudinary": { "config": { "cloud_name": "YOUR_CLOUD_NAME", "api_key": "YOUR_API_KEY" }, "output_filename_only": false, "use_transformations": true } } } ``` ```js [JavaScript]{8-9} { 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. The field-level options are merged over the top-level ones, and so is the `config` object, key by key, so a field only needs to set the options it changes: `cloud_name` and `api_key` don’t need to be repeated, and an option such as `use_transformations` is inherited unless the field sets it. An array such as `default_transformations` is replaced, not combined. Setting `cloudinary` to `false` makes Cloudinary unavailable for the field. Here is an example of configuring a File field to use the Cloudinary media storage with custom default transformations and storing only the filename: ::: code-group ```yaml [YAML]{5-11} 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 [TOML]{5-8} [[fields]] name = "cover_image" label = "Cover Image" widget = "image" [fields.media_libraries.cloudinary] output_filename_only = true [fields.media_libraries.cloudinary.config] default_transformations = [[{quality = "auto", fetch_format = "auto"}]] ``` ```json [JSON]{7-21} { "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 [JavaScript]{7-21} { fields: [ { name: "cover_image", label: "Cover Image", widget: "image", media_libraries: { cloudinary: { config: { default_transformations: [ [ { quality: "auto", fetch_format: "auto", }, ], ], }, output_filename_only: true, }, }, }, ], } ``` ::: ::: details 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. The field-level option applies to the provider set with its `name`; without a `name`, it applies to the provider named in the top-level `media_library` option, or to the internal media storage if there is none. Its options are merged over the top-level ones in the same way. Here is an example of configuring a File field to use the Cloudinary media storage with the legacy option: ```yaml media_library: name: cloudinary 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: ::: code-group ```yaml [YAML] media_libraries: cloudinary: config: default_transformations: - - width: 800 height: 600 crop: fill gravity: auto ``` ```toml [TOML] [media_libraries.cloudinary] [media_libraries.cloudinary.config] default_transformations = [[{width = 800, height = 600, crop = "fill", gravity = "auto"}]] ``` ```json [JSON] { "media_libraries": { "cloudinary": { "config": { "default_transformations": [ [ { "width": 800, "height": 600, "crop": "fill", "gravity": "auto" } ] ] } } } } ``` ```js [JavaScript] { media_libraries: { cloudinary: { config: { default_transformations: [ [ { width: 800, height: 600, crop: "fill", gravity: "auto", }, ], ], }, }, }, } ``` ::: See the [Transformation URL API reference](https://cloudinary.com/documentation/transformation_reference) for a complete list of available transformation parameters and their options. ## Accessing the Storage There are two ways to use Cloudinary in Sveltia CMS: ### File and Image Fields When editing content entries, users can use [File](/en/docs/fields/file) and [Image](/en/docs/fields/image) fields to upload and select media on Cloudinary directly within the entry editor. When uploading media, files will be stored in the Cloudinary account, and the CMS 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. ### Asset Library Cloudinary also appears under **External Locations** in the [Asset Library](/en/docs/ui/asset-library). Because the Cloudinary API can’t be called directly from the browser, the CMS opens the Cloudinary Media Library widget instead, where users can browse and manage the files using Cloudinary’s own interface. ## 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](https://cloudinary.com/documentation/javascript_integration) or hardcode [transformed URLs](https://cloudinary.com/documentation/image_transformations) based on your Cloudinary account details. Check the Cloudinary documentation for more information on how to construct URLs with transformations.