1. Home
  2. Docs
  3. docs
  4. Migration Guides
  5. How to Upgrade to v4

How to Upgrade to v4

Static CMS v4 introduces:

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

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

Installing

To install the latest version of Static CMS:

npm install @staticcms/core@^4.0.0

Or if you are using yarn:

yarn add @staticcms/core@^4.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@^4.0.0/dist/main.css" />

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

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.

Old setup

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
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,
  },
];

New setup

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_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.

Old setup

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

New setup

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
view_groups: {
  groups: [
    {
      name: "by-year",
      label: "Year",
      field: "date",
      pattern: "\\d{4}
    },
    {
      name: "drafts",
      label: "Drafts",
      field: "draft"
    }
  ]
}

Theme

The theme prop has been removed from:

The new useTheme hook should be instead to get the colors of the current theme.

Date Template Transformation

The date template transformation now uses date-fns tokens instead of momentjs.

List / Object Filter Rules

Previously, when using Filtered Folder Collections, specifying a list field, Static CMS would search the values of the list to find a match. Now the default behavior is to match the JSON formatted version of the list’s value. To match values inside the list, simply add .* to the end of your filter field.

Object fields are also now matched against the JSON formatted version of their values.

Old setup

filter:
  field: list_field
  value: some_value
filter: {
  field: 'list_field',
  value: 'some_value'
}

New setup

filter:
  field: list_field.*
  value: some_value
filter: {
  field: 'list_field.*',
  value: 'some_value'
}

i18n Config

For i18n, the setting defaultLocale has been renamed to default_locale.

Type Changes (TypeScript)

The StringOrTextField type has been split into StringField and TextField.