---
url: /en/docs/migration/netlify-decap-cms.md
description: >-
  Migrate from Netlify/Decap CMS to Sveltia CMS with step-by-step instructions
  and compatibility guidance.
---

# Migrating from Netlify CMS or Decap CMS

Sveltia CMS is designed as a modern [successor to Netlify CMS](/en/docs/successor-to-netlify-cms) (now Decap CMS). If you are currently using Netlify/Decap CMS, you can migrate to Sveltia CMS to take advantage of its hundreds of improvements across the board, including better performance, a more intuitive user interface, enhanced asset management, improved i18n support, and more.

::: warning Stable Version Not Yet Available

Sveltia CMS is still in beta. Although it’s already being used in production by [many users](/en/showcase), there might still be breaking changes before the stable 1.0 release. We recommend keeping an eye on the [release information](/en/docs/releases#release-information) for any updates.

:::

## Examples

Still not sure if Sveltia CMS is the right choice? Check out the following examples of sites that have been migrated from Netlify CMS and Decap CMS to see how other users have successfully transitioned to Sveltia CMS.

* [Examples of sites migrated from Netlify CMS](/en/showcase?migrated-from=netlify-cms)
* [Examples of sites migrated from Decap CMS](/en/showcase?migrated-from=decap-cms)

## Compatibility

We have made Sveltia CMS highly compatible with Netlify/Decap CMS, allowing more users to seamlessly switch to our modern successor. In most cases, Sveltia CMS can be used as a drop-in replacement for Netlify/Decap CMS with just a one-line code update.

However, we never planned to achieve 100% feature parity, so some features will not be added due to deprecation and other factors. See the compatibility information below to learn how the site may be affected by the migration.

### Current Limitations

We no longer have any known limitations in Sveltia CMS, except for some [UI languages](/en/docs/ui#localization) that are not yet available.

### Features Not To Be Implemented

The following features will not be implemented in Sveltia CMS due to deprecation and other factors. If you rely on any of these features, you may need to find a workaround or wait until we develop an alternative solution.

#### Deprecated Features

Other than the recently deprecated [`logo_url` option](/en/docs/customization#custom-logo), we will not support any deprecated features in Netlify/Decap CMS:

* **Git Gateway backend**: Git Gateway has been [deprecated](https://docs.netlify.com/manage/security/secure-access-to-sites/git-gateway/) by Netlify. Due to its performance limitations, we don’t plan to support it anyway. However, we plan to develop a GraphQL-based high-performance alternative [in the future](/en/docs/roadmap) to provide a migration path for existing Git Gateway users.
* The deprecated client-side implicit grant for the GitLab backend: It has already been [removed from GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/344609). Use the [client-side PKCE authorization](/en/docs/backends/gitlab#pkce-authorization) instead.
* The deprecated Netlify Large Media service: Consider other [media storage providers](/en/docs/media).
* Deprecated camel case configuration options: Use snake case instead, according to the current Decap CMS document.
  * [Entry Collection](/en/docs/collections/entries): `sortableFields`
  * [DateTime](/en/docs/fields/datetime) field: `dateFormat`, `timeFormat`, `pickerUtc`
  * [Markdown](/en/docs/fields/markdown) field: `editorComponents`
  * [Number](/en/docs/fields/number) field: `valueType`
  * [Relation](/en/docs/fields/relation) field: `displayFields`, `searchFields`, `valueField`
  * Note: Some other camel case options, including Color field options, are not deprecated and will continue to work.
* The deprecated Date widget: It was removed from Decap CMS 3.0 and Sveltia CMS 0.10. Use the DateTime field type with the [`type: date` option](/en/docs/fields/datetime#date-only) instead.
* The deprecated [Uploadcare jQuery File Uploader](https://uploadcare.com/docs/uploads/file-uploader/): Sveltia CMS uses the API for [Uploadcare integration](/en/docs/media/uploadcare) to solve some issues. Users are prompted to enter their secret key to use the integration. This means the features found in the pre-built widget are currently unavailable. We plan to support some third-party upload sources, camera access and image editing in the future.

#### Miscellaneous Features

The following features will not be implemented in Sveltia CMS due to various reasons:

* **Netlify Identity Widget**: It’s not useful without Git Gateway. We plan to develop an alternative solution with role support [in the future](/en/docs/roadmap).
  * [Netlify Identity](https://docs.netlify.com/manage/security/secure-access-to-sites/identity/overview/) was [deprecated](https://github.com/sveltia/sveltia-cms/discussions/284) in February 2025, but it has since been revived by Netlify. However, we still don’t plan to support it in Sveltia CMS due to the lack of Git Gateway support.
* **Azure DevOps and Bitbucket backends**: For performance reasons. We’ll support these platforms if their APIs improve to allow the CMS to fetch multiple entries at once. Consider migrating to GitHub, GitLab, Gitea or Forgejo if you’d like to use Sveltia CMS now.
* **Decap Turbo**: It’s a managed hosting service, not a core feature. Some notes:
  * Performance: Sveltia CMS uses the GraphQL API to retrieve multiple files at once, so it’s already fast. Using a proxy is a bad idea!
  * Media library: Sveltia CMS already implements [S3-compatible storage providers](/en/docs/media#external-storage) as a standard feature.
  * User management, roles and credentials: We plan to implement these features with [Sveltia CMS Additions](/en/docs/roadmap#v1-0), our free server-side component.
  * Deploy status: Sveltia CMS partially implements it as part of [deploy previews](/en/docs/workflows/deploy-previews).
* [Gatsby plugin](https://github.com/decaporg/gatsby-plugin-decap-cms): In light of Gatsby’s [uncertainty](https://github.com/gatsbyjs/gatsby/discussions/39062), we won’t be investing time in developing a plugin for it. Gatsby users can still create `index.html` themselves. Note: We don’t support Netlify Identity Widget; the favicon can be specified with the `logo.src` option.
* Performance-related options: Sveltia CMS has [drastically improved performance](/en/docs/successor-to-netlify-cms#better-performance) with GraphQL enabled by default, so these are no longer relevant:
  * Global: [`search`](https://decapcms.org/docs/configuration-options/#search)
  * Backend: [`use_graphql`](https://decapcms.org/reference/config/backends/github/#graphql-api)
  * Relation field: `options_length`
* An absolute URL in the [`public_folder`](https://decapcms.org/docs/configuration-options/#public-folder) option: Such configuration is not recommended, as stated in the Netlify/Decap CMS document.
* The new [`media_processing`](https://decapcms.org/docs/configuration-options/#media-processing) option: Sveltia CMS has already implemented a [built-in image optimizer](/en/docs/media#image-optimization) that supports both raster and SVG images and will be further enhanced. Use that feature instead.
* The theme and keymap inline settings for the Code field, along with support for some languages. Instead of [CodeMirror](https://codemirror.net/), we use Lexical’s code block functionality powered by [Shiki](https://shiki.style/).
* The `allow_multiple` option for the File and Image fields: It’s a confusing option that defaults to `true`, and there is a separate option called `media_library.config.multiple`. We have added the new [`multiple`](/en/docs/fields/file#multiple) option instead, which is more intuitive and works with all media storage providers.
* Remark plugins for the Markdown field: Not compatible with our Lexical-based rich text editor. The `CMS.registerRemarkPlugin` method is a noop in Sveltia CMS.
* The `use_secure_url` option for the [Cloudinary media storage](/en/docs/media/cloudinary): Insecure URLs should never be used.
* Local proxy server: Our [local development workflow](/en/docs/workflows/local) eliminates the need for a proxy server. For security and performance reasons, we don’t support `netlify-cms-proxy-server` or `decap-server`. The `local_backend` option is ignored.
* The global [`issue_reports`](https://decapcms.org/docs/configuration-options/#issue-reports) option: The Report Issue link in the Help menu always points to the Sveltia CMS issue tracker, and the `url` option is ignored.
* The global [`locale`](https://decapcms.org/docs/configuration-options/#locale) option and `CMS.registerLocale` method: Sveltia CMS automatically detects the user’s preferred language and changes the [UI locale](/en/docs/ui#localization).

#### Undocumented Features

We don’t implement features not described in the Netlify/Decap CMS documentation.

* The undocumented `getAsset` and `fields` parameters for the `toPreview` function of [custom editor components](/en/docs/api/editor-components): Sveltia CMS does not support these parameters because it automatically replaces image paths with blob URLs in the preview.
* [Undocumented methods](https://github.com/sveltia/sveltia-cms/blob/57562472e29c4090506000f7767df5179a450adb/src/lib/services/api/compatibility.js#L15-L35) exposed on the `CMS` object: This includes custom backends and custom media storage providers, if any. We may support these features in the future, but our implementation would likely be incompatible with Netlify/Decap CMS.
* Any other undocumented features and options. Exceptions apply.

### Other Breaking Changes

There are some differences in behavior between Sveltia CMS and Netlify/Decap CMS that may affect your existing configuration or content.

* [Decap CMS 3.1.1](https://github.com/decaporg/decap-cms/releases/tag/decap-cms%403.1.1) replaced Moment.js with Day.js for date handling, and In Sveltia CMS followed suit. Since [Day.js tokens](https://day.js.org/docs/en/display/format) are not 100% compatible with [Moment.js tokens](https://momentjs.com/docs/#/displaying/format/), this could be a breaking change in certain cases. Check your `format`, `date_format` and `time_format` options for DateTime fields, as well as any date formatting in [string transformations](/en/docs/string-transformations#date).
* By default, Sveltia CMS does not slugify uploaded filenames, as mentioned in the [asset management](/en/docs/successor-to-netlify-cms#better-asset-management) section. If your site generator expects hyphenated filenames, you can enable the `slugify_filename` [internal media storage option](/en/docs/media#slugification-of-filenames).
* In some cases, the [data output](/en/docs/data-output) of Sveltia CMS may differ from that of Netlify/Decap CMS. Notably, Sveltia CMS does not omit empty optional fields by default. If you have data validation in your site generator, this could cause issues. Use the `omit_empty_optional_fields` [output option](/en/docs/data-output#controlling-data-output) if needed.
* Sveltia CMS requires a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts), meaning it only works with HTTPS, `localhost` or `127.0.0.1` URLs. If you’re running your own remote server and serving content over HTTP, the CMS will not work. We recommend obtaining a TLS certificate from [Let’s Encrypt](https://letsencrypt.org/).
* In Sveltia CMS, the `sanitize_preview` option for the [Markdown](/en/docs/fields/markdown) field type is set to `true` by default to prevent potential XSS attacks via entry previews. Decap CMS made the same change in version 3.13.0, so this only affects sites migrating from Netlify CMS or an earlier version of Decap CMS. We recommend keeping this option enabled unless disabling it fixes a broken preview and you fully trust all users of the CMS.
* In Sveltia CMS, the `show_in_header` option for the [custom logo](/en/docs/customization#custom-logo) defaults to `true`, so the logo appears in the header of the admin interface. In Decap CMS, it’s hidden unless the option is set to `true`. To hide it, set `show_in_header: false` explicitly.
* In Sveltia CMS, the `create` option for [entry collections](/en/docs/collections/entries) defaults to `true` because, in 99.99% of cases, users want to create new entries and adding `create: true` to every collection is redundant. To disable entry creation, set `create: false` explicitly.
* We provide only one npm package, `@sveltia/cms`, which includes all necessary code, while Netlify/Decap CMS provides [many packages](https://github.com/decaporg/decap-cms/tree/main/packages). This means `import` statement migration is not always straightforward. See the [migration steps](#migration-steps) below for details.

There may be other minor differences in behavior that are not listed here.

Sveltia CMS is also adding various config validation checks to help users identify potential issues, so you may see errors that were not present in Netlify/Decap CMS before. For example, Sveltia CMS raises an error if the `slug` collection option contains slashes (`/`), which is supposed to be invalid.

[Let us know](https://github.com/sveltia/sveltia-cms/issues/new?type=bug) if you have encounter any compatibility issues not mentioned above. We want to make the migration process as smooth as possible for our users.

## Migration Steps

### Preparation

Check the [compatibility info](/en/docs/migration/netlify-decap-cms#compatibility) above to see if your site can be migrated now or in the near future. If there are no blockers, let’s move on to the migration steps.

#### Updating Configuration

Make necessary changes if needed, such as updating your configuration file.

#### Dealing with Unsupported Features

If you’re using any [features that are not going to be implemented](#features-not-to-be-implemented), you’ll need to find a workaround. For example, if you’re on Azure DevOps or Bitbucket, consider migrating to GitHub, GitLab, Gitea or Forgejo. See the next section if you’re a Git Gateway user.

#### Migrating from Git Gateway Backend

Sveltia CMS does not support the deprecated Git Gateway backend. If you don’t care about user management with Netlify Identity, you can use the [GitHub](/en/docs/backends/github) or [GitLab](/en/docs/backends/gitlab) backend instead.

To allow other people to edit content, simply invite them to your GitHub repository with the write role assigned.

Once you have migrated from the Git Gateway and Netlify Identity combo, you can remove the Netlify Identity Widget script tag from your HTML:

```diff
-<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
```

If you want to stay with Git Gateway and Netlify Identity, unfortunately you can’t migrate to Sveltia CMS right now. We plan to develop an alternative solution [in the future](/en/docs/roadmap).

### Switching to Sveltia CMS

Now, it’s time to switch to Sveltia CMS. Depending on how you included Netlify/Decap CMS in your project, follow the appropriate instructions below.

#### Using CDN

Replace the script tag that includes Netlify/Decap CMS with the following Sveltia CMS script tag:

```html
<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>
```

From Netlify CMS:

```diff
-<script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script>
+<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>
```

From Decap CMS:

```diff
-<script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>
+<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>
```

Next, let’s [test Sveltia CMS on your local machine](/en/docs/workflows/local). If everything looks good, push the change to your repository.

You can now open `https://[hostname]/admin/` as usual to start editing. There is even no authentication process if you’re already signed in with a backend on Netlify/Decap CMS because Sveltia CMS uses the auth token stored in the browser. Simple enough!

#### Using Package Manager

Install Sveltia CMS:

::: code-group

```bash [npm]
npm install @sveltia/cms
```

```bash [yarn]
yarn add @sveltia/cms
```

```bash [pnpm]
pnpm add @sveltia/cms
```

```bash [bun]
bun add @sveltia/cms
```

:::

Then, update your import statements accordingly.

From Netlify CMS:

```diff
-import CMS from 'netlify-cms-app'; // or 'netlify-cms'
+import CMS from '@sveltia/cms';
```

From Decap CMS:

```diff
-import CMS from 'decap-cms-app'; // or 'decap-cms'
+import CMS from '@sveltia/cms';
```

That’s it! You have successfully migrated to Sveltia CMS. Enjoy the improved performance and features.

### Cleaning Up

You can uninstall the old Netlify/Decap CMS packages from your project to keep it clean. The packages vary depending on your setup, so uninstall all relevant ones.

A few notable changes to be aware of:

* The `netlify-cms-locales`/`decap-cms-locales` package and the `CMS.registerLocale` method are no longer needed, as Sveltia CMS automatically detects the user’s preferred language and changes the [UI locale](/en/docs/ui#localization) accordingly.
* If you were using `netlify-cms-proxy-server`/`decap-server`, you can stop using it and remove it from your setup. Sveltia CMS’s [local workflow](/en/docs/workflows/local) eliminates the need for a proxy server for improved security, performance and productivity. The `local_backend` option in your configuration file is no longer needed and can be removed. If you had configured a custom port number with the `.env` file, you can remove it as well.
* Sveltia CMS only publishes a single package called `@sveltia/cms`, which includes all necessary code, while Netlify/Decap CMS provides [many packages](https://github.com/decaporg/decap-cms/tree/main/packages). If you were using any other Netlify/Decap CMS packages, you may need to find alternatives or implement the functionality yourself.

### JSON Schema Setup

For a better DX, we recommend [setting up the JSON schema](/en/docs/config-basics#validation-and-autocomplete) for the CMS configuration file in your code editor. If you have the YAML extension installed, VS Code may automatically apply the outdated Netlify CMS config schema to `config.yml`. To use the latest Sveltia CMS config schema instead, you need to specify its URL.

### AI Tools

This documentation site provides an official Agent Skill and `llms.txt` files that you can use with AI agents like GitHub Copilot, Claude and ChatGPT to help them understand Sveltia CMS better. See [Working with AI](/en/docs/working-with-ai) for details.

### Authentication

No changes are needed for authentication if you are using the GitHub, GitLab or Gitea/Forgejo backend. Sveltia CMS will use the existing auth tokens stored in the browser.

If you have set up an OAuth application for Netlify/Decap CMS, you can continue using it with Sveltia CMS. There is no need to create a new OAuth app.

::: tip Note for Netlify Customers

If you currently use Netlify to sign in with GitHub or GitLab and stay on Netlify, no changes are needed. Sveltia CMS works seamlessly with Netlify’s authentication system. However, if you’re moving to a different hosting service, you will need to use a different authentication method. See the [GitHub backend](/en/docs/backends/github#authentication) or [GitLab backend](/en/docs/backends/gitlab#authentication) documentation for more details.

:::

### Content Security Policy (CSP)

Unlike Netlify/Decap CMS, Sveltia CMS does not require the `unsafe-eval` and `unsafe-inline` keywords in the `script-src` CSP directive. However, new CSP rules may be needed depending on your configuration, such as the media storage providers you use. See [setting up Content Security Policy](/en/docs/security#setting-up-content-security-policy) for more information.

## Other Notable Differences

Some differences between Sveltia CMS and Netlify/Decap CMS may affect your existing configuration or content. Here are some notable ones to be aware of:

### Terminology

Some features have different names in Sveltia CMS compared to Netlify/Decap CMS. These differences are mostly cosmetic, and the underlying concepts remain the same. There are no changes in functionality.

| Netlify/Decap CMS | Sveltia CMS |
| --- | --- |
| [Media library](https://decapcms.org/docs/configuration-options/#media-library) | [Media storage provider](/en/docs/media) |
| [Folder collection](https://decapcms.org/docs/collection-folder/) | [Entry collection](/en/docs/collections/entries) |
| [Widget](https://decapcms.org/docs/widgets/) | [Field type](/en/docs/fields) |
| [Summary string transformation](https://decapcms.org/docs/summary-strings/) | [String transformation](/en/docs/string-transformations) |

### Content Editing Experience

Sveltia CMS marks required fields for efficient data entry. This is the opposite of Netlify/Decap CMS, which marks optional fields. This change aims to reduce visual clutter and help users focus on the essential fields that must be filled out.

When [i18n support](/en/docs/i18n) is enabled, Sveltia CMS requires all locales to have values for required fields. In contrast, Netlify/Decap CMS only enforces this for the default locale. This change ensures that content is complete across all locales. If you rely on the previous behavior, you can set the `required` [field-level configuration](/en/docs/i18n/options#field-level-configuration) to include only specific locales.

In a [nested collection](/en/docs/collections/entries/nested) with the `meta.path` option, the field that decides where an entry goes works differently. Netlify/Decap CMS asks for the full path of the folder that will hold the entry’s file, typed by hand. Sveltia CMS shows a [Parent Folder](/en/docs/collections/entries/nested#choosing-a-parent-folder) picker listing the folders that already exist, and names the new entry’s own folder after its slug:

```yaml
# Netlify/Decap CMS: path "products/hardware"
content/pages/products/hardware/_index.md

# Sveltia CMS: parent folder "products", slug "hardware"
content/pages/products/hardware/_index.md
```

The result is the same, but you choose the parent rather than typing the entry’s own folder. Moving an existing entry works the same way in both.

Both sides of that example assume the `meta.path.index_file` option, which gives every entry the same file name. Without it, Netlify/Decap CMS names a new entry’s file from the `title` field — ignoring the collection’s [`slug`](/en/docs/collections/entries/slugs#defining-entry-slugs) template and `identifier_field`, so a collection with no `title` field saves every entry as `untitled`. Sveltia CMS names the file from the slug, as it does in any other collection.

### Data Output

The data output conventions of Sveltia CMS may differ from that of Netlify/Decap CMS in some cases. See the [data output](/en/docs/data-output#data-output-conventions) documentation for details.

You don’t need to manually update your existing content — the CMS automatically handles these differences when loading existing content. However, there are two notable differences to be aware of:

* Sveltia CMS does not omit empty optional fields by default. If you have data validation in your framework, this could cause issues. Use the `omit_empty_optional_fields` [output option](/en/docs/data-output#controlling-data-output) if needed.
* Markdown uses soft line breaks (single line breaks) instead of hard line breaks (escaped line breaks `\`). In your framework, you may need to [enable the appropriate option](/en/docs/how-tos#rendering-soft-line-breaks-as-hard-line-breaks-in-markdown) to render soft line breaks as hard line breaks.

### Preview Styles

Sveltia CMS comes with a minimum default preview style to ensure better readability. If you have [custom preview styles](/en/docs/api/preview-styles) for Netlify/Decap CMS, you could remove them or adapt them to Sveltia CMS, which shows field labels in the preview by default.