From 49da90a9fed371fcadbeacc6142198ab314a9138 Mon Sep 17 00:00:00 2001 From: andrewywong Date: Sun, 4 Apr 2021 14:40:31 -0500 Subject: [PATCH 1/2] Update docs and webpack messages to reference sass instead of node-sass and add note on how to migrate projects from node-sass to sass --- docusaurus/docs/adding-a-sass-stylesheet.md | 21 ++++++++++++++----- docusaurus/docs/adding-bootstrap.md | 6 +++--- .../react-dev-utils/formatWebpackMessages.js | 6 +++--- .../webpack-message-formatting/index.test.js | 2 +- 4 files changed, 23 insertions(+), 12 deletions(-) diff --git a/docusaurus/docs/adding-a-sass-stylesheet.md b/docusaurus/docs/adding-a-sass-stylesheet.md index 1ba76380e6a..7100ede3c5a 100644 --- a/docusaurus/docs/adding-a-sass-stylesheet.md +++ b/docusaurus/docs/adding-a-sass-stylesheet.md @@ -10,12 +10,12 @@ 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`. @@ -32,7 +32,7 @@ This will allow you to do imports like > **Note:** You must prefix imports from `node_modules` with `~` as displayed above. -`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`. @@ -61,3 +61,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 +> ``` \ No newline at end of file diff --git a/docusaurus/docs/adding-bootstrap.md b/docusaurus/docs/adding-bootstrap.md index 1bbffda0854..7615f46c747 100644 --- a/docusaurus/docs/adding-bootstrap.md +++ b/docusaurus/docs/adding-bootstrap.md @@ -33,16 +33,16 @@ 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. diff --git a/packages/react-dev-utils/formatWebpackMessages.js b/packages/react-dev-utils/formatWebpackMessages.js index f459ea98ccc..30e5614c27a 100644 --- a/packages/react-dev-utils/formatWebpackMessages.js +++ b/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'); diff --git a/test/fixtures/webpack-message-formatting/index.test.js b/test/fixtures/webpack-message-formatting/index.test.js index 977bf277a5e..f813a1eecdf 100644 --- a/test/fixtures/webpack-message-formatting/index.test.js +++ b/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.' ); }); From 277cfd6fdaf092c12d4b9e00bf037398a5cac06b Mon Sep 17 00:00:00 2001 From: andrewywong Date: Sun, 4 Apr 2021 21:59:01 -0500 Subject: [PATCH 2/2] Update docs to use latest Sass syntax and not require tilde prefix for node_modules imports --- docusaurus/docs/adding-a-sass-stylesheet.md | 20 +++++++------------- docusaurus/docs/adding-bootstrap.md | 6 +++--- 2 files changed, 10 insertions(+), 16 deletions(-) diff --git a/docusaurus/docs/adding-a-sass-stylesheet.md b/docusaurus/docs/adding-a-sass-stylesheet.md index 7100ede3c5a..fb1a23af00b 100644 --- a/docusaurus/docs/adding-a-sass-stylesheet.md +++ b/docusaurus/docs/adding-a-sass-stylesheet.md @@ -21,31 +21,25 @@ $ 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`. `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! diff --git a/docusaurus/docs/adding-bootstrap.md b/docusaurus/docs/adding-bootstrap.md index 7615f46c747..7ca91c07fd2 100644 --- a/docusaurus/docs/adding-bootstrap.md +++ b/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`: @@ -45,7 +45,7 @@ Alternatively you may use `yarn`: 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: