How to Upgrade to v3

Static CMS v3 introduces:

• Mobile support
• Depedent fields (see Field Conditions for more information)

In this guide, we will walk you through the steps for upgrading to Static CMS v3.

Please report any issues you encounter while upgrading to Static CMS v3.

Installing

To install the latest version of Static CMS:

npm install @staticcms/core@^3.0.0

Or if you're using yarn:

yarn add @staticcms/core@^3.0.0

If you are using a CDN to load Static CMS, simply change your URLs:

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

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

Gitea Backend Update

Beta Feature

While still remaining in beta, the Gitea backend has been evolving. This update switches the authentication mechanism to PKCE auth and improves performance when dealing with multiple file commits.

To use Gitea with Static CMS v3, you need to update your Gitea instance to at least v1.20. You will also need to update your config to match the setup for PKCE authentication. See Gitea authentication.

CMS Events

Beta Feature

CMS Events have undergone a significant refactor in this update, including adding a new change event. You may need to update your config as follows to continue to use them. The preSave and postSave events along with the new change event, now require a collection be provided during registration, with an optional file if you are targeting a file collection. All events now can handle async handlers as well.

Old setup

CMS.registerEventListener({
  name: 'preSave',
  handler: ({ entry }) => {
    return {
      ...entry,
      data: {
        ...entry.data,
        title: 'new title',
      },
    };
  },
});

New Setup

CMS.registerEventListener({
  name: 'preSave',
  collection: 'posts',
  handler: ({ data: { entry } }) => {
    return {
      ...entry.data,
      title: 'new title',
    };
  },
});

See CMS Events for more details.

Other Breaking Changes

• The following Widget Control component properties have been removed:
  • hidden
  • mediaPaths - Use useMediaInsert instead.
  • openMediaLibrary - Use useMediaInsert instead.
  • removeInsertedMedia - Use useMediaInsert instead.