Suggest sass instead of node-sass package (#10779)

Author: andrewywong

docusaurus/docs/adding-a-sass-stylesheet.md

@@ -10,42 +10,36 @@ Generally, we recommend that you don’t reuse the same CSS classes across diffe
 
 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.
 
-To use Sass, first install `node-sass`:
+To use Sass, first install `sass`:
 
 ```sh
-$ npm install node-sass --save
-$ # or
-$ yarn add node-sass
+$ npm install sass
+# or
+$ yarn add sass
 ```
 
 Now you can rename `src/App.css` to `src/App.scss` and update `src/App.js` to import `src/App.scss`.
 This file and any other file will be automatically compiled if imported with the extension `.scss` or `.sass`.
 
-To share variables between Sass files, you can use Sass imports. For example, `src/App.scss` and other component style files could include `@import "./shared.scss";` with variable definitions.
+To share variables between Sass files, you can use Sass's [`@use` rule](https://sass-lang.com/documentation/at-rules/use). For example, `src/App.scss` and other component style files could include `@use "./shared.scss";` with variable definitions.
 
 This will allow you to do imports like
 
 ```scss
-@import 'styles/_colors.scss'; // assuming a styles directory under src/
-@import '~nprogress/nprogress'; // importing a css file from the nprogress node module
+@use 'styles/_colors.scss'; // assuming a styles directory under src/
+@use '~nprogress/nprogress'; // loading a css file from the nprogress node module
 ```
 
-> **Note:** You must prefix imports from `node_modules` with `~` as displayed above.
+> **Note:** You can prefix paths with `~`, as displayed above, to resolve modules from `node_modules`.
 
-`node-sass` also supports the `SASS_PATH` variable.
+`sass` also supports the `SASS_PATH` variable.
 
-To use imports relative to a path you specify, and from `node_modules` without adding the `~` prefix, you can add a [`.env` file](https://github.com/facebook/create-react-app/blob/master/docusaurus/docs/adding-custom-environment-variables.md#adding-development-environment-variables-in-env) at the project root with the variable `SASS_PATH=node_modules:src`. To specify more directories you can add them to `SASS_PATH` separated by a `:` like `path1:path2:path3`.
+To use imports relative to a path you specify, you can add a [`.env` file](https://github.com/facebook/create-react-app/blob/master/docusaurus/docs/adding-custom-environment-variables.md#adding-development-environment-variables-in-env) at the project root with the path specified in the `SASS_PATH` environment variable. To specify more directories you can add them to `SASS_PATH` separated by a `:` like `path1:path2:path3`.
 
-If you set `SASS_PATH=node_modules:src`, this will allow you to do imports like
-```scss
-@import 'styles/colors'; // assuming a styles directory under src/, where _colors.scss partial file exists.
-@import 'nprogress/nprogress'; // importing a css file from the nprogress node module
-```
-
-> **Note:** For windows operating system, use below syntax
+> **Note:** For the Windows operating system, separate your paths by semicolons.
 >
 > ```
-> SASS_PATH=./node_modules;./src
+> SASS_PATH=path1;path2;path3
 > ```
 
 > **Tip:** You can opt into using this feature with [CSS modules](adding-a-css-modules-stylesheet.md) too!
@@ -61,3 +55,14 @@ If you set `SASS_PATH=node_modules:src`, this will allow you to do imports like
 > module.file_ext=.sass
 > module.file_ext=.scss
 > ```
+
+> **Note:** LibSass and the packages built on top of it, including Node Sass, are [deprecated](https://sass-lang.com/blog/libsass-is-deprecated).
+> If you're a user of Node Sass, you can migrate to Dart Sass by replacing `node-sass` in your `package.json` file with `sass` or by running the following commands:
+>
+> ```sh
+> $ npm uninstall node-sass
+> $ npm install sass
+> # or
+> $ yarn remove node-sass
+> $ yarn add sass
+> ```

docusaurus/docs/adding-bootstrap.md

@@ -8,7 +8,7 @@ While you don’t have to use any specific library to integrate Bootstrap with R
 Each project's respective documentation site has detailed instructions for installing and using them. Both depend on the Bootstrap css file so install that as well:
 
 ```sh
-npm install --save bootstrap
+npm install bootstrap
 ```
 
 Alternatively you may use `yarn`:
@@ -33,19 +33,19 @@ Sometimes you might need to tweak the visual styles of Bootstrap (or equivalent
 
 As of `react-scripts@2.0.0` you can import `.scss` files. This makes it possible to use a package's built-in Sass variables for global style preferences.
 
-To enable `scss` in Create React App you will need to install `node-sass`.
+To enable `scss` in Create React App you will need to install `sass`.
 
 ```sh
-npm install --save node-sass
+npm install sass
 ```
 
 Alternatively you may use `yarn`:
 
 ```sh
-yarn add node-sass
+yarn add sass
 ```
 
-To customize Bootstrap, create a file called `src/custom.scss` (or similar) and import the Bootstrap source stylesheet. Add any overrides _before_ the imported file(s). You can reference [Bootstrap's documentation](https://getbootstrap.com/docs/4.1/getting-started/theming/#css-variables) for the names of the available variables.
+To customize Bootstrap, create a file called `src/custom.scss` (or similar) and import the Bootstrap source stylesheet. Add any overrides _before_ the imported file(s). You can reference [Bootstrap's documentation](https://getbootstrap.com/docs/4.6/getting-started/theming/#variable-defaults) for the names of the available variables.
 
 ```scss
 // Override default variables before the import
@@ -55,7 +55,7 @@ $body-bg: #000;
 @import '~bootstrap/scss/bootstrap.scss';
 ```
 
-> **Note:** You must prefix imports from `node_modules` with `~` as displayed above.
+> **Note:** You can prefix paths with `~`, as displayed above, to resolve modules from `node_modules`.
 
 Finally, import the newly created `.scss` file instead of the default Bootstrap `.css` in the beginning of your `src/index.js` file, for example:
 

packages/react-dev-utils/formatWebpackMessages.js

@@ -73,10 +73,10 @@ function formatMessage(message) {
   }
 
   // Add helpful message for users trying to use Sass for the first time
-  if (lines[1] && lines[1].match(/Cannot find module.+node-sass/)) {
-    lines[1] = 'To import Sass files, you first need to install node-sass.\n';
+  if (lines[1] && lines[1].match(/Cannot find module.+sass/)) {
+    lines[1] = 'To import Sass files, you first need to install sass.\n';
     lines[1] +=
-      'Run `npm install node-sass` or `yarn add node-sass` inside your workspace.';
+      'Run `npm install sass` or `yarn add sass` inside your workspace.';
   }
 
   message = lines.join('\n');

test/fixtures/webpack-message-formatting/index.test.js

@@ -100,7 +100,7 @@ test('helps when users tries to use sass', async () => {
   expect(stdout).toBeFalsy();
   // TODO: Snapshots differ between Node 10/12 as the call stack log output has changed.
   expect(stderr).toContain(
-    'To import Sass files, you first need to install node-sass.'
+    'To import Sass files, you first need to install sass.'
   );
 });