From 645ba66d41a9c537f5514994893daacdbfbafb23 Mon Sep 17 00:00:00 2001
From: Dimitris Tsironis <tsironis.dimitris@gmail.com>
Date: Sun, 12 Feb 2017 02:38:59 +0200
Subject: [PATCH] Add SASS support documentation #1007 (#1008)

* 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
---
 packages/react-scripts/template/README.md | 47 +++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/packages/react-scripts/template/README.md b/packages/react-scripts/template/README.md
index c30fb9d13ee..00e4f248131 100644
--- a/packages/react-scripts/template/README.md
+++ b/packages/react-scripts/template/README.md
@@ -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)
@@ -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.