generator-react-zeal

generator-react-zeal

Yeoman generator for Zeal's React boilerplate

Expected to be used in the root of a Rails or Phoenix project configured with the Zeal client app strategy.

Installation

# Install globally the yo cli as well as this generator
npm install -g yo generator-react-zeal

Usage

generator-react-zeal is a yeoman generator and follows the usage pattern commonly found with the yo cli.

# Create new directory and `cd` into it
mkdir myApp && cd myApp

# Run the generator
yo react-zeal

Voila! Now craft with React.

Example

Checkout our usage in the context of Phoenix app - https://github.com/CodingZeal/phoenix-react-apollo-demo

Context

This generator has a devDependency of @zeal/react-scripts which is a fork of the "react CLI" from facebook. This fork marches closely in step with facebook's version with some differences in configuration. These changes support some more advanced webpack features as well as plug-and-play with frameworks like Rails and Phoenix.

The features we have added support for include:

• CSS Modules
• SASS

Thus you can import .scss files into your components like so

import styles from './styles.scss'

...

<div className={styles.foo}>...</div>

In order to better support usage inside Rails etc we have moved the public directory inside the client directory. Thus the frameworks' root will not be cluttered with anything other than the client directory. The generated app will run with npm start and you can still develop on localhost:3000 if you are not in the context of a larger framework.

React Toolbox

The generator installs by default React Toolbox which is a set of Material Design components. At Zeal we have found this project to be an excellent starting point for many common UI patterns. You can of-course ignore it and or remove it from the generated app if you are so inclined.

Using Customizable React Toolbox Components

To make for the most flexibility when dealing with React Toolbox we recommend following the pattern of manually adding and exporting the desired components theme. Then instead of importing the pre-themed component from react-toolbox, import the un-themed version. Don't worry, if you have exported the theme manually it will still have the default theme, and now you will have more flexibility in terms of overriding theme defaults.

For example you would like to use the button component from react-toolbox and would like to override the default primary color. You will want to import / export that button's theme from react-toolbox along with a hook for your customization.

In the client/styles/react-toolbox directory create a new file called button.scss. In button.scss first import your apps global styles;

@import '~/styles/globals';

Then import the the buttons theme from react-toolbox;

@import '~/styles/globals';
@import '~react-toolbox/lib/button/theme';

Lastly in client/styles/react-toolbox/index.js export your custom theme file.

export RTButton from './button.scss'

This allows the apps ThemeProvider context to pass this information to react-toolbox. By default we follow this pattern for ProgressBar as an example.

Great, you now have hooked into the theme provider. Now you just have to import the un-themed version of the component from react-toolbox and let the theme provider do the rest.

In your component import like this;

import Button from 'react-toolbox/lib/button/Button'

It is important not to import the themed version from react toolbox otherwise your hard work to allow for greater flexibility will be lost, for example if you did this...

import { Button, IconButton } from 'react-toolbox/lib/button'

The button would not be affected by the apps theme provider.

Once you have imported the Button component that will respond to the theme provider, you can set the $color-primary in several different ways depending on your needs. Generally $color-primary will be inherited from the react-toolbox default configuration. You can override it globally in client/styles/_globals.scss which will make all react-toolbox components use that configuration for $color-primary. You can see in the generated app we have set the $color-primary to the $zeal-orange color defined in the _colors.scss file. If however you would like to override that color for a specific component, we recommend creating a new component that imports the button, applies a custom theme, and then exports the button for the rest of the app to use.

Style Dependencies

Many of the React Toolbox components have styles which depend on other components from React Toolbox having their styles present. For example some of the react components have an option for the 'ripple' effect. So, if you would like to set that property on a list item or a button etc, you should be sure to import / export the ripple theme as described above.

Themr

The generator installs by default React CSS Themr which allows the decorating of components with a simple mechanism for easily "theming" the components.

Creating a "Themed" Component

Creating a themed component is easy, and builds of the concept of composing css modules. Apply the decorator to a component on export passing a css module and receiving the incoming theme as props.

// MyComponent/theme.scss
.myComponent {
  background-color: red
}

// MyComponent/index.js
import { themr } from 'react-css-themr'

import myComponentTheme from './theme.scss'

function MyComponent({ theme }) {
  return (
    <div className={theme.myComponent}>Hello World</div>
  )
}

export default themr('', myComponentTheme)(MyComponent)

In the above example we import the styles object from theme.scss and pass it as the second argument to the themr decorator. Themr will pass that object into our wrapped component as theme on the components props. When this component is used, theme can be passed to the component and the information in the incoming style object will be merged with "default" theme. There are options that can be passed in regards to the approach for merging the themes, and you can read up on them here. To illustrate passing a theme override;

// ParentComponent/theme.scss
.myComponent {
  background-color: blue
}

// MyComponent/index.js
import { themr } from 'react-css-themr'

import MyComponent from './MyComponent'
import myParentComponentTheme from './theme.scss'

function MyParentComponent({ theme }) {
  return <MyComponent theme={theme} />
}

export default themr('', myParentComponentTheme)(MyParentComponent)

Above the parent component is overriding the background-color by passing custom theme information to the themed component. We generally wrap all components in themr, which allows for great flexibility in using our components elsewhere in our apps.