React Toolbox Deployment & Usage Guide

A comprehensive guide for integrating React Toolbox (Material Design components with CSS Modules) into React applications.

Prerequisites

• Node.js: Version 8.0 or higher (LTS recommended)
• Package Manager: npm (6+) or yarn
• React: Version 16.3+ (peer dependency)
• Module Bundler: Webpack 2.x/3.x/4.x, or Create React App
• Build Tools: PostCSS toolchain for CSS processing

Installation

1. Install React Toolbox

npm install --save react-toolbox

Or with yarn:

yarn add react-toolbox

2. Install PostCSS Dependencies (Webpack Projects)

Required for processing CSS Modules with PostCSS features:

npm install --save-dev postcss-loader postcss postcss-preset-env postcss-calc

3. Peer Dependencies

Ensure React is installed:

npm install --save react react-dom

Configuration

Webpack Configuration (Non-CRA Projects)

Configure CSS loader to handle CSS Modules and PostCSS:

Webpack 2.x/3.x/4.x:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              modules: true,
              sourceMap: true,
              importLoaders: 1,
              localIdentName: "[name]--[local]--[hash:base64:8]"
            }
          },
          "postcss-loader"
        ]
      }
    ]
  }
};

PostCSS Configuration:

Create postcss.config.js in project root:

module.exports = {
  plugins: [
    require('postcss-preset-env')({
      stage: 0,
      features: {
        'custom-properties': {
          preserve: false,
        },
        'color-mod-function': true,
      }
    }),
    require('postcss-calc'),
  ]
};

Create React App Configuration

CRA doesn't allow custom webpack config without ejecting. Use react-toolbox-themr:

npm install --save react-toolbox-themr

Add to package.json:

{
  "scripts": {
    "toolbox": "react-toolbox-themr"
  },
  "reactToolbox": {
    "include": ["BUTTON", "INPUT", "DATE_PICKER"],
    "customProperties": {
      "preferred-font": "Roboto, sans-serif",
      "color-primary": "var(--palette-blue-500)"
    }
  }
}

Run the build step:

npm run toolbox

Import the generated CSS in src/index.js:

import 'react-toolbox/react-toolbox.theme.css';

Build & Run

Development

Import components individually for optimal tree-shaking:

import React from 'react';
import { Button } from 'react-toolbox/lib/button';
import { Input } from 'react-toolbox/lib/input';

const App = () => (
  <div>
    <Button label="Click Me" raised primary />
    <Input type="text" label="Name" />
  </div>
);

export default App;

Note for CRA users: Use deep imports to avoid CSS loader issues:

// Instead of:
// import { Button } from 'react-toolbox/lib/button';

// Use:
import Button from 'react-toolbox/lib/button/Button';

Start the development server:

npm start
# or
yarn start

Production Build

Build optimized bundle:

npm run build
# or
yarn build

Ensure your production webpack configuration handles CSS extraction (MiniCssExtractPlugin) for optimal performance.

Deployment

Static Hosting (Recommended)

Deploy applications using React Toolbox to static hosting platforms:

Netlify:

# Build command
npm run build

# Publish directory
build/

Vercel:

vercel --prod

GitHub Pages:

Use gh-pages package:

npm install --save-dev gh-pages

Add to package.json:

{
  "scripts": {
    "predeploy": "npm run build",
    "deploy": "gh-pages -d build"
  }
}

NPM Publishing (Library Contributions)

If extending React Toolbox or publishing themed versions:

# Build library
npm run build:lib

# Publish to npm
npm publish

Ensure files array in package.json includes only necessary build artifacts.

Troubleshooting

CSS Modules Not Loading

Symptom: Components render without styles (unstyled HTML elements).

Solution: Verify webpack CSS loader configuration includes modules: true:

{
  loader: 'css-loader',
  options: { modules: true }
}

For CRA, ensure you ran react-toolbox-themr and imported the generated CSS file.

PostCSS Build Errors

Symptom: Unknown word or Unexpected token errors in .css files.

Solution: Ensure postcss-loader is included in the webpack chain after css-loader. Verify postcss-preset-env is installed and configured in postcss.config.js.

Import Errors in CRA

Symptom: Module not found: Can't resolve 'react-toolbox/lib/button' or CSS loader errors.

Solution: Use deep imports to the component file directly:

import Button from 'react-toolbox/lib/button/Button';
import buttonTheme from 'react-toolbox/lib/button/theme.css';

Or switch to react-toolbox-themr approach.

Theming Not Applied

Symptom: Custom colors or fonts not reflecting.

Solution: When using react-toolbox-themr, ensure custom properties are defined in package.json under reactToolbox.customProperties. For webpack projects, ensure CSS custom properties are processed by PostCSS with preserve: false to convert to static values.

Ripple Effects Not Working

Symptom: Click animations missing on buttons.

Solution: Ensure react-css-themr is installed. Check that theme object is properly passed through context or props. Verify no CSS overrides are disabling overflow: hidden on button containers.