Migrating from version 2.0 to 3.0

Migrating from version 2.0 to 3.0

Overview

Whereas React-Toolbox 2.x used PostCSS with cssnext, React-Toolbox 3.0 uses PostCSS with postcss-preset-env and specifically, the color() function in css has been replaced by color-mod() and postcss-preset-env does not include a reduce calc() function. The TimePicker component now also requires React 16.

Migrating from 2.0 to 3.0 requires adding the postcss-color-mod-function and possibly postcss-calc into your PostCSS build setup (i.e. webpack). This can be done in one of two ways:

Option 1 - adding postcss-color-mod-function to existing cssnext setup

npm install postcss-color-mod-function --save-dev

Add this plugin to the postcss configuration in webpack:

  postcss: () => {
    return [
      /* eslint-disable global-require */
      require('postcss-cssnext')({
        features: {
          customProperties: {
            variables: reactToolboxVariables,
          },
        },
      }),
      require('postcss-modules-values'),
      require('postcss-color-mod-function'),
      /* eslint-enable global-require */
    ];
  },

(postcss-modules-values is optional.)

Option 2 - replacing cssnext with postcss-preset-env

Unfortunately the latest version of postcss-preset-env brings in version 8+ of postcss-custom-properties, which no longer supports overriding the already-defined variables in react-toolbox with your customProperties in webpack - https://github.com/postcss/postcss-custom-properties/issues/148

As a result, you need to use either an older (5.x) version of postcss-preset-env or disable custom-properties in postcss-preset-env and use the 7.x version of postcss-custom-properties separately. If you previously used cssnext, you will probably need to upgrade to newer version of postcss and use the postcss-loader to support postcss-preset-env.

Option 2a - using older postcss-preset-env

npm remove postcss-cssnext
npm install postcss-loader --save-dev
npm install postcss-preset-env@^5.3.0 --save-dev
npm install postcss-calc --save-dev

Replace the postcss configuration in webpack for cssnext with the one for postcss-preset-env:

  postcss: () => {
    return [
      /* eslint-disable global-require */
      require('postcss-preset-env')({
        stage: 0, // enables all postcss-preset-env features to match cssnext
        features: {
          'custom-properties': {
            preserve: false, // returns calculated values instead of variable names
            variables: reactToolboxVariables,
          },
          'color-mod-function': true, // if you use a stage later than 0
        },
      }),
      require('postcss-calc'), // required as postcss-preset-env doesn't have a reduce calc() function that cssnext did
      require('postcss-modules-values'),
      /* eslint-enable global-require */
    ];
  },

(postcss-modules-values is optional.)

Option 2b - using postcss-custom-properties 7.x separately

npm remove postcss-cssnext
npm install postcss-loader --save-dev
npm install postcss-preset-env --save-dev
npm install postcss-calc --save-dev
npm install postcss-mixins --save-dev
npm install postcss-each --save-dev
npm install postcss-apply --save-dev
npm install postcss-custom-properties@^7.0.0 --save-dev

Replace the postcss configuration in webpack for cssnext with the one for postcss-preset-env with custom-properties disabled and add postcss-custom-properties ahead of postcss-preset-env:

  postcss: () => {
    return [
      /* eslint-disable global-require */
      require('postcss-mixins')(),
      require('postcss-each')(),
      require('postcss-apply')(),
      require('postcss-custom-properties')({
        preserve: false, // returns calculated values instead of variable names
        variables: reactToolboxVariables,
      }),
      require('postcss-preset-env')({
        stage: 0, // enables all postcss-preset-env features to match cssnext
        features: {
          'environment-variables': false, // react-toolbox doesn't use env() but this feature's parser causes problems
          'custom-properties': false,
          'color-mod-function': true, // if you use a stage later than 0
        },
      }),
      require('postcss-calc'), // required as postcss-preset-env doesn't have a reduce calc() function that cssnext did
      require('postcss-modules-values'),
      /* eslint-enable global-require */
    ];
  },

(postcss-modules-values is optional.)

Note that if your own css files use negative-value-of-a-value calc expressions like these:

@value containerHeight: 35px;
.container {
  height: containerHeight;
  margin-top: calc(containerHeight * -1);
}

this will fail to compile with postcss-calc 6.x and 7.x, so keep it at version 5.x, i.e.: npm install postcss-calc@^5.3.1 --save-dev