Skip to content

Commit

Permalink
Add SASS support documentation #1007 (#1008)
Browse files Browse the repository at this point in the history
* Add SASS support documentation #1007

* Change SASS section title to more generic label

* Fix link in Table of Contents

* Chain build-css with watch-css script, fix typos

* Update Sass and Less naming style

* Fix wording, remove offensive words

* Slightly rewite
  • Loading branch information
tsironis authored and Timer committed Feb 23, 2017
1 parent 12e8cea commit 645ba66
Showing 1 changed file with 47 additions and 0 deletions.
47 changes: 47 additions & 0 deletions packages/react-scripts/template/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ You can find the most recent version of this guide [here](https://github.com/fac
- [Importing a Component](#importing-a-component)
- [Adding a Stylesheet](#adding-a-stylesheet)
- [Post-Processing CSS](#post-processing-css)
- [Adding a CSS Preprocessor (Sass, Less etc.)](#adding-a-css-preprocessor-sass-less-etc)
- [Adding Images and Fonts](#adding-images-and-fonts)
- [Using the `public` Folder](#using-the-public-folder)
- [Changing the HTML](#changing-the-html)
Expand Down Expand Up @@ -353,6 +354,52 @@ becomes this:

There is currently no support for preprocessors such as Less, or for sharing variables across CSS files.

## Adding a CSS Preprocessor (Sass, Less etc.)

Generally, we recommend that you don’t reuse the same CSS classes across different components. For example, instead of using a `.Button` CSS class in `<AcceptButton>` and `<RejectButton>` components, we recommend creating a `<Button>` component with its own `.Button` styles, that both `<AcceptButton>` and `<RejectButton>` can render (but [not inherit](https://facebook.github.io/react/docs/composition-vs-inheritance.html)).

Following this rule often makes CSS preprocessors less useful, as features like mixins and nesting are replaced by component composition. You can, however, integrate a CSS preprocessor if you find it valuable. In this walkthrough, we will be using Sass, but you can also use Less, or another alternative.

First, let’s install the command-line interface for Sass:

```
npm install node-sass --save-dev
```

Then in `package.json`, add the following lines to `scripts`:

```diff
"scripts": {
+ "build-css": "node-sass src/ -o src/",
+ "watch-css": "npm run build-css && node-sass src/ -o src/ --watch",
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test --env=jsdom",
```

>Note: To use a different preprocessor, replace `build-css` and `watch-css` commands according to your preprocessor’s documentation.
Now you can rename `src/App.css` to `src/App.scss` and run `npm run watch-css`. The watcher will find every Sass file in `src` subdirectories, and create a corresponding CSS file next to it, in our case overwriting `src/App.css`. Since `src/App.js` still imports `src/App.css`, the styles become a part of your application. You can now edit `src/App.scss`, and `src/App.css` will be regenerated.

At this point you might want to remove all CSS files from the source control, and add `src/**/*.css` to your `.gitignore` file. It is generally a good practice to keep the build products outside of the source control.

As a final step, you may find it convenient to run `watch-css` automatically with `npm start`, and run `build-css` as a part of `npm run build`. You can use `&` operator for executing scripts in parallel, and `&&` for executing them sequentially:

```diff
"scripts": {
"build-css": "node-sass src/ -o src/",
"watch-css": "npm run build-css && node-sass src/ -o src/ --watch",
- "start": "react-scripts start",
- "build": "react-scripts build",
+ "start": "react-scripts start & npm run watch-css",
+ "build": "react-scripts build && npm run build-css",
"test": "react-scripts test --env=jsdom",
"eject": "react-scripts eject"
}
```

Now running `npm start` and `npm run build` also builds Sass files. Note that `node-sass` seems to have an [issue recognizing newly created files on some systems](https://github.com/sass/node-sass/issues/1891) so you might need to restart the watcher when you create a file until it’s resolved.

## Adding Images and Fonts

With Webpack, using static assets like images and fonts works similarly to CSS.
Expand Down

0 comments on commit 645ba66

Please sign in to comment.