Skip to content

Media Storage ​

Sveltia CMS supports multiple media storage providers for managing media assets such as images and files. You can choose from the built-in internal media storage that saves files directly in your Git repository, or integrate with popular cloud-based media storage services for enhanced capabilities.

Note for Netlify/Decap CMS users

In Sveltia CMS, the term “media storage provider” is used instead of “media library” to avoid confusion with Sveltia CMS’s Asset Library feature that lets users manage media assets from multiple sources in one place. There is no change in functionality or configuration; it’s simply a terminology update.

Internal Storage ​

The internal media storage allows you to store media files directly in your Git repository along with your content files. It supports various configuration options for organizing and managing media files effectively.

External Storage ​

Sveltia CMS supports integrations with popular cloud-based media storage providers for enhanced capabilities such as automatic image transformations, CDN delivery and more. Sveltia CMS currently supports the following external media storage providers:

Unlike backends, you can use multiple storage providers simultaneously in Sveltia CMS. Each media storage provider integration includes its own configuration instructions.

Breaking changes from Netlify/Decap CMS

Sveltia CMS does not support the deprecated Netlify Large Media service. If you’re using it with Netlify/Decap CMS, you will need to migrate your assets to one of the supported providers mentioned above.

Also, Sveltia CMS does not support the undocumented custom media storage provider API. The CMS.registerMediaLibrary method is a no-op in Sveltia CMS. We may add support for custom storage providers in future releases, though compatibility with existing Netlify/Decap CMS custom media libraries is not guaranteed.

Future Plans

More integration options may be added in the future.

Configuration ​

Relevant configuration options can be set in the media_folder, public_folder and media_libraries options of your CMS configuration file. The media_library option from Netlify/Decap CMS is also supported for backward compatibility.

The following example demonstrates how to configure multiple providers in Sveltia CMS:

yaml
# Default media storage paths
media_folder: /public/media
public_folder: /media

# Media provider features
media_libraries:
  default:
    config:
      max_file_size: 1024000 # default: Infinity
      slugify_filename: true # default: false
      # transformations: # See the documentation for details
  cloudinary:
    config:
      cloud_name: YOUR_CLOUD_NAME
      api_key: YOUR_API_KEY
    output_filename_only: true
  uploadcare:
    config:
      publicKey: YOUR_PUBLIC_KEY
    settings:
      autoFilename: true
      defaultOperations: '/resize/800x600/'
toml
# Default media storage paths
media_folder = "/public/media"
public_folder = "/media"

# Media provider features
[media_libraries.default]
[media_libraries.default.config]
max_file_size = 1024000 # default: Infinity
slugify_filename = true # default: false
# transformations: See the documentation for details

[media_libraries.cloudinary]
output_filename_only = true

[media_libraries.cloudinary.config]
cloud_name = "YOUR_CLOUD_NAME"
api_key = "YOUR_API_KEY"

[media_libraries.uploadcare]
[media_libraries.uploadcare.config]
publicKey = "YOUR_PUBLIC_KEY"

[media_libraries.uploadcare.settings]
autoFilename = true
defaultOperations = "/resize/800x600/"
json
{
  "media_folder": "/public/media",
  "public_folder": "/media",
  "media_libraries": {
    "default": {
      "config": {
        "max_file_size": 1024000,
        "slugify_filename": true
      }
    },
    "cloudinary": {
      "config": {
        "cloud_name": "YOUR_CLOUD_NAME",
        "api_key": "YOUR_API_KEY"
      },
      "output_filename_only": true
    },
    "uploadcare": {
      "config": {
        "publicKey": "YOUR_PUBLIC_KEY"
      },
      "settings": {
        "autoFilename": true,
        "defaultOperations": "/resize/800x600/"
      }
    }
  }
}
js
{
  media_folder: "/public/media",
  public_folder: "/media",
  media_libraries: {
    default: {
      config: {
        max_file_size: 1024000,
        slugify_filename: true,
      },
    },
    cloudinary: {
      config: {
        cloud_name: "YOUR_CLOUD_NAME",
        api_key: "YOUR_API_KEY",
      },
      output_filename_only: true,
    },
    uploadcare: {
      config: {
        publicKey: "YOUR_PUBLIC_KEY",
      },
      settings: {
        autoFilename: true,
        defaultOperations: "/resize/800x600/",
      },
    },
  },
}

See the individual media storage provider documentation for specific configuration options and details.

The media_libraries option can also be defined for a File or Image field. The options of each provider are merged over the same provider’s top-level options. This includes the internal media storage (default), the stock photo providers (stock_assets) and the shared all options. A field therefore only needs to set the options it changes, or false to make the provider unavailable for the field. Providers not defined at the field level fall back to the top-level configuration.

The options are merged as follows:

  • A nested object such as config is merged key by key, but only one level deep.
  • Other values, including arrays such as the providers list, are replaced.
  • The all options are merged shallowly, too.

As a result, a field-level transformations map, under all or default.config, replaces the top-level one as a whole rather than being merged format by format.

Legacy media_library Option

Sveltia CMS supports the legacy media_library option for backward compatibility with Netlify/Decap CMS. For new configurations, use the media_libraries option instead.

With the legacy option, only a single media storage provider can be configured. If both options define the same provider, media_libraries takes precedence. Netlify/Decap CMS requires the name, but Sveltia CMS applies a legacy option without a name to the internal media storage.

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
  output_filename_only: true

Storage Opened First ​

The Select File and Select Image dialogs open on the first repository folder, such as Global Assets, even when an external storage provider is configured. If your editors usually upload files to an external provider, set that provider’s default option to true. The dialogs then open on it, so files don’t end up in your repository by mistake.

yaml
media_libraries:
  aws_s3:
    access_key_id: YOUR_ACCESS_KEY_ID
    bucket: my-website-assets
    region: us-east-1
    default: true
toml
[media_libraries.aws_s3]
access_key_id = "YOUR_ACCESS_KEY_ID"
bucket = "my-website-assets"
region = "us-east-1"
default = true
json
{
  "media_libraries": {
    "aws_s3": {
      "access_key_id": "YOUR_ACCESS_KEY_ID",
      "bucket": "my-website-assets",
      "region": "us-east-1",
      "default": true
    }
  }
}
js
{
  media_libraries: {
    aws_s3: {
      access_key_id: 'YOUR_ACCESS_KEY_ID',
      bucket: 'my-website-assets',
      region: 'us-east-1',
      default: true,
    },
  },
}

The option is available for Amazon S3 and the S3-compatible providers, Azure Blob Storage, Cloudinary, Uploadcare and the internal media storage (default). Editors can still pick any other location in the dialog.

The option can also be set in the media_libraries option of a File or Image field:

  • Field over site: A provider marked in the field takes precedence over one marked at the top level.
  • Clearing the mark: Set default: false on a provider in the field to clear its top-level mark.
  • Back to the repository: Set default: true on the internal media storage, i.e. media_libraries.default.default, to make a field open the repository folder again.
  • Unavailable providers: A marked provider that isn’t offered is skipped. For example, it may be disabled for the field, or the field may select a folder, which can only be picked from the repository. The next marked provider opens instead, or the first repository folder if there’s none.
  • Several marks: Mark only one provider. If more are marked, the first one offered is used, in the order they’re listed.

The option only applies to the dialogs. The Asset Library still opens on All Assets, and files dropped directly on a File or Image field aren’t affected. The legacy media_library option doesn’t support it.

Additional Features ​

A couple of additional features are available to enhance media management. These features apply to the internal media storage and to files uploaded to external storage providers, except for Cloudinary, which uses its own Media Library widget.

The configuration goes in the media_libraries option, under the all key. For the internal media storage, these options can be overridden by the same options in media_libraries.default.config. A File or Image field can also have its own media_libraries.all options, which are merged into the global ones.

For the internal media storage, the options are applied in this order, each overriding the previous ones:

  1. the top-level all
  2. the top-level default.config
  3. the field-level all
  4. the field-level default.config

So a field-level all option takes precedence over the same option in the top-level default.config.

Image Optimization ​

You can enable automatic image optimization by configuring the transformations option in the media_libraries configuration. This allows you to specify how uploaded images should be processed and optimized before being stored.

For example, you can convert raster images to WebP format, resize them to a maximum dimension and optimize SVG files.

yaml
media_libraries:
  all:
    transformations:
      raster_image: # original format
        format: webp # new format, only `webp` is supported
        quality: 85 # integer between 0 and 100, default: 85
        width: 2048 # default: original size
        height: 2048 # default: original size
      svg:
        optimize: true # default: false
toml
[media_libraries.all]
[media_libraries.all.transformations]
[media_libraries.all.transformations.raster_image]
format = "webp"
quality = 85
width = 2048
height = 2048
[media_libraries.all.transformations.svg]
optimize = true
json
{
  "media_libraries": {
    "all": {
      "transformations": {
        "raster_image": {
          "format": "webp",
          "quality": 85,
          "width": 2048,
          "height": 2048
        },
        "svg": {
          "optimize": true
        }
      }
    }
  }
}
js
{
  media_libraries: {
    all: {
      transformations: {
        raster_image: {
          format: "webp",
          quality: 85,
          width: 2048,
          height: 2048,
        },
        svg: {
          optimize: true,
        },
      },
    },
  },
}

Then, whenever a user selects images to upload, those images are automatically optimized, all within the browser. Raster images such as JPEG and PNG are converted to WebP format and resized if necessary. If the optimize option is true, SVG images are minified using the SVGO library, which removes unnecessary data such as comments and editor metadata.

In case you’re not aware, WebP offers better compression than conventional formats and is now widely supported across major browsers. So there is no reason not to use WebP on the web.

  • raster_image applies to any supported raster image format: avif, gif, heic, jpeg, png and webp. If you like, you can use a specific format as key instead of raster_image, or in addition to it to give one format different options.
  • The width and height options are the maximum width and height in pixels, respectively. If an image is larger than the specified dimension, it will be scaled down, keeping the aspect ratio. Smaller images will not be scaled up.
  • If the browser can’t encode WebP, the image may be saved in PNG format instead, with the file extension changed accordingly.
  • File processing is a bit slow on Safari because native WebP encoding is not supported and the jSquash library is used instead.
  • AVIF conversion is not supported because no browser has native AVIF encoding support (Chromium won’t fix it) and the third-party library (and AVIF encoding in general) is very slow.
  • This feature is not intended for creating image variants in different formats and sizes. It should be done with a framework during the build process. Popular frameworks like Astro, Eleventy, Hugo, Next.js and SvelteKit have built-in image processing capabilities.
  • Animated GIF, WebP and PNG images are uploaded as they are, without conversion or resizing, because only their first frame would be kept otherwise.
  • Exif metadata is stripped from raster images to reduce file size. If you want to keep it, upload the original files without optimization and use the framework to process them later.

HEIC Photos ​

Photos taken on an iPhone or a recent Android phone are often saved in HEIC (HEIF) format, which only Safari can display. When the raster_image or heic transformation is configured, HEIC photos are accepted by Image fields and the Asset Library, and converted on upload like any other raster image:

  • The photo is decoded within the browser using libheif compiled to WebAssembly. The decoder, @discourse/heic, is a build from the jSquash project and is downloaded from UNPKG on first use (about 300 KB). Decoding runs in a Web Worker so the interface stays responsive. It takes about half a second for a 12-megapixel photo on a recent laptop. Photos are decoded one at a time. Safari decodes HEIC natively, so nothing is downloaded there.
  • A HEIC photo saved with a .jpg extension is detected by its content and converted as well. This happens when a photo is renamed rather than converted. Without HEIC conversion, such a file is rejected as unusable, because browsers other than Safari can’t display it.
  • A HEIC photo that can’t be decoded is rejected rather than uploaded as is.
  • Use the heic key to give HEIC photos their own options, such as a smaller maximum dimension, since they’re typically full-resolution camera shots.
  • If your site adopts a Content Security Policy, add blob: to the worker-src directive so that the decoder can run in a Web Worker. The decoder falls back to the main thread otherwise, which freezes the interface during decoding.

Without HEIC conversion, Image fields don’t offer HEIC photos in the file picker, while .heic files uploaded to the Asset Library are stored as they are.

Thumbnails of HEIC photos already in the repository are generated with the same decoder regardless of the configuration.

Future Plans

We may add more transformation options in the future.

File Size Limits ​

To restrict the maximum file size for uploads, set the max_file_size option (in bytes) in the media_libraries configuration, either at the top level or in a File/Image field. The default value is Infinity, meaning there is no limit. The legacy field-level media_library.config.max_file_size option from Netlify/Decap CMS is also supported for the internal media storage.

For example, to set a maximum file size of 1 MB for all uploads, add the following to your config.yml:

yaml
media_libraries:
  all:
    max_file_size: 1024000
toml
[media_libraries.all]
max_file_size = 1024000
json
{
  "media_libraries": {
    "all": {
      "max_file_size": 1024000
    }
  }
}
js
{
  media_libraries: {
    all: {
      max_file_size: 1024000,
    },
  },
}

Slugification of Filenames ​

Some frameworks and static site generators have restrictions on filenames, such as not allowing spaces or special characters. To ensure compatibility, you can enable filename slugification by setting the slugify_filename option to true in the media_libraries configuration.

yaml
media_libraries:
  all:
    slugify_filename: true
toml
[media_libraries.all]
slugify_filename = true
json
{
  "media_libraries": {
    "all": {
      "slugify_filename": true
    }
  }
}
js
{
  media_libraries: {
    all: {
      slugify_filename: true,
    },
  },
}

Once enabled, any uploaded file will have its filename converted to a URL-friendly format, according to the global slug options. The same applies to a file renamed in the Asset Library, or in a File or Image field before the entry is saved. The resulting filename is shown below the input. For example, Blog Photo 1.jpg is saved as blog-photo-1.jpg.

Renaming Uploaded Files ​

Files are uploaded with their original names by default, which are often meaningless, like IMG_1234.jpg, or may reveal private information. To give uploaded files consistent names, set the filename_template option to a template for the new filename.

yaml
media_libraries:
  all:
    filename_template: '{{year}}{{month}}{{day}}-{{uuid_short}}'
toml
[media_libraries.all]
filename_template = "{{year}}{{month}}{{day}}-{{uuid_short}}"
json
{
  "media_libraries": {
    "all": {
      "filename_template": "{{year}}{{month}}{{day}}-{{uuid_short}}"
    }
  }
}
js
{
  media_libraries: {
    all: {
      filename_template: "{{year}}{{month}}{{day}}-{{uuid_short}}",
    },
  },
}

With this configuration, a photo named IMG_1234.jpg uploaded on September 29, 2026, would be saved as something like 20260929-392bdcf3b642.jpg.

The template supports the same template tags and string transformations as the entry slug option, plus the following tags for the original file:

  • {{filename}}: The original filename without the extension, e.g. IMG_1234.
  • {{extension}}: The original file extension, e.g. jpg.

Keep these points in mind:

  • The file extension is always appended to the new filename, so don’t include it in the template. If the file is converted to another format by image optimization, the new extension is used.
  • The value of each tag is slugified according to the global slug options, while the rest of the template is used as is, except for characters that are not allowed in filenames. Enable the slugify_filename option as well to slugify the whole filename.
  • If a file with the same name already exists in the folder, a number is appended to the new filename, like 20260929-392bdcf3b642-1.jpg.
  • A file that replaces an existing asset keeps the name of that asset.

When a file is added to a File or Image field in the internal media storage, it’s renamed when the entry is saved. So you can also use the tags that refer to the entry, like {{slug}} for the entry slug and {{fields.title}} for a field value.

Before the entry is saved, the field shows the file with its new filename, and the name follows any changes to the entry. For example, with the {{slug}}-{{filename}} template, a photo named IMG_1234.jpg added to an entry with the summer-trip slug would be saved as summer-trip-img-1234.jpg.

In a multilingual entry, the tags are filled with the content of the default locale, so a file used in several locales has the same name everywhere. If the user renames the file by hand before saving the entry, the template no longer applies to the file.

A file uploaded from an entry to an external storage provider is renamed right away with the entry’s values at that time, and its name doesn’t follow later changes. Fill in the fields the template depends on first: a tag with no value yet is replaced with a random value.

A file uploaded in the Asset Library has no entry, so only the date/time tags, the unique identifier tags, {{filename}} and {{extension}} make sense there. Any other tag is replaced with a random value.

The option can also be set for a specific File or Image field, under the field’s media_libraries option. For example, to name the cover images of blog posts after the entry:

yaml
collections:
  - name: posts
    fields:
      - name: cover
        label: Cover Image
        widget: image
        media_libraries:
          default:
            config:
              filename_template: '{{slug}}-cover'

Cloud Storage Options ​

The following options apply to Amazon S3, S3-compatible providers and Azure Blob Storage.

Custom Storage Name ​

Each cloud storage provider appears in the CMS under its own name. To show another name, set the label option. This is useful when the Amazon S3 integration connects to a self-hosted server, where “Amazon S3” would mislead your editors.

yaml
media_libraries:
  aws_s3:
    label: Garage
    endpoint: https://s3.example.com
    region: garage
    access_key_id: YOUR_ACCESS_KEY_ID
    bucket: my-website-assets
toml
[media_libraries.aws_s3]
label = "Garage"
endpoint = "https://s3.example.com"
region = "garage"
access_key_id = "YOUR_ACCESS_KEY_ID"
bucket = "my-website-assets"
json
{
  "media_libraries": {
    "aws_s3": {
      "label": "Garage",
      "endpoint": "https://s3.example.com",
      "region": "garage",
      "access_key_id": "YOUR_ACCESS_KEY_ID",
      "bucket": "my-website-assets"
    }
  }
}
js
{
  media_libraries: {
    aws_s3: {
      label: 'Garage',
      endpoint: 'https://s3.example.com',
      region: 'garage',
      access_key_id: 'YOUR_ACCESS_KEY_ID',
      bucket: 'my-website-assets',
    },
  },
}

The name appears in the Asset Library, the Select File and Select Image dialogs, and the Settings dialog. The label option isn’t localized, and it’s only read from the top-level options, so it’s ignored in the media_libraries option of a field.

Entry-Based Folders ​

A File or Image field can use template tags in the prefix option to keep the files of each entry in a folder of their own. Editors then don’t have to create the folder themselves. For example, the following field stores its files in a folder named after the entry’s release field, such as 12/:

yaml
fields:
  - name: release
    label: Episode Number
    widget: number
    value_type: int
  - name: audio
    label: Audio
    widget: file
    media_libraries:
      aws_s3:
        prefix: '{{fields.release}}/'
toml
[[fields]]
name = "release"
label = "Episode Number"
widget = "number"
value_type = "int"

[[fields]]
name = "audio"
label = "Audio"
widget = "file"

[fields.media_libraries.aws_s3]
prefix = "{{fields.release}}/"
json
{
  "fields": [
    {
      "name": "release",
      "label": "Episode Number",
      "widget": "number",
      "value_type": "int"
    },
    {
      "name": "audio",
      "label": "Audio",
      "widget": "file",
      "media_libraries": {
        "aws_s3": {
          "prefix": "{{fields.release}}/"
        }
      }
    }
  ]
}
js
{
  fields: [
    {
      name: 'release',
      label: 'Episode Number',
      widget: 'number',
      value_type: 'int',
    },
    {
      name: 'audio',
      label: 'Audio',
      widget: 'file',
      media_libraries: {
        aws_s3: {
          prefix: '{{fields.release}}/',
        },
      },
    },
  ],
}

The other options of the provider, including the required ones such as bucket, are taken from the top-level media_libraries option, so the field only needs to set prefix.

Keep the following in mind:

  • Tags: Use {{fields.name}} for a field value. The {{slug}} tag and date/time tags such as {{year}} work too, as do string transformations. A tag can’t refer to the list item a file belongs to, so a field in a list item needs its full path, e.g. {{fields.episodes.0.release}}.
  • Field level only: The top-level prefix option can’t contain template tags, because there’s no entry to read the values from. The CMS shows a warning if they’re used there.
  • Values: Each value is slugified, so it always stands for a single folder. For example, Season 1/Pilot becomes season-1-pilot.
  • Empty fields: Until the fields used in the prefix have values, the dialog asks the editor to fill them in, and files can’t be listed or uploaded. This keeps files from ending up in the wrong folder.
  • Browsing: The dialog only lists the files under the prefix, so an editor can’t pick a file from another entry’s folder there. The Asset Library has no entry to read from, so it uses the provider’s top-level options.
  • Later changes: Changing a field value doesn’t move files that have already been uploaded. Their URLs stay valid, and new uploads go to the new folder.
  • Not access control: The prefix organizes files, but it doesn’t restrict them. An editor’s credentials still have the access you gave them.