Static CMS
Star StaticJsCMS/static-cms on GitHub
v4.3.0DocsExamplesDemoCommunity

Decap / Netlify Migration Guide

Static CMS is a fork of Decap (previously Netlify CMS). Many changes have been made, some big, some small.

In this guide, we will walk you through the steps of migrating from Decap or Netlify to Static CMS.

How to Migrate

Start by replacing Decap / Netlify with Static CMS, then address the changes below.

CDN

Decap (remove):

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

Netlify (remove):

<script src="https://unpkg.com/netlify-cms@^3.0.0/dist/netlify-cms.js"></script>

Static CMS (add):

<script src="https://unpkg.com/@staticcms/app@^4.0.0/dist/static-cms-app.js"></script>

Bundling

# Uninstall Decap
npm uninstall decap-cms-app
npm uninstall decap-cms-core

# Uninstall Netlify
npm uninstall netlify-cms-app
npm uninstall netlify-cms-core

# Install Static CMS
npm install @staticcms/core

Change your imports

Decap (remove):

import CMS from 'decap-cms-app';

Netlify (remove):

import CMS from 'netlify-cms-app';

Static CMS (add):

import CMS from '@staticcms/core';

Changes

React 18

React 18.2.0 is now the minimum supported React version. If you are using Static CMS through a CDN, this comes bundled.

Static CMS Styles

Static CMS bundles its styles separately from the main javascript file, so you will need to import them separately.

CDN:

<link rel="stylesheet" href="https://unpkg.com/@staticcms/app@^3.0.0/dist/main.css" />

Bundling:

import '@staticcms/core/dist/main.css';

Backends

The Azure backend has been removed. All other backends are still supported.

However, the Gitlab, Client-Side Implicit Grant has been removed as a method of authentication.

Dates

Moment has been dropped as the date library used. Instead we are now using date-fns. Date formats in your configuration will need to be updated. See format docs.

Initializing Static CMS

CMS must be explicitly initiated by calling CMS.init(). Passing a config to CMS.init() will now completely override config.yml (they are now exclusive), instead of being merged with config.yml

Markdown Editor

A new markdown editor has been added. It comes with a new shortcode system, old editor components no longer work.

Sortable Fields

The sortable_fields configuration option has been slightly changed, as we now allow a default sorting option.

Decap / Netlify:

sortable_fields:
  - field1
  - field2

Static CMS:

sortable_fields:
  fields:
    - field1
    - field2

View Filters

The view_filters configuration option has been slightly changed, as we now allow a default filter option. Also each filter now requires a unique name.

Decap / Netlify:

view_filters:
  - label: "Alice's and Bob's Posts"
    field: author
    pattern: 'Alice|Bob'
  - label: 'Posts published in 2020'
    field: date
    pattern: '2020'
  - label: Drafts
    field: draft
    pattern: true

Static CMS:

view_filters:
  fields:
    - name: alice-and-bob
      label: "Alice's and Bob's Posts"
      field: author
      pattern: 'Alice|Bob'
    - name: posts-2020
      label: 'Posts published in 2020'
      field: date
      pattern: '2020'
    - name: drafts
      label: Drafts
      field: draft
      pattern: true

View Groups

The view_groups configuration option has been slightly changed, as we now allow a default grouping option. Also each group now requires a unique name.

Decap / Netlify:

view_groups:
  - label: Year
    field: date
    # groups items based on the value matched by the pattern
    pattern: \d{4}
  - label: Drafts
    field: draft

Static CMS:

view_groups:
  groups:
    - name: by-year
      label: Year
      field: date
      # groups items based on the value matched by the pattern
      pattern: \d{4}
    - name: drafts
      label: Drafts
      field: draft

List Widget

Support in the List Widget for the field property has been dropped. A single field in the fields property achieves the same behavior.

Custom Widgets

Custom widget creation has changed. createClass has been removed. Custom widgets should all be functional components now.

There have also been changes to how custom widgets are registered and the properties passed to the controls and previews. See custom widgets for full details.

Custom Previews

Custom preview creation has changed. createClass has been removed. Custom previews should all be functional components now.

There have also been changes to the properties passed to custom previews. See custom previews for full details.

External integrations

The following external integrations have been removed:

  • Algolia
  • AssetStore
  • Cloudinary
  • Uploadcare

Deprecated Features

  • All deprecated features were removed
    • date widget has been removed
    • datetime widget
      • dateFormat has been removed (Use date_format instead)
      • timeFormat has been removed (Use time_format instead)

Media Library

The getAsset method has been removed, the new useMediaAsset hook should be used instead. See Interacting With The Media Library.

Beta Features

The following beta features from Decap / Netlify have been dropped:

  • GraphQL support for GitHub and GitLab
  • Remark plugins (new markdown editor has its own plugin system)
  • Dynamic Default Values
  • Custom Mount Element

Nested Collections

Nested Collections have some breaking config changes. The meta config has been dropped and its path property has been moved into the nested prop. You can also no longer specify the widget type for the path.

Old Config

collections:
  - name: pages
    label: Pages
    label_singular: 'Page'
    folder: content/pages
    create: true
    nested:
      depth: 100
      summary: '{{title}}'
    fields:
      - label: Title
        name: title
        widget: string
      - label: Body
        name: body
        widget: markdown
    meta: { path: { widget: string, label: 'Path', index_file: 'index' } }

Platform Changes

Gatsby

If you are using Gatsby you will need to change out your CMS plugin.

# Uninstall Decap / Netlify plugin
npm uninstall gatsby-plugin-netlify-cms

# Install Static CMS plugin
npm install gatsby-plugin-static-cms

Local Development Changes

If you are using the local backend you will need to switch the proxy server package you are using.

Decap (remove):

npx decap-server

Netlify (remove):

npx netlify-cms-proxy-server

Static CMS (add):

npx @staticcms/proxy-server