react-toolbox-build4server

react-toolbox-build4server builds react-toolbox in such a way that it's components can be required and used in node - most likely for server-side rendered webapps - without having to depend on webpack to build your entire server-side project.

When to use?

react-toolbox is a material-design components library for React. One of the great things about it is that it uses CSS for it's styling which allows the user to fully customize the appearance of any of the components it provides. However, the way the components' code uses CSS is a bit special (CSS modules directly required from JS code) and requires your project to be built with webpack which would do it's magic behind the scenes to make everything work.

All this is perfectly fine for your client-side web apps, but what if you wish to build an isomorphic application with server-side rendering and don't like the idea of packing up all of your server-side code into a single file?

This is where things can get pretty tricky and where react-toolbox-build4server module tries to help ...

Dependencies

• Gulp

$ npm install -g gulp

Install

$ npm install react-toolbox-build4server

Major and minor version of the react-toolbox-build4server module will match the version of react-toolbox it is building.

Example

Example project with server-side rendered react-toolbox components, using react-toolbox-build4server can be found here.

Use pre-built react-toolbox components

After installing you can just import and use any of the components provided by react-toolbox.

import { Button, Input } from 'react-toolbox-build4server';
    

Use as part of your own build process

Module's internal gulpfile.js is written in such a way that it can be imported into your own gulpfile.js and used to define react-toolbox build tasks for you. To setup a react-toolbox build task inside your own gulpfile.js you'll need to require and run react-toolbox-build4server's gulpfile.js, passing in following arguments:

• A reference to your own instance of gulp
• A path of react-toolbox module you want to build
• A target path the build task should output to
• [Optional] An array of paths to .scss files you wish to prepend to react-toolbox internal .scss files. This allow you to change any of the SASS variables used by any of the components.

// Include gulp build task(s) from 'react-toolbox-build4server' module
require( path.join(__dirname, './node_modules/react-toolbox-build4server/gulpfile') )(      
  // Pass your gulp instalnce to create tasks with
  gulp,      
  // Pass location of your react-toolbox directory
  path.join(__dirname, './node_modules/react-toolbox'),
  // Pass target location for your build
  path.join(__dirname, './react-toolbox'),
  // Pass any additional .scss files you'd like to prepend to react-toolbox styles (probably SASS variables)
  [
    path.join(__dirname, './src/style/react-toolbox-config.scss')
  ]
);  
    

Now you can run a newly exposed gulp task to build react-toolbox components by running:

$ gulp react-toolbox-build4server

Styling

Your client-side application will need to include styles for the components it is using.

If you're just using components directly from the react-toolbox-build4server module, style.css is located at:

./node_modules/react-toolbox-build4server/react-toolbox/style.css

If you're using react-toolbox-build4server as part of your own build process, style.css will be located at:

[build-target-path]/style.css

Build your own ...

Internal structure

If your project has it's own build process, and you're including react-toolbox-build4server as part of it, it's target directory will contain react-toolbox components in few different versions in different stages of being pre-build for you. Depending on your project's build process, you can choose the one that fits you best ...

Prebuilt JSX components

Standard way of including components from the react-toolbox-build4server module is in their fully pre-built form:

import { Button, Input } from 'react-toolbox-build4server';
    

The code you're including here has already had require([scss file]) calls from JS code handled and it's original ES6/JSX syntax transcompiled. No further steps are needed for node to be able to execute the imported code.

Building JSX components yourself

For use-cases where your project's build procedure already has it's own ES6/JSX build step, you might want to include react-toolbox components that are still in an ES6/JSX format and avoid re-building already built code. In this case, you can include components as:

import { Button, Input } from 'react-toolbox-build4server/react-toolbox/jsx';
    

If you decide to include components in this form, it is up to you to make sure they compile properly - all react-toolbox-build4server does for you in this case is handles require([scss file]) calls from JS code.

Prebuilt .css Styling

When including components' styling into your client-side application, you can simply include the pre-built style.css file. In this case, the file will use default style configuration and any changes you wish to make to the styling you'll need to do in a separate .css file with overriding rules for every single component that the change should apply to.

*[data-react-toolbox="button"] {
    background-color: red;
}

Building .scss Styling

Alternatively, you can have your own SASS build procedure into which you import .scss files from the react-toolbox-build4server module. Should you decide for this approach, you'll get the benefit of being able to reconfigure the styling. You'll want to include react-toolbox-build4server's style.scss file into your own SASS file, like this:

@import "./node_modules/react-toolbox-build4server/react-toolbox/style.scss";

This style.scss file already imports style-config.scss file, which you might want to use as a templates for for your own configuration .scss file - just copy the file to your local project, modify any of the variables you need, and drop the "!default" sufix on the line you modified. When you're done, just include your new custom configuration file before style.scss in your parent SASS file, like this:

@import "./style-custom-config.scss";
@import "./node_modules/react-toolbox-build4server/react-toolbox/style.scss";

License

MIT