Skip to content

Upgrade Guide

This upgrade guide lists all breaking changes in Volto and explains the steps that are necessary to upgrade to the lastest version.

Note

There are times that updating the Volto boilerplate (the one generated by @plone/create-volto-app) is enough to fulfill all the changes. If you haven't heavilly modified it, moving things around and copying over your dependencies might do when dealing with upgrades. We keep the generator up to date and in sync with current Volto release.

Upgrading to Volto 3.x

Volto was upgraded to use Razzle 3.0.0 which is not a breaking change itself, but it forces to some changes in the boilerplate on your Volto projects. You should change the babel config by deleting .babelrc file and creating a new file babel.config.js with these contents:

module.exports = require('@plone/volto/babel');

Then update your package.json to Volto 3.x.

  "dependencies": {
    "@plone/volto": "3.0.0",
    ...
  }

Volto 3.x is compatible with the new changes introduced in the vocabularies endpoint in plone.restapi 4.0.0. If you custom build a widget based in the Volto ones, you should update them as well. Volto updated its own widget set to support them:

  • components/manage/Widgets/ArrayWidget
  • components/manage/Widgets/SelectWidget
  • components/manage/Widgets/TokenWidget

They all use react-select third party library for render it.

Upgrading to Volto 2.x

Improved Tiles HOC

The Tiles HOC (High Order Component) was changed to lift off some of the features from the tiles themselves and now it takes care of them by its own.

  • The delete tile feature was moved to it
  • The keylisteners for navigating through tiles was moved to it
  • The properties passed down to the tiles are improved and documented

This change only applies to your existing tiles, you have to update them accordingly by delete the trash icon and action from the end of your tiles

{this.props.selected && (
  <Button
    icon
    basic
    onClick={() => this.props.onDeleteTile(this.props.tile)}
    className="tile-delete-button"
  >
    <Icon name={trashSVG} size="18px" />
  </Button>
)}

Modify the parent element of your tile making this changes:

<div
  role="presentation"
  onClick={() => this.props.onSelectTile(this.props.tile)}
  className={cx('tile hero', {
    selected: this.props.selected,
  })}
  tabIndex={0}
  onKeyDown={e =>
    this.props.handleKeyDown(
      e,
      this.props.index,
      this.props.tile,
      this.node
    )
  }
  ref={node => {
    this.node = node;
  }}
>
  • Add the keylisteners to the parent element of your tile
  onKeyDown={e =>
    this.props.handleKeyDown(
      e,
      this.props.index,
      this.props.tile,
      this.node
    )
  }
  • Add a ref to it and assign it to this.node.
  ref={node => {
    this.node = node;
  }}
  • Add a proper role for it
  role="presentation"

Take a look into the implementation of the default Volto tiles to get a grasp on all the edge cases related to keyboard navigation and how to deal with them.

Reordering of the internal CSS, added an extra

The internal Volto CSS has been tidied up and reordered, for that reason, some other extras have been introduced and the theme.config in your project needs to be updated by making sure you have these two extras in the theme.config file:

/* Extras */
@main        : 'pastanaga';
@custom      : 'pastanaga';