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 publicKey and multiple 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 Settings

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"
      }
    }
  }
}

JavaScript

{
  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:

media_library:
  name: uploadcare
  config:
    publicKey: YOUR_PUBLIC_KEY

The config object includes the Uploadcare jQuery File Uploader options. However, only publicKey and multiple 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.
• 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.

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 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. For example, /resize/800x600/ will resize images to fit within 800x600 pixels by default. See the Uploadcare documentation for available operations.

TIP

Unlike most of 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/"
      }
    }
  }
}

JavaScript

{
  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. 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/"
      }
    }
  }
}

JavaScript

{
  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. Here is an example of configuring a File field to use the Uploadcare media storage with the legacy option:

media_library:
  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

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

Future Plans

You’ll be able to manage your Uploadcare files directly from the Asset Library in future releases.