Update README.md for PostCSS instead of SASS (#1251)
Alex Hisen
Javi Velasco
parent
8e2b688954
commit
9354f4b2c3
209
README.md
209
README.md
|
|
@ -5,7 +5,7 @@
|
|||
|
||||
React Toolbox is a set of [React](http://facebook.github.io/react/) components that implement [Google's Material Design specification](https://material.google.com/). It's powered by [CSS Modules](https://github.com/css-modules/css-modules) and harmoniously integrates with your [webpack](http://webpack.github.io/) workflow, although you can use any other module bundler. You can take a tour through our documentation website and try the components live!
|
||||
|
||||
**Note:** ⚠️ This source code refers to the [future version](https://github.com/react-toolbox/react-toolbox/blob/dev/ROADMAP.md). To check the source for `1.x` go to `master` branch. We are currently writing a migration guide so you can start working with 2.0-beta.x now!
|
||||
**Note:** ⚠️ This source code refers to the [future version](https://github.com/react-toolbox/react-toolbox/blob/dev/ROADMAP.md). To check the source for `1.x` go to `master` branch. There is a [migration guide](https://github.com/react-toolbox/react-toolbox/wiki/Migrating-from-version-1.3-to-2.0) so you can start working with 2.0-beta.x now!
|
||||
|
||||
## Installation
|
||||
|
||||
|
|
@ -17,12 +17,41 @@ $ npm install --save react-toolbox
|
|||
|
||||
## Prerequisites
|
||||
|
||||
React Toolbox uses [CSS Modules](https://github.com/css-modules/css-modules) by default to import stylesheets written in [SASS](http://sass-lang.com/). In case you want to import the components already bundled with CSS, your module bundler should be able to require these SASS modules.
|
||||
React Toolbox uses [CSS Modules](https://github.com/css-modules/css-modules) by default to import stylesheets written using PostCSS/[cssnext](http://cssnext.io/) features. In case you want to import the components already bundled with CSS, your module bundler should be able to require these PostCSS modules.
|
||||
|
||||
Although we recommend [webpack](https://webpack.github.io/), you are free to use whatever module bundler you want as long as it can compile and require SASS files located in your `node_modules`. If you are experiencing require errors, make sure your configuration satisfies this requirement.
|
||||
Although we recommend [webpack](https://webpack.github.io/), you are free to use whatever module bundler you want as long as it can compile and require PostCSS files located in your `node_modules`. If you are experiencing require errors, make sure your configuration satisfies this requirement.
|
||||
|
||||
Of course this is a set of React components so you should be familiar with [React](https://facebook.github.io/react/). If want to customize your components via themes, you may want to take a look to [react-css-themr](https://github.com/javivelasco/react-css-themr) which is used by React Toolbox to make components easily themeable.
|
||||
|
||||
### Setting up PostCSS+cssnext in Webpack:
|
||||
|
||||
```bash
|
||||
npm install postcss-loader --save-dev
|
||||
npm install postcss --save
|
||||
npm install postcss-cssnext --save
|
||||
```
|
||||
|
||||
Configure webpack 1.x loader for .css files to use postcss:
|
||||
```js
|
||||
{
|
||||
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):
|
||||
```js
|
||||
postcss: () => {
|
||||
return [
|
||||
/* eslint-disable global-require */
|
||||
require('postcss-cssnext'),
|
||||
/* eslint-enable global-require */
|
||||
];
|
||||
},
|
||||
```
|
||||
|
||||
## Basic usage
|
||||
|
||||
In this minimal example, we import a `Button` with styles already bundled:
|
||||
|
|
@ -38,7 +67,7 @@ ReactDOM.render(
|
|||
);
|
||||
```
|
||||
|
||||
Take into account that any required style will be included in the final CSS so your final would include `Button` styles in this case. It's more convenient to import components this way (or with raw imports) because if you require from the project root, every stylesheet of React Toolbox will be included, even if you don't use it.
|
||||
Take into account that any required style will be included in the final CSS so your final CSS would include `Button` styles in this case. It's more efficient to import components this way (`from 'react-toolbox/lib/button'`) (or with raw imports) because if you require from the project root (i.e. `from 'react-toolbox'`), every stylesheet of React Toolbox will be included, even if you don't use it.
|
||||
|
||||
## Importing components
|
||||
|
||||
|
|
@ -47,13 +76,13 @@ First let's take a look on how the components are structured in the project. The
|
|||
```
|
||||
|- /app_bar
|
||||
|---- AppBar.js
|
||||
|---- _config.scss
|
||||
|---- config.css
|
||||
|---- index.js
|
||||
|---- readme.md
|
||||
|---- theme.scss
|
||||
|---- theme.css
|
||||
```
|
||||
|
||||
As you can see in the previous block, each folder includes: a Javascript file for each component/subcomponent; a README with documentation, an index Javascript file that imports and injects styles and dependencies for you, a default theme SASS stylesheet and a configuration partial with configuration variables. Depending on whether you want the styles to be directly bundled or not, you can import components in **two** different ways.
|
||||
As you can see in the previous block, each folder includes: a Javascript file for each component/subcomponent; a README with documentation, an index Javascript file that imports and injects styles and dependencies for you, a default theme PostCSS/cssnext stylesheet and a config.css with configuration variables (CSS Custom Properties). Depending on whether you want the styles to be directly bundled or not, you can import components in **two** different ways.
|
||||
|
||||
### Bundled component
|
||||
|
||||
|
|
@ -73,14 +102,14 @@ import { AppBar } from 'react-toolbox/lib/app_bar/AppBar.js';
|
|||
|
||||
## Customizing components
|
||||
|
||||
Every component accepts a `theme` property intended to provide a [CSS Module import object](https://github.com/css-modules/css-modules) that will be used by the component to assign local classnames to its DOM nodes. Therefore, each one implements a documented **classname API**. So if you want to customize a component, you just need to provide a theme object with the appropriated classname mapping.
|
||||
Every component accepts a `theme` property intended to provide a [CSS Module import object](https://github.com/css-modules/css-modules) that will be used by the component to assign local classnames to its DOM nodes. Therefore, each one implements a documented **classname API**. So if you want to customize a component, you just need to provide a theme object with the appropriate classname mapping.
|
||||
|
||||
If the component already has a theme injected, the properties you pass will be merged with the injected theme. In this way, you can **add** classnames to the nodes of a specific component and use them to add or to override styles. For example, if you want to customize the `AppBar` to be purple:
|
||||
|
||||
```js
|
||||
import React from 'react';
|
||||
import { AppBar } from 'react-toolbox/lib/app_bar';
|
||||
import theme from './PurpleAppBar.scss';
|
||||
import theme from './PurpleAppBar.css';
|
||||
|
||||
const PurpleAppBar = (props) => (
|
||||
<AppBar {...props} theme={theme} />
|
||||
|
|
@ -90,97 +119,125 @@ export default PurpleAppBar;
|
|||
|
||||
```
|
||||
|
||||
```scss
|
||||
```css
|
||||
.appBar {
|
||||
background-color: #800080;
|
||||
}
|
||||
```
|
||||
|
||||
In this case we are **adding** styles to an `AppBar` component that already has some styles injected. It works because the component background by default has the same priority as the one we added. There will be cases where the original rule is more restrictive. For those cases you would need to boost priority using the same restrictions as in the original stylesheet. Feel free to take a look into the original themes or just check the selectors you want to override in DevTools.
|
||||
In this case we are **adding** styles to a specific instance of an `AppBar` component that already has its default styles injected. It works because the component background by default has the same priority as the one we added. There will be cases where the original rule is more restrictive. For those cases you would need to boost priority using the same restrictions as in the original stylesheet. Feel free to take a look into the default theme.css files or just check the selectors you want to override in DevTools.
|
||||
|
||||
If the component has no styles injected, you should provide a theme object implementing the full API. You are free to require the CSS Module you want but take into account that every classname is there for a reason. You can either provide a theme via prop or via context as we will see later.
|
||||
If the component has no styles injected, you should provide a theme object implementing the full API. You are free to require the CSS Module you want but take into account that every classname is there for a reason. You can either provide a theme via prop or via context as described in the next section.
|
||||
|
||||
## Theming
|
||||
### Customizing all instances of a component type
|
||||
|
||||
You can afford theming in multiple ways. First of all, you have to understand that React Toolbox stylesheets are written in SASS and configured using the **config** files we saw earlier. Also you may want to check [colors](https://github.com/react-toolbox/react-toolbox/blob/dev/components/_colors.scss) and [globals](https://github.com/react-toolbox/react-toolbox/blob/dev/components/_globals.scss) files to get an overview on the **variables** you have to override to get the results you want.
|
||||
Install [react-css-themr](https://github.com/javivelasco/react-css-themr) with `npm install react-css-themr --save`
|
||||
|
||||
In most scenarios you can get more customized themes by overriding those variables and compiling stylesheets with them. For example, you can create a `_theme.scss` SASS file:
|
||||
Create a CSS Module theme style file for each component type, for example for `Button`:
|
||||
|
||||
```scss
|
||||
@import "~react-toolbox/lib/colors";
|
||||
```css
|
||||
# /css/button.css
|
||||
|
||||
$color-primary: $palette-blue-500;
|
||||
$color-primary-dark: $palette-blue-700;
|
||||
```
|
||||
|
||||
This file should be prepended to each stylesheet compilation which can be achieved in multiple ways.
|
||||
|
||||
### Using SASS Loader
|
||||
|
||||
If you are using [Webpack](http://webpack.github.io/) as module bundler, you are probably using [sass-loader](https://github.com/jtangelder/sass-loader) as well. What we want to do is to prepend to each SASS file compilation a bunch of variables to override. This can be done with the `data` option. For example:
|
||||
|
||||
```js
|
||||
sassLoader: {
|
||||
data: '@import "' + path.resolve(__dirname, 'theme/_theme.scss') + '";'
|
||||
.button {
|
||||
text-transform: uppercase;
|
||||
}
|
||||
```
|
||||
|
||||
In this case we are prepending the theme import to each SASS compilation so the primary color will be changed in every single stylesheet. If you are not using webpack, maybe your loader still has a similar option. Otherwise, don't worry, there are solutions.
|
||||
|
||||
### Using SASS imports and props
|
||||
|
||||
Remember that you can import components without styles and provide those styles using the theme property. For example, a theme for a button customized with the previous theme file would be like:
|
||||
|
||||
```scss
|
||||
@import "theme.scss";
|
||||
@import "~react-toolbox/lib/button/theme";
|
||||
```
|
||||
|
||||
Then, when you use a button, you can inject the appropriate theme:
|
||||
Create a theme file that imports each component's custom theme style under the special theme key listed in that widgets's documentation, i.e.:
|
||||
|
||||
```js
|
||||
import { Button } from 'react-toolbox/lib/button/Button';
|
||||
import buttonTheme from './theme/button.scss';
|
||||
# theme.js
|
||||
|
||||
const ThemedButton = (props) => (
|
||||
<Button theme={buttonTheme} {...props} />
|
||||
);
|
||||
import RTButton from './css/button.css';
|
||||
import RTDatePicker from './css/datepicker.css';
|
||||
|
||||
export default ThemedButton;
|
||||
```
|
||||
|
||||
With this technique you have to create wrappers for every component, and this is not cool at all... but don't worry, we can provide the theme via context to avoid this.
|
||||
|
||||
### Using SASS imports and context
|
||||
|
||||
This is a good moment to check out [react-css-themr](http://github.com/javivelasco/react-css-themr) if you still didn't. Every component in React Toolbox has a key assigned that can be used to provide a default CSS Module. You can create a theme like:
|
||||
|
||||
```js
|
||||
export default {
|
||||
RTRipple: require('./ripple.scss'),
|
||||
RTButton: require('./button.scss')
|
||||
}
|
||||
RTButton, RTDatePicker,
|
||||
};
|
||||
```
|
||||
|
||||
Check for each component what key uses. Then, when you have a theme object fully imported and customized for each component your application uses, you can use it like we list here:
|
||||
Wrap your component tree with ThemeProvider at the desired level in your component hierarchy. You can maintain different themes, each importing differently styled css files \(i.e. `import RTButton from './css/adminAreaButton.css'`\) and can provide each one at different points in the tree.
|
||||
|
||||
```js
|
||||
import React from 'react';
|
||||
import { render } from 'react-dom';
|
||||
import { ThemeProvider } from 'react-css-themr';
|
||||
import theme from './theme/theme.js';
|
||||
import App from './App.js';
|
||||
import theme from './theme';
|
||||
|
||||
render(
|
||||
<ThemeProvider theme={theme}>
|
||||
<App />
|
||||
</ThemeProvider>
|
||||
, document.getElementById('app'))
|
||||
class App extends React.Component {
|
||||
render() {
|
||||
return (
|
||||
<ThemeProvider theme={theme}>
|
||||
<div>
|
||||
...
|
||||
</div>
|
||||
</ThemeProvider>
|
||||
);
|
||||
}
|
||||
}
|
||||
export default App;
|
||||
```
|
||||
|
||||
A couple of things here. First you need to use raw components to get this styles properly applied. Second, you have to add dependency themes by yourself. For example, the `Button` requires `Ripple` so you have to provide styles for both of them.
|
||||
## Theming (configuration variables)
|
||||
|
||||
Also, recall that all components accept a theme verifying required classNames but there may be some missing. If any property is missing you can check the selectors you want to override straight in the DevTools.
|
||||
You can apply theming in multiple ways. First of all, you have to understand that React Toolbox stylesheets are written using PostCSS with cssnext features and use CSS Custom Properties from the **config** files we saw earlier. In addition, there are some global CSS Properties imported by each component: [colors](https://github.com/react-toolbox/react-toolbox/blob/dev/components/colors.css) and [variables](https://github.com/react-toolbox/react-toolbox/blob/dev/components/variables.css). You can override both the global and component-specific **variables** to get the results you want using one of the methods below.
|
||||
|
||||
### Settings configuration variables in JavaScript
|
||||
|
||||
You can override both the global and component-specific CSS Custom Properties at build-time by supplying an object with these variable names and your desired values to the PostCSS customProperties plugin. i.e. if using postcss-next in webpack:
|
||||
|
||||
```js
|
||||
|
||||
// This can also be stored in a separate file:
|
||||
const reactToolboxVariables = {
|
||||
'color-text': '#444548',
|
||||
/* Note that you can use global colors and variables */
|
||||
'color-primary': 'var(--palette-blue-500)',
|
||||
'button-height': '30px',
|
||||
};
|
||||
|
||||
// webpack's config object:
|
||||
const config = {
|
||||
...
|
||||
postcss: () => {
|
||||
return [
|
||||
/* eslint-disable global-require */
|
||||
require('postcss-cssnext')({
|
||||
features: {
|
||||
customProperties: {
|
||||
variables: reactToolboxVariables,
|
||||
},
|
||||
},
|
||||
}),
|
||||
/* optional - see next section */
|
||||
require('postcss-modules-values'),
|
||||
/* eslint-enable global-require */
|
||||
];
|
||||
},
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### Settings configuration variables using CSS Module Values
|
||||
|
||||
Instead of using a JavaScript object for variables, you can use [CSS Module Values](https://github.com/css-modules/css-modules/blob/master/docs/values-variables.md) (`npm install postcss-modules-values --save`) and the [modules-values-extract](https://github.com/alexhisen/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.:
|
||||
|
||||
```css
|
||||
# variables.css
|
||||
|
||||
@value buttonPrimaryBackgroundColor: #9c3990;
|
||||
```
|
||||
|
||||
```js
|
||||
import styleVariables from './css/variables.css';
|
||||
|
||||
styleVariables.buttonPrimaryBackgroundColor
|
||||
```
|
||||
|
||||
In [this demo project](https://github.com/alexhisen/mobx-forms-demo), 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](https://github.com/alexhisen/mobx-forms-demo/blob/master/webpack.config.js). In the demo project, variables that are not specific to a particular component are in [variables.css](https://github.com/alexhisen/mobx-forms-demo/blob/master/src/css/variables.css) and button-specific variables are in [button.css](https://github.com/alexhisen/mobx-forms-demo/blob/master/src/css/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!**
|
||||
|
||||
## Roboto Font and Material Design Icons
|
||||
|
||||
|
|
@ -194,7 +251,9 @@ The only requirement for SSR is to be able to require ES6 and CSS Modules in the
|
|||
|
||||
## Examples
|
||||
|
||||
For now we have a [repository example](https://github.com/react-toolbox/react-toolbox-example) demonstrating configuration and some basic customization. For now it's not using SSR rendering but it shouldn't be difficult to implement an example so it will come soon. Feel free to PR your example project or to add some use cases to the repository.
|
||||
For now we have a [1.x repository example](https://github.com/react-toolbox/react-toolbox-example) demonstrating configuration and some basic customization. It hasn't yet been updated for 2.0! For now it's not using SSR rendering but it shouldn't be difficult to implement an example so it will come soon. Feel free to PR your example project or to add some use cases to the repository:
|
||||
|
||||
2.x demo project - https://github.com/alexhisen/mobx-forms-demo
|
||||
|
||||
## TypeScript
|
||||
|
||||
|
|
@ -223,7 +282,11 @@ Local documentation will then be available at `http://localhost:8081/`.
|
|||
|
||||
## Extensions
|
||||
|
||||
We don't officially support components that are not covered by [Google Material Design](https://www.google.com/design/spec/material-design/introduction.html). If you want to implement some complementary component feel free to open a PR adding your a link in this section. For now you can check [on github: react-toolbox-additions](https://github.com/MaximKomlev/react-toolbox-additions) and [on npm: react-toolbox-additions](https://www.npmjs.com/package/react-toolbox-additions).
|
||||
We don't officially support components that are not covered by [Google Material Design](https://www.google.com/design/spec/material-design/introduction.html). If you want to implement some complementary component feel free to open a PR adding your a link in this section:
|
||||
|
||||
[on github: react-toolbox-additions](https://github.com/MaximKomlev/react-toolbox-additions) and [on npm: react-toolbox-additions](https://www.npmjs.com/package/react-toolbox-additions).
|
||||
|
||||
Form generation and validation using React-Toolbox form widgets - [mobx-schema-form](https://github.com/alexhisen/mobx-schema-form)
|
||||
|
||||
## Support
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue