--- url: /en/docs/media/uploadcare.md description: >- Integrate Uploadcare as a media storage provider in Sveltia CMS for cloud-based asset management. --- # Uploadcare Integration [Uploadcare](https://uploadcare.com/) 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. ::: warning Breaking change from Netlify/Decap CMS Sveltia CMS uses the Uploadcare API to integrate the service instead of the deprecated [jQuery File Uploader](https://uploadcare.com/docs/uploads/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](#configuration) section for more details. ::: ## Requirements * An Uploadcare account. You can sign up for a free account at [uploadcare.com](https://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](/en/docs/security#setting-up-content-security-policy) 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: ::: code-group ```yaml [YAML] media_libraries: uploadcare: config: publicKey: YOUR_PUBLIC_KEY ``` ```toml [TOML] [media_libraries.uploadcare] [media_libraries.uploadcare.config] publicKey = "YOUR_PUBLIC_KEY" ``` ```json [JSON] { "media_libraries": { "uploadcare": { "config": { "publicKey": "YOUR_PUBLIC_KEY" } } } } ``` ```js [JavaScript] { media_libraries: { uploadcare: { config: { publicKey: "YOUR_PUBLIC_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 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](https://uploadcare.com/docs/uploads/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](#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](https://uploadcare.com/docs/transformations/image/) 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: ::: code-group ```yaml [YAML]{5-7} media_libraries: uploadcare: config: publicKey: YOUR_PUBLIC_KEY settings: autoFilename: true defaultOperations: '/resize/800x600/' ``` ```toml [TOML]{5-7} [media_libraries.uploadcare] [media_libraries.uploadcare.config] publicKey = "YOUR_PUBLIC_KEY" [media_libraries.uploadcare.settings] autoFilename = true defaultOperations = "/resize/800x600/" ``` ```json [JSON]{7-10} { "media_libraries": { "uploadcare": { "config": { "publicKey": "YOUR_PUBLIC_KEY" }, "settings": { "autoFilename": true, "defaultOperations": "/resize/800x600/" } } } } ``` ```js [JavaScript]{7-10} { 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: ::: code-group ```yaml [YAML]{4-7} - name: my_image label: My Image widget: image media_libraries: uploadcare: settings: defaultOperations: '/crop/200x200/' ``` ```toml [TOML]{5-6} [[fields]] name = "my_image" label = "My Image" widget = "image" [fields.media_libraries.uploadcare.settings] defaultOperations = "/crop/200x200/" ``` ```json [JSON]{5-11} { "name": "my_image", "label": "My Image", "widget": "image", "media_libraries": { "uploadcare": { "settings": { "defaultOperations": "/crop/200x200/" } } } } ``` ```js [JavaScript]{5-11} { name: "my_image", label: "My Image", widget: "image", media_libraries: { uploadcare: { settings: { defaultOperations: "/crop/200x200/", }, }, }, } ``` ::: ::: 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 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](https://uploadcare.com/docs/security/secure-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](/en/docs/fields/file) and [Image](/en/docs/fields/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](/en/docs/ui/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.