Migrating from version 1.3 to 2.0

Migrating from version 1.3 to 2.0

Overview

Whereas React-Toolbox 1.x used SASS, React-Toolbox 2.0 uses PostCSS + cssnext. It also no longer bundles in CSS with global effect on the page. A few internal, undocumented components have also changed how they operate. Therefore migrating from 1.3 to 2.0 involves four steps:

1. Set up PostCSS + cssnext in webpack
2. Change how theme variables are set
3. Add global normalization / reset CSS to match 1.3
4. Make some changes if you used the Overlay component before

Set up PostCSS + cssnext in webpack

npm install postcss-loader --save-dev
npm install postcss --save
npm install postcss-cssnext --save
npm install postcss-modules-values --save

(postcss-modules-values is optional)

Configure webpack 1.x loader for .css files to use postcss:

      {
        test: /\.css$/,
        loaders: [
          'style-loader',
          'css-loader?sourceMap&modules&importLoaders=1&localIdentName=[name]__[local]___[hash:base64:5]!postcss?sourceMap&sourceComments',
        ],
      },

Declare plugins to be used by postcss (as part of webpack's config object):

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

(postcss-modules-values is optional. See next section regarding reactToolboxVariables)

Change how theme variables are set

React-Toolbox 1.x used SASS variables that could be set with something like this (in the webpack config object):

  sassLoader: {
    // This injects the specified variable-setting file as an import into every processed sass file
    data: `@import '${path.resolve(__dirname, './src/themes/_config.scss').replace(/\\/g, '/')}';`,
  },

The above should now be removed. Instead, React-Toolbox 2.x uses CSS Properties that can be set at build time by providing them in a JavaScript object as variables for customProperties feature of css-next, with the above postcss config:

const reactToolboxVariables = {
  'color-text': '#444548',
};

You can alternatively use CSS Module Values and the modules-values-extract utility to declare these variables in component-specific theme .css files, where you would typically store additional style overrides.

CSS Module Values also offer the advantage that importing a css file with @value declarations makes these values properties of the imported style object, i.e.:

# variables.css

@value buttonPrimaryBackgroundColor: #9c3990;

import styleVariables from './css/variables.css';

styleVariables.buttonPrimaryBackgroundColor

In this demo project, modules-values-extract utility is used to extract all @values with dashes in their name from all css files in the /css folder and to feed them to customProperties in webpack. In the demo project, variables that are not specific to a particular component are in variables.css and button-specific variables are in button.css. Note that button.css also imports certain values from variables.css just to demonstrate this capability (the import can also be used in a @value declaration) and it uses CSS overrides instead of color variables that exist in the React-Toolbox Button component to show an alternative method if the variables are not sufficient.

IMPORTANT: Changes to the module values do not take effect immediately with Webpack Hot-Module-Reload - webpack / webpack-dev-server must be restarted!

Add global normalization / reset CSS to match 1.3

npm install normalize.css --save

Replace @import "~react-toolbox/lib/commons"; with:

@import "normalize.css";
@import "./global.scss";

where global.scss that is largely equivalent to 1.3 can be seen here. (If the above @import is in a SCSS file, use @import "~normalize.css";, i.e. with a ~.)

Make some changes if you used the Overlay component before

If you used the undocumented/internal Overlay component to render some components as a popup (without a Dialog), you will now need to use the (equally undocumented/internal) Portal component (which creates the popup and Overlay is now used for the backdrop), i.e.: 1.3:

import { Overlay } from 'react-toolbox/lib/overlay';
...
  render() {
    return (
      <Overlay invisible>
        {this.props.children}
      </Overlay>
    );
  }

2.x:

import Portal from 'react-toolbox/lib/hoc/Portal';
import theme from 'react-toolbox/lib/dialog/theme.css';
...
  render() {
    return (
      <Portal className={theme.wrapper}>
        {this.props.children}
      </Portal>
    );
  }

or (example of a gray-out backdrop with a progress indicator over it):

        <Portal className={theme.wrapper}>
          <Overlay active />
          <ProgressBar type="circular" mode="indeterminate" multicolor />
        </Portal>