source: trip-planner-front/node_modules/sass-loader/README.md@ bdd6491

Last change on this file since bdd6491 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 19.6 KB
Line 
1<div align="center">
2 <img height="170"
3 src="https://worldvectorlogo.com/logos/sass-1.svg">
4 <a href="https://github.com/webpack/webpack">
5 <img width="200" height="200"
6 src="https://webpack.js.org/assets/icon-square-big.svg">
7 </a>
8</div>
9
10[![npm][npm]][npm-url]
11[![node][node]][node-url]
12[![deps][deps]][deps-url]
13[![tests][tests]][tests-url]
14[![coverage][cover]][cover-url]
15[![chat][chat]][chat-url]
16[![size][size]][size-url]
17
18# sass-loader
19
20Loads a Sass/SCSS file and compiles it to CSS.
21
22## Getting Started
23
24To begin, you'll need to install `sass-loader`:
25
26```console
27npm install sass-loader sass webpack --save-dev
28```
29
30`sass-loader` requires you to install either [Dart Sass](https://github.com/sass/dart-sass) or [Node Sass](https://github.com/sass/node-sass) on your own (more documentation can be found below).
31
32This allows you to control the versions of all your dependencies, and to choose which Sass implementation to use.
33
34> ℹ️ We highly recommend using [Dart Sass](https://github.com/sass/dart-sass).
35
36> ⚠ [Node Sass](https://github.com/sass/node-sass) does not work with [Yarn PnP](https://classic.yarnpkg.com/en/docs/pnp/) feature and doesn't support [@use rule](https://sass-lang.com/documentation/at-rules/use).
37
38Chain the `sass-loader` with the [css-loader](https://github.com/webpack-contrib/css-loader) and the [style-loader](https://github.com/webpack-contrib/style-loader) to immediately apply all styles to the DOM or the [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin) to extract it into a separate file.
39
40Then add the loader to your Webpack configuration. For example:
41
42**app.js**
43
44```js
45import "./style.scss";
46```
47
48**style.scss**
49
50```scss
51$body-color: red;
52
53body {
54 color: $body-color;
55}
56```
57
58**webpack.config.js**
59
60```js
61module.exports = {
62 module: {
63 rules: [
64 {
65 test: /\.s[ac]ss$/i,
66 use: [
67 // Creates `style` nodes from JS strings
68 "style-loader",
69 // Translates CSS into CommonJS
70 "css-loader",
71 // Compiles Sass to CSS
72 "sass-loader",
73 ],
74 },
75 ],
76 },
77};
78```
79
80Finally run `webpack` via your preferred method.
81
82### Resolving `import` at-rules
83
84Webpack provides an [advanced mechanism to resolve files](https://webpack.js.org/concepts/module-resolution/).
85
86The `sass-loader` uses Sass's custom importer feature to pass all queries to the Webpack resolving engine.
87Thus you can import your Sass modules from `node_modules`.
88
89```scss
90@import "bootstrap";
91```
92
93Using `~` is deprecated and can be removed from your code (**we recommend it**), but we still support it for historical reasons.
94Why can you remove it? The loader will first try to resolve `@import` as a relative path. If it cannot be resolved, then the loader will try to resolve `@import` inside [`node_modules`](https://webpack.js.org/configuration/resolve/#resolvemodules).
95
96Prepending module paths with a `~` tells webpack to search through [`node_modules`](https://webpack.js.org/configuration/resolve/#resolvemodules).
97
98```scss
99@import "~bootstrap";
100```
101
102It's important to prepend it with only `~`, because `~/` resolves to the home directory.
103Webpack needs to distinguish between `bootstrap` and `~bootstrap` because CSS and Sass files have no special syntax for importing relative files.
104Writing `@import "style.scss"` is the same as `@import "./style.scss";`
105
106### Problems with `url(...)`
107
108Since Sass implementations don't provide [url rewriting](https://github.com/sass/libsass/issues/532), all linked assets must be relative to the output.
109
110- If you pass the generated CSS on to the `css-loader`, all urls must be relative to the entry-file (e.g. `main.scss`).
111- If you're just generating CSS without passing it to the `css-loader`, it must be relative to your web root.
112
113You will be disrupted by this first issue. It is natural to expect relative references to be resolved against the `.sass`/`.scss` file in which they are specified (like in regular `.css` files).
114
115Thankfully there are a two solutions to this problem:
116
117- Add the missing url rewriting using the [resolve-url-loader](https://github.com/bholloway/resolve-url-loader). Place it before `sass-loader` in the loader chain.
118- Library authors usually provide a variable to modify the asset path. [bootstrap-sass](https://github.com/twbs/bootstrap-sass) for example has an `$icon-font-path`.
119
120## Options
121
122| Name | Type | Default | Description |
123| :---------------------------------------: | :------------------: | :-------------------------------------: | :---------------------------------------------------------------- |
124| **[`implementation`](#implementation)** | `{Object\|String}` | `sass` | Setup Sass implementation to use. |
125| **[`sassOptions`](#sassoptions)** | `{Object\|Function}` | defaults values for Sass implementation | Options for Sass. |
126| **[`sourceMap`](#sourcemap)** | `{Boolean}` | `compiler.devtool` | Enables/Disables generation of source maps. |
127| **[`additionalData`](#additionaldata)** | `{String\|Function}` | `undefined` | Prepends/Appends `Sass`/`SCSS` code before the actual entry file. |
128| **[`webpackImporter`](#webpackimporter)** | `{Boolean}` | `true` | Enables/Disables the default Webpack importer. |
129
130### `implementation`
131
132Type: `Object | String`
133Default: `sass`
134
135The special `implementation` option determines which implementation of Sass to use.
136
137By default the loader resolve the implementation based on your dependencies.
138Just add required implementation to `package.json` (`sass` or `node-sass` package) and install dependencies.
139
140Example where the `sass-loader` loader uses the `sass` (`dart-sass`) implementation:
141
142**package.json**
143
144```json
145{
146 "devDependencies": {
147 "sass-loader": "^7.2.0",
148 "sass": "^1.22.10"
149 }
150}
151```
152
153Example where the `sass-loader` loader uses the `node-sass` implementation:
154
155**package.json**
156
157```json
158{
159 "devDependencies": {
160 "sass-loader": "^7.2.0",
161 "node-sass": "^5.0.0"
162 }
163}
164```
165
166Beware the situation when `node-sass` and `sass` were installed! By default the `sass-loader` prefers `sass`.
167In order to avoid this situation you can use the `implementation` option.
168
169The `implementation` options either accepts `sass` (`Dart Sass`) or `node-sass` as a module.
170
171#### Object
172
173For example, to use Dart Sass, you'd pass:
174
175```js
176module.exports = {
177 module: {
178 rules: [
179 {
180 test: /\.s[ac]ss$/i,
181 use: [
182 "style-loader",
183 "css-loader",
184 {
185 loader: "sass-loader",
186 options: {
187 // Prefer `dart-sass`
188 implementation: require("sass"),
189 },
190 },
191 ],
192 },
193 ],
194 },
195};
196```
197
198#### String
199
200For example, to use Dart Sass, you'd pass:
201
202```js
203module.exports = {
204 module: {
205 rules: [
206 {
207 test: /\.s[ac]ss$/i,
208 use: [
209 "style-loader",
210 "css-loader",
211 {
212 loader: "sass-loader",
213 options: {
214 // Prefer `dart-sass`
215 implementation: require.resolve("sass"),
216 },
217 },
218 ],
219 },
220 ],
221 },
222};
223```
224
225Note that when using `sass` (`Dart Sass`), **synchronous compilation is twice as fast as asynchronous compilation** by default, due to the overhead of asynchronous callbacks.
226To avoid this overhead, you can use the [fibers](https://www.npmjs.com/package/fibers) package to call asynchronous importers from the synchronous code path.
227
228We automatically inject the [`fibers`](https://github.com/laverdet/node-fibers) package (setup `sassOptions.fiber`) for `Node.js` less v16.0.0 if is possible (i.e. you need install the [`fibers`](https://github.com/laverdet/node-fibers) package).
229
230> Fibers is not compatible with `Node.js` v16.0.0 or later ([see introduction to readme](https://github.com/laverdet/node-fibers)).
231
232**package.json**
233
234```json
235{
236 "devDependencies": {
237 "sass-loader": "^7.2.0",
238 "sass": "^1.22.10",
239 "fibers": "^4.0.1"
240 }
241}
242```
243
244You can disable automatically injecting the [`fibers`](https://github.com/laverdet/node-fibers) package by passing a `false` value for the `sassOptions.fiber` option.
245
246**webpack.config.js**
247
248```js
249module.exports = {
250 module: {
251 rules: [
252 {
253 test: /\.s[ac]ss$/i,
254 use: [
255 "style-loader",
256 "css-loader",
257 {
258 loader: "sass-loader",
259 options: {
260 implementation: require("sass"),
261 sassOptions: {
262 fiber: false,
263 },
264 },
265 },
266 ],
267 },
268 ],
269 },
270};
271```
272
273You can also pass the `fiber` value using this code:
274
275**webpack.config.js**
276
277```js
278module.exports = {
279 module: {
280 rules: [
281 {
282 test: /\.s[ac]ss$/i,
283 use: [
284 "style-loader",
285 "css-loader",
286 {
287 loader: "sass-loader",
288 options: {
289 implementation: require("sass"),
290 sassOptions: {
291 fiber: require("fibers"),
292 },
293 },
294 },
295 ],
296 },
297 ],
298 },
299};
300```
301
302### `sassOptions`
303
304Type: `Object|Function`
305Default: defaults values for Sass implementation
306
307Options for [Dart Sass](http://sass-lang.com/dart-sass) or [Node Sass](https://github.com/sass/node-sass) implementation.
308
309> ℹ️ The `indentedSyntax` option has `true` value for the `sass` extension.
310
311> ℹ️ Options such as `data` and `file` are unavailable and will be ignored.
312
313> ℹ We recommend not to set the `outFile`, `sourceMapContents`, `sourceMapEmbed`, `sourceMapRoot` options because `sass-loader` automatically sets these options when the `sourceMap` option is `true`.
314
315> ℹ️ Access to the [loader context](https://webpack.js.org/api/loaders/#the-loader-context) inside the custom importer can be done using the `this.webpackLoaderContext` property.
316
317There is a slight difference between the `sass` (`dart-sass`) and `node-sass` options.
318
319Please consult documentation before using them:
320
321- [Dart Sass documentation](https://github.com/sass/dart-sass#javascript-api) for all available `sass` options.
322- [Node Sass documentation](https://github.com/sass/node-sass/#options) for all available `node-sass` options.
323
324#### `Object`
325
326Use and object for the Sass implementation setup.
327
328**webpack.config.js**
329
330```js
331module.exports = {
332 module: {
333 rules: [
334 {
335 test: /\.s[ac]ss$/i,
336 use: [
337 "style-loader",
338 "css-loader",
339 {
340 loader: "sass-loader",
341 options: {
342 sassOptions: {
343 indentWidth: 4,
344 includePaths: ["absolute/path/a", "absolute/path/b"],
345 },
346 },
347 },
348 ],
349 },
350 ],
351 },
352};
353```
354
355#### `Function`
356
357Allows to setup the Sass implementation by setting different options based on the loader context.
358
359```js
360module.exports = {
361 module: {
362 rules: [
363 {
364 test: /\.s[ac]ss$/i,
365 use: [
366 "style-loader",
367 "css-loader",
368 {
369 loader: "sass-loader",
370 options: {
371 sassOptions: (loaderContext) => {
372 // More information about available properties https://webpack.js.org/api/loaders/
373 const { resourcePath, rootContext } = loaderContext;
374 const relativePath = path.relative(rootContext, resourcePath);
375
376 if (relativePath === "styles/foo.scss") {
377 return {
378 includePaths: ["absolute/path/c", "absolute/path/d"],
379 };
380 }
381
382 return {
383 includePaths: ["absolute/path/a", "absolute/path/b"],
384 };
385 },
386 },
387 },
388 ],
389 },
390 ],
391 },
392};
393```
394
395### `sourceMap`
396
397Type: `Boolean`
398Default: depends on the `compiler.devtool` value
399
400Enables/Disables generation of source maps.
401
402By default generation of source maps depends on the [`devtool`](https://webpack.js.org/configuration/devtool/) option.
403All values enable source map generation except `eval` and `false` value.
404
405> ℹ If a `true` the `sourceMap`, `sourceMapRoot`, `sourceMapEmbed`, `sourceMapContents` and `omitSourceMapUrl` from `sassOptions` will be ignored.
406
407**webpack.config.js**
408
409```js
410module.exports = {
411 module: {
412 rules: [
413 {
414 test: /\.s[ac]ss$/i,
415 use: [
416 "style-loader",
417 {
418 loader: "css-loader",
419 options: {
420 sourceMap: true,
421 },
422 },
423 {
424 loader: "sass-loader",
425 options: {
426 sourceMap: true,
427 },
428 },
429 ],
430 },
431 ],
432 },
433};
434```
435
436> ℹ In some rare cases `node-sass` can output invalid source maps (it is a `node-sass` bug).
437
438> > In order to avoid this, you can try to update `node-sass` to latest version or you can try to set within `sassOptions` the `outputStyle` option to `compressed`.
439
440**webpack.config.js**
441
442```js
443module.exports = {
444 module: {
445 rules: [
446 {
447 test: /\.s[ac]ss$/i,
448 use: [
449 "style-loader",
450 "css-loader",
451 {
452 loader: "sass-loader",
453 options: {
454 sourceMap: true,
455 sassOptions: {
456 outputStyle: "compressed",
457 },
458 },
459 },
460 ],
461 },
462 ],
463 },
464};
465```
466
467### `additionalData`
468
469Type: `String|Function`
470Default: `undefined`
471
472Prepends `Sass`/`SCSS` code before the actual entry file.
473In this case, the `sass-loader` will not override the `data` option but just **prepend** the entry's content.
474
475This is especially useful when some of your Sass variables depend on the environment:
476
477#### `String`
478
479```js
480module.exports = {
481 module: {
482 rules: [
483 {
484 test: /\.s[ac]ss$/i,
485 use: [
486 "style-loader",
487 "css-loader",
488 {
489 loader: "sass-loader",
490 options: {
491 additionalData: "$env: " + process.env.NODE_ENV + ";",
492 },
493 },
494 ],
495 },
496 ],
497 },
498};
499```
500
501#### `Function`
502
503##### Sync
504
505```js
506module.exports = {
507 module: {
508 rules: [
509 {
510 test: /\.s[ac]ss$/i,
511 use: [
512 "style-loader",
513 "css-loader",
514 {
515 loader: "sass-loader",
516 options: {
517 additionalData: (content, loaderContext) => {
518 // More information about available properties https://webpack.js.org/api/loaders/
519 const { resourcePath, rootContext } = loaderContext;
520 const relativePath = path.relative(rootContext, resourcePath);
521
522 if (relativePath === "styles/foo.scss") {
523 return "$value: 100px;" + content;
524 }
525
526 return "$value: 200px;" + content;
527 },
528 },
529 },
530 ],
531 },
532 ],
533 },
534};
535```
536
537##### Async
538
539```js
540module.exports = {
541 module: {
542 rules: [
543 {
544 test: /\.s[ac]ss$/i,
545 use: [
546 "style-loader",
547 "css-loader",
548 {
549 loader: "sass-loader",
550 options: {
551 additionalData: async (content, loaderContext) => {
552 // More information about available properties https://webpack.js.org/api/loaders/
553 const { resourcePath, rootContext } = loaderContext;
554 const relativePath = path.relative(rootContext, resourcePath);
555
556 if (relativePath === "styles/foo.scss") {
557 return "$value: 100px;" + content;
558 }
559
560 return "$value: 200px;" + content;
561 },
562 },
563 },
564 ],
565 },
566 ],
567 },
568};
569```
570
571### `webpackImporter`
572
573Type: `Boolean`
574Default: `true`
575
576Enables/Disables the default Webpack importer.
577
578This can improve performance in some cases. Use it with caution because aliases and `@import` at-rules starting with `~` will not work.
579You can pass own `importer` to solve this (see [`importer docs`](https://github.com/sass/node-sass#importer--v200---experimental)).
580
581**webpack.config.js**
582
583```js
584module.exports = {
585 module: {
586 rules: [
587 {
588 test: /\.s[ac]ss$/i,
589 use: [
590 "style-loader",
591 "css-loader",
592 {
593 loader: "sass-loader",
594 options: {
595 webpackImporter: false,
596 },
597 },
598 ],
599 },
600 ],
601 },
602};
603```
604
605## Examples
606
607### Extracts CSS into separate files
608
609For production builds it's recommended to extract the CSS from your bundle being able to use parallel loading of CSS/JS resources later on.
610
611There are two possibilities to extract a style sheet from the bundle:
612
613- [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin)
614- [extract-loader](https://github.com/peerigon/extract-loader) (simpler, but specialized on the css-loader's output)
615
616**webpack.config.js**
617
618```js
619const MiniCssExtractPlugin = require("mini-css-extract-plugin");
620
621module.exports = {
622 module: {
623 rules: [
624 {
625 test: /\.s[ac]ss$/i,
626 use: [
627 // fallback to style-loader in development
628 process.env.NODE_ENV !== "production"
629 ? "style-loader"
630 : MiniCssExtractPlugin.loader,
631 "css-loader",
632 "sass-loader",
633 ],
634 },
635 ],
636 },
637 plugins: [
638 new MiniCssExtractPlugin({
639 // Options similar to the same options in webpackOptions.output
640 // both options are optional
641 filename: "[name].css",
642 chunkFilename: "[id].css",
643 }),
644 ],
645};
646```
647
648### Source maps
649
650Enables/Disables generation of source maps.
651
652To enable CSS source maps, you'll need to pass the `sourceMap` option to the `sass-loader` _and_ the css-loader.
653
654**webpack.config.js**
655
656```javascript
657module.exports = {
658 devtool: "source-map", // any "source-map"-like devtool is possible
659 module: {
660 rules: [
661 {
662 test: /\.s[ac]ss$/i,
663 use: [
664 "style-loader",
665 {
666 loader: "css-loader",
667 options: {
668 sourceMap: true,
669 },
670 },
671 {
672 loader: "sass-loader",
673 options: {
674 sourceMap: true,
675 },
676 },
677 ],
678 },
679 ],
680 },
681};
682```
683
684If you want to edit the original Sass files inside Chrome, [there's a good blog post](https://medium.com/@toolmantim/getting-started-with-css-sourcemaps-and-in-browser-sass-editing-b4daab987fb0). Checkout [test/sourceMap](https://github.com/webpack-contrib/sass-loader/tree/master/test) for a running example.
685
686## Contributing
687
688Please take a moment to read our contributing guidelines if you haven't yet done so.
689
690[CONTRIBUTING](./.github/CONTRIBUTING.md)
691
692## License
693
694[MIT](./LICENSE)
695
696[npm]: https://img.shields.io/npm/v/sass-loader.svg
697[npm-url]: https://npmjs.com/package/sass-loader
698[node]: https://img.shields.io/node/v/sass-loader.svg
699[node-url]: https://nodejs.org
700[deps]: https://david-dm.org/webpack-contrib/sass-loader.svg
701[deps-url]: https://david-dm.org/webpack-contrib/sass-loader
702[tests]: https://github.com/webpack-contrib/sass-loader/workflows/sass-loader/badge.svg
703[tests-url]: https://github.com/webpack-contrib/sass-loader/actions
704[cover]: https://codecov.io/gh/webpack-contrib/sass-loader/branch/master/graph/badge.svg
705[cover-url]: https://codecov.io/gh/webpack-contrib/sass-loader
706[chat]: https://badges.gitter.im/webpack/webpack.svg
707[chat-url]: https://gitter.im/webpack/webpack
708[size]: https://packagephobia.now.sh/badge?p=sass-loader
709[size-url]: https://packagephobia.now.sh/result?p=sass-loader
Note: See TracBrowser for help on using the repository browser.