Static CMS
Star StaticJsCMS/static-cms on GitHubSponsor
DocsContributingCommunitySponsor

Netlify CMS Migration Guide

Static CMS is a fork of Netlify CMS. Many changes have been made, some big, some small. If you are coming from Netlify CMS, here is the list items to watch out for while migrating.

How to Migrate

To migrate, simply replace Netlify CMS with Static CMS, then address the changes below.

CDN

Netlify CMS:

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

Static CMS:

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

Bundling

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

# Install Static CMS
npm install @staticcms/core

Change your imports

Netlify CMS:

import CMS from 'netlify-cms-app'

Static CMS:

import CMS from '@staticcms/core';

Changes

  • React 18.2.0 is now the minimum supported React version. If you are using Static CMS through a CDN, this comes bundled.
  • 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.
  • CMS must be explicitly initiated now 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
  • A new markdown editor has been added. It comes with a new shortcode system, old editor components no longer work.
  • The sortable_fields configuration option has been slightly changed, as we now allow a default sorting option.

    Netlify CMS: 
    sortable_fields:
 - field1
 - field2

    Static CMS: 
    sortable_fields:
  fields:
   - field1
   - field2

  • Support in the List Widget for the field property has been dropped. A single field in the fields property achieves the same behavior.
  • Custom widget creation has changed slightly. React class components have been deprecated. 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.

Deprecated and Removed Features

  • Dropped the following beta features from Netlify CMS.
    • GraphQL support for GitHub and GitLab
    • Remark plugins (new markdown editor has its own plugin system)
    • Dynamic Default Values
    • Custom Mount Element
  • Dropped support for AssetStore integration
  • Dropped support for Azure backend
  • 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)
    • Gitlab, Client-Side Implicit Grant has been removed
  • createClass is deprecated, functional components should be used instead. Basic react hooks are provided as globals now.
  • getAsset is deprecated, the new useMediaAsset hook should be used instead. See Interacting With The Media Library.

Beta Features

All beta features from Netlify CMS that were kept, remain in beta and may not fully function in their current state. Please submit an issue for any bugs you find.

Platform Changes

Gatsby

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

# Uninstall Netlify CMS 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.

Netlify CMS:

npx netlify-cms-proxy-server

Static CMS:

npx @staticcms/proxy-server