Sveltia CMS

Uploadcare Integration ​

Uploadcare is a powerful media management service that provides robust file uploading, storage, and delivery capabilities. The Uploadcare integration allows users to seamlessly upload and manage media files within Sveltia CMS using Uploadcare’s infrastructure.

Breaking change from Netlify/Decap CMS

Sveltia CMS uses the Uploadcare API to integrate the service instead of the deprecated jQuery File Uploader. This change resolves several issues present in Netlify/Decap CMS, including the ability to select existing files from Uploadcare storage and support for signed uploads.

However, some features available in the previous integration, such as image editing, camera capture and external sources, are not currently supported in Sveltia CMS. We’ll consider adding these features in future releases.

Also, in the config object, only the publicKey, multiple and cdnBase options are supported at this time. Please refer to the Configuration section for more details.

Requirements ​

  • An Uploadcare account. You can sign up for a free account at uploadcare.com.
  • Your Uploadcare public and secret API keys. These can be found in your Uploadcare dashboard under the API Keys section. The public key is required for configuration, while the secret key will be manually entered by users in the CMS UI when they use the storage for the first time.

CSP ​

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

Configuration ​

Top-Level Configuration ​

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

yaml
media_libraries:
  uploadcare:
    config:
      publicKey: YOUR_PUBLIC_KEY
toml
[media_libraries.uploadcare]
[media_libraries.uploadcare.config]
publicKey = "YOUR_PUBLIC_KEY"
json
{
  "media_libraries": {
    "uploadcare": {
      "config": {
        "publicKey": "YOUR_PUBLIC_KEY"
      }
    }
  }
}
js
{
  media_libraries: {
    uploadcare: {
      config: {
        publicKey: "YOUR_PUBLIC_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 Uploadcare using the legacy option:

yaml
media_library:
  name: uploadcare
  config:
    publicKey: YOUR_PUBLIC_KEY

The config object includes the Uploadcare jQuery File Uploader options. However, only publicKey, multiple and cdnBase are supported in Sveltia CMS at this time, as we don’t actually use the pre-built uploader.

  • publicKey (string, required): Your Uploadcare public API key. A field-level configuration inherits it from the top-level configuration, so it doesn’t need to be repeated there.
  • multiple (boolean, optional): If set to true, allows selecting multiple files at once. Default is false. This option is available for backward compatibility; use the multiple option in the File or Image field configuration instead, which takes precedence over this option.
  • cdnBase (string, optional): The CDN origin used in output URLs, such as a custom CDN domain. Default: the origin of the file URL returned by Uploadcare, typically https://ucarecdn.com.

WARNING

Do not write your Uploadcare secret key in the configuration file, as it should be kept confidential and not exposed in client-side code. Users will be prompted to enter the secret key when they use the storage for the first time, which will be stored securely in the browser’s local storage.

There are two Sveltia CMS-specific configuration options you can include under the settings object:

  • autoFilename (boolean): If set to true, a filename will be added at the end of the file URL when selecting files, e.g. https://ucarecdn.com/UUID/filename.jpg. Default is false.
  • defaultOperations (string): A string of default image transformation operations to be applied to images when they are selected. It must start with a slash, and it’s not added to the URLs of non-image files. For example, /resize/800x600/ will resize images to fit within 800x600 pixels by default. See the Uploadcare documentation for available operations.

TIP

Unlike most other config options, the setting keys are camelCased. (Not auto_filename but autoFilename.)

The complete configuration with these additional options looks like this:

yaml
media_libraries:
  uploadcare:
    config:
      publicKey: YOUR_PUBLIC_KEY
    settings:
      autoFilename: true
      defaultOperations: '/resize/800x600/'
toml
[media_libraries.uploadcare]
[media_libraries.uploadcare.config]
publicKey = "YOUR_PUBLIC_KEY"

[media_libraries.uploadcare.settings]
autoFilename = true
defaultOperations = "/resize/800x600/"
json
{
  "media_libraries": {
    "uploadcare": {
      "config": {
        "publicKey": "YOUR_PUBLIC_KEY"
      },
      "settings": {
        "autoFilename": true,
        "defaultOperations": "/resize/800x600/"
      }
    }
  }
}
js
{
  media_libraries: {
    uploadcare: {
      config: {
        publicKey: "YOUR_PUBLIC_KEY",
      },
      settings: {
        autoFilename: true,
        defaultOperations: "/resize/800x600/",
      },
    },
  },
}

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 are the config and settings objects, key by key, so a field only needs to set the options it changes: publicKey doesn’t need to be repeated, and a setting such as autoFilename is inherited unless the field sets it. Setting uploadcare to false makes Uploadcare unavailable for the field. Here is an example of configuring a File field to use the Uploadcare media storage with custom default operations:

yaml
- name: my_image
  label: My Image
  widget: image
  media_libraries:
    uploadcare:
      settings:
        defaultOperations: '/crop/200x200/'
toml
[[fields]]
name = "my_image"
label = "My Image"
widget = "image"
[fields.media_libraries.uploadcare.settings]
defaultOperations = "/crop/200x200/"
json
{
  "name": "my_image",
  "label": "My Image",
  "widget": "image",
  "media_libraries": {
    "uploadcare": {
      "settings": {
        "defaultOperations": "/crop/200x200/"
      }
    }
  }
}
js
{
  name: "my_image",
  label: "My Image",
  widget: "image",
  media_libraries: {
    uploadcare: {
      settings: {
        defaultOperations: "/crop/200x200/",
      },
    },
  },
}
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 Uploadcare media storage with the legacy option:

yaml
media_library:
  name: uploadcare
  settings:
    defaultOperations: '/crop/200x200/'

Signed Uploads ​

To enhance security, Uploadcare supports signed uploads, which require a secret key to generate upload signatures. Sveltia CMS prompts users to enter the secret key when they use the Uploadcare storage for the first time, and the key is securely stored in the browser’s local storage. After that, all uploads will be automatically signed using the provided secret key. No configuration is needed in the CMS config file.

Accessing the Storage ​

There are two ways to use Uploadcare in Sveltia CMS:

File and Image Fields ​

When editing content entries, users can use File and Image fields to upload and select media on Uploadcare directly within the entry editor. When uploading media, files will be stored in the Uploadcare account, and the CMS can take advantage of Uploadcare’s transformation capabilities directly from the CMS. You can also select existing media from your Uploadcare storage.

Asset Library ​

Uploadcare also appears under External Locations in the Asset Library, where users can browse, search, sort and filter the files, and upload, download or delete them without leaving the CMS. Files can’t be renamed or replaced, because the Uploadcare REST API doesn’t support renaming, and a re-uploaded file gets a new UUID and therefore a new URL.

Copyright © 2026 Kohei Yoshino