source: trip-planner-front/node_modules/css-loader/README.md

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

initial commit

  • Property mode set to 100644
File size: 38.9 KB
Line 
1<div align="center">
2 <img width="180" height="180" vspace="20"
3 src="https://cdn.worldvectorlogo.com/logos/css-3.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# css-loader
19
20The `css-loader` interprets `@import` and `url()` like `import/require()` and will resolve them.
21
22## Getting Started
23
24> ⚠ To use css-loader, webpack@5 is required
25
26To begin, you'll need to install `css-loader`:
27
28```console
29npm install --save-dev css-loader
30```
31
32Then add the plugin to your `webpack` config. For example:
33
34**file.js**
35
36```js
37import css from "file.css";
38```
39
40**webpack.config.js**
41
42```js
43module.exports = {
44 module: {
45 rules: [
46 {
47 test: /\.css$/i,
48 use: ["style-loader", "css-loader"],
49 },
50 ],
51 },
52};
53```
54
55And run `webpack` via your preferred method.
56
57### `toString`
58
59You can also use the css-loader results directly as a string, such as in Angular's component style.
60
61**webpack.config.js**
62
63```js
64module.exports = {
65 module: {
66 rules: [
67 {
68 test: /\.css$/i,
69 use: ["to-string-loader", "css-loader"],
70 },
71 ],
72 },
73};
74```
75
76or
77
78```js
79const css = require("./test.css").toString();
80
81console.log(css); // {String}
82```
83
84If there are SourceMaps, they will also be included in the result string.
85
86If, for one reason or another, you need to extract CSS as a
87plain string resource (i.e. not wrapped in a JS module) you
88might want to check out the [extract-loader](https://github.com/peerigon/extract-loader).
89It's useful when you, for instance, need to post process the CSS as a string.
90
91**webpack.config.js**
92
93```js
94module.exports = {
95 module: {
96 rules: [
97 {
98 test: /\.css$/i,
99 use: [
100 "handlebars-loader", // handlebars loader expects raw resource string
101 "extract-loader",
102 "css-loader",
103 ],
104 },
105 ],
106 },
107};
108```
109
110## Options
111
112| Name | Type | Default | Description |
113| :-----------------------------------: | :-------------------------: | :----------------: | :----------------------------------------------------------------------------------------------------------------------- |
114| **[`url`](#url)** | `{Boolean\|Object}` | `true` | Allows to enables/disables `url()`/`image-set()` functions handling |
115| **[`import`](#import)** | `{Boolean\|Object}` | `true` | Allows to enables/disables `@import` at-rules handling |
116| **[`modules`](#modules)** | `{Boolean\|String\|Object}` | `{auto: true}` | Allows to enables/disables or setup CSS Modules options |
117| **[`sourceMap`](#sourcemap)** | `{Boolean}` | `compiler.devtool` | Enables/Disables generation of source maps |
118| **[`importLoaders`](#importloaders)** | `{Number}` | `0` | Allows enables/disables or setups number of loaders applied before CSS loader for `@import`/CSS Modules and ICSS imports |
119| **[`esModule`](#esmodule)** | `{Boolean}` | `true` | Use ES modules syntax |
120
121### `url`
122
123Type: `Boolean|Object`
124Default: `true`
125
126Allow to enable/disables handling the CSS functions `url` and `image-set`.
127If set to `false`, `css-loader` will not parse any paths specified in `url` or `image-set`.
128A function can also be passed to control this behavior dynamically based on the path to the asset.
129Starting with version [4.0.0](https://github.com/webpack-contrib/css-loader/blob/master/CHANGELOG.md#400-2020-07-25), absolute paths are parsed based on the server root.
130
131Examples resolutions:
132
133```
134url(image.png) => require('./image.png')
135url('image.png') => require('./image.png')
136url(./image.png) => require('./image.png')
137url('./image.png') => require('./image.png')
138url('http://dontwritehorriblecode.com/2112.png') => require('http://dontwritehorriblecode.com/2112.png')
139image-set(url('image2x.png') 1x, url('image1x.png') 2x) => require('./image1x.png') and require('./image2x.png')
140```
141
142To import assets from a `node_modules` path (include `resolve.modules`) and for `alias`, prefix it with a `~`:
143
144```
145url(~module/image.png) => require('module/image.png')
146url('~module/image.png') => require('module/image.png')
147url(~aliasDirectory/image.png) => require('otherDirectory/image.png')
148```
149
150#### `Boolean`
151
152Enable/disable `url()` resolving.
153
154**webpack.config.js**
155
156```js
157module.exports = {
158 module: {
159 rules: [
160 {
161 test: /\.css$/i,
162 loader: "css-loader",
163 options: {
164 url: true,
165 },
166 },
167 ],
168 },
169};
170```
171
172#### `Object`
173
174Allow to filter `url()`. All filtered `url()` will not be resolved (left in the code as they were written).
175
176**webpack.config.js**
177
178```js
179module.exports = {
180 module: {
181 rules: [
182 {
183 test: /\.css$/i,
184 loader: "css-loader",
185 options: {
186 url: {
187 filter: (url, resourcePath) => {
188 // resourcePath - path to css file
189
190 // Don't handle `img.png` urls
191 if (url.includes("img.png")) {
192 return false;
193 }
194
195 return true;
196 },
197 },
198 },
199 },
200 ],
201 },
202};
203```
204
205### `import`
206
207Type: `Boolean|Object`
208Default: `true`
209
210Allows to enables/disables `@import` at-rules handling.
211Control `@import` resolving. Absolute urls in `@import` will be moved in runtime code.
212
213Examples resolutions:
214
215```
216@import 'style.css' => require('./style.css')
217@import url(style.css) => require('./style.css')
218@import url('style.css') => require('./style.css')
219@import './style.css' => require('./style.css')
220@import url(./style.css) => require('./style.css')
221@import url('./style.css') => require('./style.css')
222@import url('http://dontwritehorriblecode.com/style.css') => @import url('http://dontwritehorriblecode.com/style.css') in runtime
223```
224
225To import styles from a `node_modules` path (include `resolve.modules`) and for `alias`, prefix it with a `~`:
226
227```
228@import url(~module/style.css) => require('module/style.css')
229@import url('~module/style.css') => require('module/style.css')
230@import url(~aliasDirectory/style.css) => require('otherDirectory/style.css')
231```
232
233#### `Boolean`
234
235Enable/disable `@import` resolving.
236
237**webpack.config.js**
238
239```js
240module.exports = {
241 module: {
242 rules: [
243 {
244 test: /\.css$/i,
245 loader: "css-loader",
246 options: {
247 import: true,
248 },
249 },
250 ],
251 },
252};
253```
254
255#### `Object`
256
257| Name | Type | Default | Description |
258| :---------------------: | :----------: | :---------: | :------------------------ |
259| **[`filter`](#filter)** | `{Function}` | `undefined` | Allow to filter `@import` |
260
261##### `filter`
262
263Type: `Function`
264Default: `undefined`
265
266Allow to filter `@import`. All filtered `@import` will not be resolved (left in the code as they were written).
267
268**webpack.config.js**
269
270```js
271module.exports = {
272 module: {
273 rules: [
274 {
275 test: /\.css$/i,
276 loader: "css-loader",
277 options: {
278 import: {
279 filter: (url, media, resourcePath) => {
280 // resourcePath - path to css file
281
282 // Don't handle `style.css` import
283 if (url.includes("style.css")) {
284 return false;
285 }
286
287 return true;
288 },
289 },
290 },
291 },
292 ],
293 },
294};
295```
296
297### `modules`
298
299Type: `Boolean|String|Object`
300Default: `undefined`
301
302Allows to enable/disable CSS Modules or ICSS and setup configuration:
303
304- `undefined` - enable CSS modules for all files matching `/\.module\.\w+$/i.test(filename)` and `/\.icss\.\w+$/i.test(filename)` regexp.
305- `true` - enable CSS modules for all files.
306- `false` - disables CSS Modules for all files.
307- `string` - disables CSS Modules for all files and set the `mode` option, more information you can read [here](https://github.com/webpack-contrib/css-loader#mode)
308- `object` - enable CSS modules for all files, if `modules.auto` option is not specified, otherwise the `modules.auto` option will determine whether if it is CSS modules or not, more information you can read [here](https://github.com/webpack-contrib/css-loader#auto)
309
310The `modules` option enables/disables the **[CSS Modules](https://github.com/css-modules/css-modules)** specification and setup basic behaviour.
311
312Using `false` value increase performance because we avoid parsing **CSS Modules** features, it will be useful for developers who use vanilla css or use other technologies.
313
314**webpack.config.js**
315
316```js
317module.exports = {
318 module: {
319 rules: [
320 {
321 test: /\.css$/i,
322 loader: "css-loader",
323 options: {
324 modules: true,
325 },
326 },
327 ],
328 },
329};
330```
331
332#### `Features`
333
334##### `Scope`
335
336Using `local` value requires you to specify `:global` classes.
337Using `global` value requires you to specify `:local` classes.
338Using `pure` value requires selectors must contain at least one local class or id.
339
340You can find more information [here](https://github.com/css-modules/css-modules).
341
342Styles can be locally scoped to avoid globally scoping styles.
343
344The syntax `:local(.className)` can be used to declare `className` in the local scope. The local identifiers are exported by the module.
345
346With `:local` (without brackets) local mode can be switched on for this selector.
347The `:global(.className)` notation can be used to declare an explicit global selector.
348With `:global` (without brackets) global mode can be switched on for this selector.
349
350The loader replaces local selectors with unique identifiers. The chosen unique identifiers are exported by the module.
351
352```css
353:local(.className) {
354 background: red;
355}
356:local .className {
357 color: green;
358}
359:local(.className .subClass) {
360 color: green;
361}
362:local .className .subClass :global(.global-class-name) {
363 color: blue;
364}
365```
366
367```css
368._23_aKvs-b8bW2Vg3fwHozO {
369 background: red;
370}
371._23_aKvs-b8bW2Vg3fwHozO {
372 color: green;
373}
374._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 {
375 color: green;
376}
377._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 .global-class-name {
378 color: blue;
379}
380```
381
382> ℹ️ Identifiers are exported
383
384```js
385exports.locals = {
386 className: "_23_aKvs-b8bW2Vg3fwHozO",
387 subClass: "_13LGdX8RMStbBE9w-t0gZ1",
388};
389```
390
391CamelCase is recommended for local selectors. They are easier to use within the imported JS module.
392
393You can use `:local(#someId)`, but this is not recommended. Use classes instead of ids.
394
395##### `Composing`
396
397When declaring a local classname you can compose a local class from another local classname.
398
399```css
400:local(.className) {
401 background: red;
402 color: yellow;
403}
404
405:local(.subClass) {
406 composes: className;
407 background: blue;
408}
409```
410
411This doesn't result in any change to the CSS itself but exports multiple classnames.
412
413```js
414exports.locals = {
415 className: "_23_aKvs-b8bW2Vg3fwHozO",
416 subClass: "_13LGdX8RMStbBE9w-t0gZ1 _23_aKvs-b8bW2Vg3fwHozO",
417};
418```
419
420```css
421._23_aKvs-b8bW2Vg3fwHozO {
422 background: red;
423 color: yellow;
424}
425
426._13LGdX8RMStbBE9w-t0gZ1 {
427 background: blue;
428}
429```
430
431##### `Importing`
432
433To import a local classname from another module.
434
435> i We strongly recommend that you specify the extension when importing a file, since it is possible to import a file with any extension and it is not known in advance which file to use.
436
437```css
438:local(.continueButton) {
439 composes: button from "library/button.css";
440 background: red;
441}
442```
443
444```css
445:local(.nameEdit) {
446 composes: edit highlight from "./edit.css";
447 background: red;
448}
449```
450
451To import from multiple modules use multiple `composes:` rules.
452
453```css
454:local(.className) {
455 composes: edit hightlight from "./edit.css";
456 composes: button from "module/button.css";
457 composes: classFromThisModule;
458 background: red;
459}
460```
461
462##### `Values`
463
464You can use `@value` to specific values to be reused throughout a document.
465
466We recommend use prefix `v-` for values, `s-` for selectors and `m-` for media at-rules.
467
468```css
469@value v-primary: #BF4040;
470@value s-black: black-selector;
471@value m-large: (min-width: 960px);
472
473.header {
474 color: v-primary;
475 padding: 0 10px;
476}
477
478.s-black {
479 color: black;
480}
481
482@media m-large {
483 .header {
484 padding: 0 20px;
485 }
486}
487```
488
489#### `Boolean`
490
491Enable **CSS Modules** features.
492
493**webpack.config.js**
494
495```js
496module.exports = {
497 module: {
498 rules: [
499 {
500 test: /\.css$/i,
501 loader: "css-loader",
502 options: {
503 modules: true,
504 },
505 },
506 ],
507 },
508};
509```
510
511#### `String`
512
513Enable **CSS Modules** features and setup `mode`.
514
515**webpack.config.js**
516
517```js
518module.exports = {
519 module: {
520 rules: [
521 {
522 test: /\.css$/i,
523 loader: "css-loader",
524 options: {
525 // Using `local` value has same effect like using `modules: true`
526 modules: "global",
527 },
528 },
529 ],
530 },
531};
532```
533
534#### `Object`
535
536Enable **CSS Modules** features and setup options for them.
537
538**webpack.config.js**
539
540```js
541module.exports = {
542 module: {
543 rules: [
544 {
545 test: /\.css$/i,
546 loader: "css-loader",
547 options: {
548 modules: {
549 mode: "local",
550 auto: true,
551 exportGlobals: true,
552 localIdentName: "[path][name]__[local]--[hash:base64:5]",
553 localIdentContext: path.resolve(__dirname, "src"),
554 localIdentHashSalt: "my-custom-hash",
555 namedExport: true,
556 exportLocalsConvention: "camelCase",
557 exportOnlyLocals: false,
558 },
559 },
560 },
561 ],
562 },
563};
564```
565
566##### `auto`
567
568Type: `Boolean|RegExp|Function`
569Default: `undefined`
570
571Allows auto enable CSS modules/ICSS based on filename when `modules` option is object.
572
573Possible values:
574
575- `undefined` - enable CSS modules for all files.
576- `true` - enable CSS modules for all files matching `/\.module\.\w+$/i.test(filename)` and `/\.icss\.\w+$/i.test(filename)` regexp.
577- `false` - disables CSS Modules.
578- `RegExp` - enable CSS modules for all files matching `/RegExp/i.test(filename)` regexp.
579- `function` - enable CSS Modules for files based on the filename satisfying your filter function check.
580
581###### `Boolean`
582
583Possible values:
584
585- `true` - enables CSS modules or interoperable CSS format, sets the [`modules.mode`](#mode) option to `local` value for all files which satisfy `/\.module(s)?\.\w+$/i.test(filename)` condition or sets the [`modules.mode`](#mode) option to `icss` value for all files which satisfy `/\.icss\.\w+$/i.test(filename)` condition
586- `false` - disables CSS modules or interoperable CSS format based on filename
587
588**webpack.config.js**
589
590```js
591module.exports = {
592 module: {
593 rules: [
594 {
595 test: /\.css$/i,
596 loader: "css-loader",
597 options: {
598 modules: {
599 auto: true,
600 },
601 },
602 },
603 ],
604 },
605};
606```
607
608###### `RegExp`
609
610Enable css modules for files based on the filename satisfying your regex check.
611
612**webpack.config.js**
613
614```js
615module.exports = {
616 module: {
617 rules: [
618 {
619 test: /\.css$/i,
620 loader: "css-loader",
621 options: {
622 modules: {
623 auto: /\.custom-module\.\w+$/i,
624 },
625 },
626 },
627 ],
628 },
629};
630```
631
632###### `Function`
633
634Enable css modules for files based on the filename satisfying your filter function check.
635
636**webpack.config.js**
637
638```js
639module.exports = {
640 module: {
641 rules: [
642 {
643 test: /\.css$/i,
644 loader: "css-loader",
645 options: {
646 modules: {
647 auto: (resourcePath) => resourcePath.endsWith(".custom-module.css"),
648 },
649 },
650 },
651 ],
652 },
653};
654```
655
656##### `mode`
657
658Type: `String|Function`
659Default: `'local'`
660
661Setup `mode` option. You can omit the value when you want `local` mode.
662
663Controls the level of compilation applied to the input styles.
664
665The `local`, `global`, and `pure` handles `class` and `id` scoping and `@value` values.
666The `icss` will only compile the low level `Interoperable CSS` format for declaring `:import` and `:export` dependencies between CSS and other languages.
667
668ICSS underpins CSS Module support, and provides a low level syntax for other tools to implement CSS-module variations of their own.
669
670###### `String`
671
672Possible values - `local`, `global`, `pure`, and `icss`.
673
674**webpack.config.js**
675
676```js
677module.exports = {
678 module: {
679 rules: [
680 {
681 test: /\.css$/i,
682 loader: "css-loader",
683 options: {
684 modules: {
685 mode: "global",
686 },
687 },
688 },
689 ],
690 },
691};
692```
693
694###### `Function`
695
696Allows set different values for the `mode` option based on a filename
697
698Possible return values - `local`, `global`, `pure` and `icss`.
699
700**webpack.config.js**
701
702```js
703module.exports = {
704 module: {
705 rules: [
706 {
707 test: /\.css$/i,
708 loader: "css-loader",
709 options: {
710 modules: {
711 // Callback must return "local", "global", or "pure" values
712 mode: (resourcePath) => {
713 if (/pure.css$/i.test(resourcePath)) {
714 return "pure";
715 }
716
717 if (/global.css$/i.test(resourcePath)) {
718 return "global";
719 }
720
721 return "local";
722 },
723 },
724 },
725 },
726 ],
727 },
728};
729```
730
731##### `localIdentName`
732
733Type: `String`
734Default: `'[hash:base64]'`
735
736Allows to configure the generated local ident name.
737
738For more information on options see:
739
740- [webpack template strings](https://webpack.js.org/configuration/output/#template-strings),
741- [output.hashDigest](https://webpack.js.org/configuration/output/#outputhashdigest),
742- [output.hashDigestLength](https://webpack.js.org/configuration/output/#outputhashdigestlength),
743- [output.hashFunction](https://webpack.js.org/configuration/output/#outputhashfunction),
744- [output.hashSalt](https://webpack.js.org/configuration/output/#outputhashsalt).
745
746Supported template strings:
747
748- [name] the basename of the resource
749- [path] the path of the resource relative to the `compiler.context` option or `modules.localIdentContext` option.
750- [file] - filename and path.
751- [ext] - extension with leading .
752- [hash] - the hash of the string, generated based on `localIdentHashSalt`, `localIdentHashFunction`, `localIdentHashDigest`, `localIdentHashDigestLength`, `localIdentContext`, `resourcePath` and `exportName`
753- [<hashFunction>:hash:<hashDigest>:<hashDigestLength>] - hash with hash settings.
754- [local] - original class.
755
756Recommendations:
757
758- use `'[path][name]__[local]'` for development
759- use `'[hash:base64]'` for production
760
761The `[local]` placeholder contains original class.
762
763**Note:** all reserved (`<>:"/\|?*`) and control filesystem characters (excluding characters in the `[local]` placeholder) will be converted to `-`.
764
765**webpack.config.js**
766
767```js
768module.exports = {
769 module: {
770 rules: [
771 {
772 test: /\.css$/i,
773 loader: "css-loader",
774 options: {
775 modules: {
776 localIdentName: "[path][name]__[local]--[hash:base64:5]",
777 },
778 },
779 },
780 ],
781 },
782};
783```
784
785##### `localIdentContext`
786
787Type: `String`
788Default: `compiler.context`
789
790Allows to redefine basic loader context for local ident name.
791
792**webpack.config.js**
793
794```js
795module.exports = {
796 module: {
797 rules: [
798 {
799 test: /\.css$/i,
800 loader: "css-loader",
801 options: {
802 modules: {
803 localIdentContext: path.resolve(__dirname, "src"),
804 },
805 },
806 },
807 ],
808 },
809};
810```
811
812##### `localIdentHashSalt`
813
814Type: `String`
815Default: `undefined`
816
817Allows to add custom hash to generate more unique classes.
818For more information see [output.hashSalt](https://webpack.js.org/configuration/output/#outputhashsalt).
819
820**webpack.config.js**
821
822```js
823module.exports = {
824 module: {
825 rules: [
826 {
827 test: /\.css$/i,
828 loader: "css-loader",
829 options: {
830 modules: {
831 localIdentHashSalt: "hash",
832 },
833 },
834 },
835 ],
836 },
837};
838```
839
840##### `localIdentHashFunction`
841
842Type: `String`
843Default: `md4`
844
845Allows to specify hash function to generate classes .
846For more information see [output.hashFunction](https://webpack.js.org/configuration/output/#outputhashfunction).
847
848**webpack.config.js**
849
850```js
851module.exports = {
852 module: {
853 rules: [
854 {
855 test: /\.css$/i,
856 loader: "css-loader",
857 options: {
858 modules: {
859 localIdentHashFunction: "md4",
860 },
861 },
862 },
863 ],
864 },
865};
866```
867
868##### `localIdentHashDigest`
869
870Type: `String`
871Default: `hex`
872
873Allows to specify hash digest to generate classes.
874For more information see [output.hashDigest](https://webpack.js.org/configuration/output/#outputhashdigest).
875
876**webpack.config.js**
877
878```js
879module.exports = {
880 module: {
881 rules: [
882 {
883 test: /\.css$/i,
884 loader: "css-loader",
885 options: {
886 modules: {
887 localIdentHashDigest: "base64",
888 },
889 },
890 },
891 ],
892 },
893};
894```
895
896##### `localIdentHashDigestLength`
897
898Type: `Number`
899Default: `20`
900
901Allows to specify hash digest length to generate classes.
902For more information see [output.hashDigestLength](https://webpack.js.org/configuration/output/#outputhashdigestlength).
903
904**webpack.config.js**
905
906```js
907module.exports = {
908 module: {
909 rules: [
910 {
911 test: /\.css$/i,
912 loader: "css-loader",
913 options: {
914 modules: {
915 localIdentHashDigestLength: 5,
916 },
917 },
918 },
919 ],
920 },
921};
922```
923
924##### `localIdentRegExp`
925
926Type: `String|RegExp`
927Default: `undefined`
928
929**webpack.config.js**
930
931```js
932module.exports = {
933 module: {
934 rules: [
935 {
936 test: /\.css$/i,
937 loader: "css-loader",
938 options: {
939 modules: {
940 localIdentRegExp: /page-(.*)\.css/i,
941 },
942 },
943 },
944 ],
945 },
946};
947```
948
949##### `getLocalIdent`
950
951Type: `Function`
952Default: `undefined`
953
954Allows to specify a function to generate the classname.
955By default we use built-in function to generate a classname.
956If the custom function returns `null` or `undefined`, we fallback to the
957built-in function to generate the classname.
958
959**webpack.config.js**
960
961```js
962module.exports = {
963 module: {
964 rules: [
965 {
966 test: /\.css$/i,
967 loader: "css-loader",
968 options: {
969 modules: {
970 getLocalIdent: (context, localIdentName, localName, options) => {
971 return "whatever_random_class_name";
972 },
973 },
974 },
975 },
976 ],
977 },
978};
979```
980
981##### `namedExport`
982
983Type: `Boolean`
984Default: `false`
985
986Enables/disables ES modules named export for locals.
987
988> ⚠ Names of locals are converted to camelcase, i.e. the `exportLocalsConvention` option has `camelCaseOnly` value by default.
989
990> ⚠ It is not allowed to use JavaScript reserved words in css class names.
991
992**styles.css**
993
994```css
995.foo-baz {
996 color: red;
997}
998.bar {
999 color: blue;
1000}
1001```
1002
1003**index.js**
1004
1005```js
1006import { fooBaz, bar } from "./styles.css";
1007
1008console.log(fooBaz, bar);
1009```
1010
1011You can enable a ES module named export using:
1012
1013**webpack.config.js**
1014
1015```js
1016module.exports = {
1017 module: {
1018 rules: [
1019 {
1020 test: /\.css$/i,
1021 loader: "css-loader",
1022 options: {
1023 esModule: true,
1024 modules: {
1025 namedExport: true,
1026 },
1027 },
1028 },
1029 ],
1030 },
1031};
1032```
1033
1034To set a custom name for namedExport, can use [`exportLocalsConvention`](#exportLocalsConvention) option as a function.
1035Example below in the [`examples`](#examples) section.
1036
1037##### `exportGlobals`
1038
1039Type: `Boolean`
1040Default: `false`
1041
1042Allow `css-loader` to export names from global class or id, so you can use that as local name.
1043
1044**webpack.config.js**
1045
1046```js
1047module.exports = {
1048 module: {
1049 rules: [
1050 {
1051 test: /\.css$/i,
1052 loader: "css-loader",
1053 options: {
1054 modules: {
1055 exportGlobals: true,
1056 },
1057 },
1058 },
1059 ],
1060 },
1061};
1062```
1063
1064##### `exportLocalsConvention`
1065
1066Type: `String|Function`
1067Default: based on the `modules.namedExport` option value, if `true` - `camelCaseOnly`, otherwise `asIs`
1068
1069Style of exported class names.
1070
1071###### `String`
1072
1073By default, the exported JSON keys mirror the class names (i.e `asIs` value).
1074
1075> ⚠ Only `camelCaseOnly` value allowed if you set the `namedExport` value to `true`.
1076
1077| Name | Type | Description |
1078| :-------------------: | :--------: | :----------------------------------------------------------------------------------------------- |
1079| **`'asIs'`** | `{String}` | Class names will be exported as is. |
1080| **`'camelCase'`** | `{String}` | Class names will be camelized, the original class name will not to be removed from the locals |
1081| **`'camelCaseOnly'`** | `{String}` | Class names will be camelized, the original class name will be removed from the locals |
1082| **`'dashes'`** | `{String}` | Only dashes in class names will be camelized |
1083| **`'dashesOnly'`** | `{String}` | Dashes in class names will be camelized, the original class name will be removed from the locals |
1084
1085**file.css**
1086
1087```css
1088.class-name {
1089}
1090```
1091
1092**file.js**
1093
1094```js
1095import { className } from "file.css";
1096```
1097
1098**webpack.config.js**
1099
1100```js
1101module.exports = {
1102 module: {
1103 rules: [
1104 {
1105 test: /\.css$/i,
1106 loader: "css-loader",
1107 options: {
1108 modules: {
1109 exportLocalsConvention: "camelCase",
1110 },
1111 },
1112 },
1113 ],
1114 },
1115};
1116```
1117
1118###### `Function`
1119
1120**webpack.config.js**
1121
1122```js
1123module.exports = {
1124 module: {
1125 rules: [
1126 {
1127 test: /\.css$/i,
1128 loader: "css-loader",
1129 options: {
1130 modules: {
1131 exportLocalsConvention: function (name) {
1132 return name.replace(/-/g, "_");
1133 },
1134 },
1135 },
1136 },
1137 ],
1138 },
1139};
1140```
1141
1142**webpack.config.js**
1143
1144```js
1145module.exports = {
1146 module: {
1147 rules: [
1148 {
1149 test: /\.css$/i,
1150 loader: "css-loader",
1151 options: {
1152 modules: {
1153 exportLocalsConvention: function (name) {
1154 return [
1155 name.replace(/-/g, "_"),
1156 // dashesCamelCase
1157 name.replace(/-+(\w)/g, (match, firstLetter) =>
1158 firstLetter.toUpperCase()
1159 ),
1160 ];
1161 },
1162 },
1163 },
1164 },
1165 ],
1166 },
1167};
1168```
1169
1170##### `exportOnlyLocals`
1171
1172Type: `Boolean`
1173Default: `false`
1174
1175Export only locals.
1176
1177**Useful** when you use **css modules** for pre-rendering (for example SSR).
1178For pre-rendering with `mini-css-extract-plugin` you should use this option instead of `style-loader!css-loader` **in the pre-rendering bundle**.
1179It doesn't embed CSS but only exports the identifier mappings.
1180
1181**webpack.config.js**
1182
1183```js
1184module.exports = {
1185 module: {
1186 rules: [
1187 {
1188 test: /\.css$/i,
1189 loader: "css-loader",
1190 options: {
1191 modules: {
1192 exportOnlyLocals: true,
1193 },
1194 },
1195 },
1196 ],
1197 },
1198};
1199```
1200
1201### `importLoaders`
1202
1203Type: `Number`
1204Default: `0`
1205
1206Allows to enables/disables or setups number of loaders applied before CSS loader for `@import` at-rules, CSS modules and ICSS imports, i.e. `@import`/`composes`/`@value value from './values.css'`/etc.
1207
1208The option `importLoaders` allows you to configure how many loaders before `css-loader` should be applied to `@import`ed resources and CSS modules/ICSS imports.
1209
1210**webpack.config.js**
1211
1212```js
1213module.exports = {
1214 module: {
1215 rules: [
1216 {
1217 test: /\.css$/i,
1218 use: [
1219 "style-loader",
1220 {
1221 loader: "css-loader",
1222 options: {
1223 importLoaders: 2,
1224 // 0 => no loaders (default);
1225 // 1 => postcss-loader;
1226 // 2 => postcss-loader, sass-loader
1227 },
1228 },
1229 "postcss-loader",
1230 "sass-loader",
1231 ],
1232 },
1233 ],
1234 },
1235};
1236```
1237
1238This may change in the future when the module system (i. e. webpack) supports loader matching by origin.
1239
1240### `sourceMap`
1241
1242Type: `Boolean`
1243Default: depends on the `compiler.devtool` value
1244
1245By default generation of source maps depends on the [`devtool`](https://webpack.js.org/configuration/devtool/) option. All values enable source map generation except `eval` and `false` value.
1246
1247**webpack.config.js**
1248
1249```js
1250module.exports = {
1251 module: {
1252 rules: [
1253 {
1254 test: /\.css$/i,
1255 loader: "css-loader",
1256 options: {
1257 sourceMap: true,
1258 },
1259 },
1260 ],
1261 },
1262};
1263```
1264
1265### `esModule`
1266
1267Type: `Boolean`
1268Default: `true`
1269
1270By default, `css-loader` generates JS modules that use the ES modules syntax.
1271There are some cases in which using ES modules is beneficial, like in the case of [module concatenation](https://webpack.js.org/plugins/module-concatenation-plugin/) and [tree shaking](https://webpack.js.org/guides/tree-shaking/).
1272
1273You can enable a CommonJS modules syntax using:
1274
1275**webpack.config.js**
1276
1277```js
1278module.exports = {
1279 module: {
1280 rules: [
1281 {
1282 test: /\.css$/i,
1283 loader: "css-loader",
1284 options: {
1285 esModule: false,
1286 },
1287 },
1288 ],
1289 },
1290};
1291```
1292
1293## Examples
1294
1295### Recommend
1296
1297For `production` builds it's recommended to extract the CSS from your bundle being able to use parallel loading of CSS/JS resources later on.
1298This can be achieved by using the [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin), because it creates separate css files.
1299For `development` mode (including `webpack-dev-server`) you can use [style-loader](https://github.com/webpack-contrib/style-loader), because it injects CSS into the DOM using multiple <style></style> and works faster.
1300
1301> i Do not use together `style-loader` and `mini-css-extract-plugin`.
1302
1303**webpack.config.js**
1304
1305```js
1306const MiniCssExtractPlugin = require("mini-css-extract-plugin");
1307const devMode = process.env.NODE_ENV !== "production";
1308
1309module.exports = {
1310 module: {
1311 rules: [
1312 {
1313 test: /\.(sa|sc|c)ss$/,
1314 use: [
1315 devMode ? "style-loader" : MiniCssExtractPlugin.loader,
1316 "css-loader",
1317 "postcss-loader",
1318 "sass-loader",
1319 ],
1320 },
1321 ],
1322 },
1323 plugins: [].concat(devMode ? [] : [new MiniCssExtractPlugin()]),
1324};
1325```
1326
1327### Disable url resolving using the `/* webpackIgnore: true */` comment
1328
1329With the help of the `/* webpackIgnore: true */`comment, it is possible to disable sources handling for rules and for individual declarations.
1330
1331```css
1332/* webpackIgnore: true */
1333@import url(./basic.css);
1334@import /* webpackIgnore: true */ url(./imported.css);
1335
1336.class {
1337 /* Disabled url handling for the all urls in the 'background' declaration */
1338 color: red;
1339 /* webpackIgnore: true */
1340 background: url("./url/img.png"), url("./url/img.png");
1341}
1342
1343.class {
1344 /* Disabled url handling for the first url in the 'background' declaration */
1345 color: red;
1346 background:
1347 /* webpackIgnore: true */ url("./url/img.png"), url("./url/img.png");
1348}
1349
1350.class {
1351 /* Disabled url handling for the second url in the 'background' declaration */
1352 color: red;
1353 background: url("./url/img.png"),
1354 /* webpackIgnore: true */ url("./url/img.png");
1355}
1356
1357/* prettier-ignore */
1358.class {
1359 /* Disabled url handling for the second url in the 'background' declaration */
1360 color: red;
1361 background: url("./url/img.png"),
1362 /* webpackIgnore: true */
1363 url("./url/img.png");
1364}
1365
1366/* prettier-ignore */
1367.class {
1368 /* Disabled url handling for third and sixth urls in the 'background-image' declaration */
1369 background-image: image-set(
1370 url(./url/img.png) 2x,
1371 url(./url/img.png) 3x,
1372 /* webpackIgnore: true */ url(./url/img.png) 4x,
1373 url(./url/img.png) 5x,
1374 url(./url/img.png) 6x,
1375 /* webpackIgnore: true */
1376 url(./url/img.png) 7x
1377 );
1378}
1379```
1380
1381### Assets
1382
1383The following `webpack.config.js` can load CSS files, embed small PNG/JPG/GIF/SVG images as well as fonts as [Data URLs](https://tools.ietf.org/html/rfc2397) and copy larger files to the output directory.
1384
1385**For webpack v5:**
1386
1387**webpack.config.js**
1388
1389```js
1390module.exports = {
1391 module: {
1392 rules: [
1393 {
1394 test: /\.css$/i,
1395 use: ["style-loader", "css-loader"],
1396 },
1397 {
1398 test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
1399 // More information here https://webpack.js.org/guides/asset-modules/
1400 type: "asset",
1401 },
1402 ],
1403 },
1404};
1405```
1406
1407### Extract
1408
1409For production builds it's recommended to extract the CSS from your bundle being able to use parallel loading of CSS/JS resources later on.
1410
1411- This can be achieved by using the [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin) to extract the CSS when running in production mode.
1412
1413- As an alternative, if seeking better development performance and css outputs that mimic production. [extract-css-chunks-webpack-plugin](https://github.com/faceyspacey/extract-css-chunks-webpack-plugin) offers a hot module reload friendly, extended version of mini-css-extract-plugin. HMR real CSS files in dev, works like mini-css in non-dev
1414
1415### Pure CSS, CSS modules and PostCSS
1416
1417When you have pure CSS (without CSS modules), CSS modules and PostCSS in your project you can use this setup:
1418
1419**webpack.config.js**
1420
1421```js
1422module.exports = {
1423 module: {
1424 rules: [
1425 {
1426 // For pure CSS - /\.css$/i,
1427 // For Sass/SCSS - /\.((c|sa|sc)ss)$/i,
1428 // For Less - /\.((c|le)ss)$/i,
1429 test: /\.((c|sa|sc)ss)$/i,
1430 use: [
1431 "style-loader",
1432 {
1433 loader: "css-loader",
1434 options: {
1435 // Run `postcss-loader` on each CSS `@import` and CSS modules/ICSS imports, do not forget that `sass-loader` compile non CSS `@import`'s into a single file
1436 // If you need run `sass-loader` and `postcss-loader` on each CSS `@import` please set it to `2`
1437 importLoaders: 1,
1438 },
1439 },
1440 {
1441 loader: "postcss-loader",
1442 options: { plugins: () => [postcssPresetEnv({ stage: 0 })] },
1443 },
1444 // Can be `less-loader`
1445 {
1446 loader: "sass-loader",
1447 },
1448 ],
1449 },
1450 // For webpack v5
1451 {
1452 test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
1453 // More information here https://webpack.js.org/guides/asset-modules/
1454 type: "asset",
1455 },
1456 ],
1457 },
1458};
1459```
1460
1461### Resolve unresolved URLs using an alias
1462
1463**index.css**
1464
1465```css
1466.class {
1467 background: url(/assets/unresolved/img.png);
1468}
1469```
1470
1471**webpack.config.js**
1472
1473```js
1474module.exports = {
1475 module: {
1476 rules: [
1477 {
1478 test: /\.css$/i,
1479 use: ["style-loader", "css-loader"],
1480 },
1481 ],
1482 },
1483 resolve: {
1484 alias: {
1485 "/assets/unresolved/img.png": path.resolve(
1486 __dirname,
1487 "assets/real-path-to-img/img.png"
1488 ),
1489 },
1490 },
1491};
1492```
1493
1494### Named export with custom export names
1495
1496**webpack.config.js**
1497
1498```js
1499module.exports = {
1500 module: {
1501 rules: [
1502 {
1503 test: /\.css$/i,
1504 loader: "css-loader",
1505 options: {
1506 modules: {
1507 namedExport: true,
1508 exportLocalsConvention: function (name) {
1509 return name.replace(/-/g, "_");
1510 },
1511 },
1512 },
1513 },
1514 ],
1515 },
1516};
1517```
1518
1519### Separating `Interoperable CSS`-only and `CSS Module` features
1520
1521The following setup is an example of allowing `Interoperable CSS` features only (such as `:import` and `:export`) without using further `CSS Module` functionality by setting `mode` option for all files that do not match `*.module.scss` naming convention. This is for reference as having `ICSS` features applied to all files was default `css-loader` behavior before v4.
1522Meanwhile all files matching `*.module.scss` are treated as `CSS Modules` in this example.
1523
1524An example case is assumed where a project requires canvas drawing variables to be synchronized with CSS - canvas drawing uses the same color (set by color name in JavaScript) as HTML background (set by class name in CSS).
1525
1526**webpack.config.js**
1527
1528```js
1529module.exports = {
1530 module: {
1531 rules: [
1532 // ...
1533 // --------
1534 // SCSS ALL EXCEPT MODULES
1535 {
1536 test: /\.scss$/,
1537 exclude: /\.module\.scss$/,
1538 use: [
1539 {
1540 loader: "style-loader",
1541 },
1542 {
1543 loader: "css-loader",
1544 options: {
1545 importLoaders: 1,
1546 modules: {
1547 mode: "icss",
1548 },
1549 },
1550 },
1551 {
1552 loader: "sass-loader",
1553 },
1554 ],
1555 },
1556 // --------
1557 // SCSS MODULES
1558 {
1559 test: /\.module\.scss$/,
1560 use: [
1561 {
1562 loader: "style-loader",
1563 },
1564 {
1565 loader: "css-loader",
1566 options: {
1567 importLoaders: 1,
1568 modules: {
1569 mode: "local",
1570 },
1571 },
1572 },
1573 {
1574 loader: "sass-loader",
1575 },
1576 ],
1577 },
1578 // --------
1579 // ...
1580 ],
1581 },
1582};
1583```
1584
1585**variables.scss**
1586
1587File treated as `ICSS`-only.
1588
1589```scss
1590$colorBackground: red;
1591:export {
1592 colorBackgroundCanvas: $colorBackground;
1593}
1594```
1595
1596**Component.module.scss**
1597
1598File treated as `CSS Module`.
1599
1600```scss
1601@import "variables.scss";
1602.componentClass {
1603 background-color: $colorBackground;
1604}
1605```
1606
1607**Component.jsx**
1608
1609Using both `CSS Module` functionality as well as SCSS variables directly in JavaScript.
1610
1611```jsx
1612import svars from "variables.scss";
1613import styles from "Component.module.scss";
1614
1615// Render DOM with CSS modules class name
1616// <div className={styles.componentClass}>
1617// <canvas ref={mountsCanvas}/>
1618// </div>
1619
1620// Somewhere in JavaScript canvas drawing code use the variable directly
1621// const ctx = mountsCanvas.current.getContext('2d',{alpha: false});
1622ctx.fillStyle = `${svars.colorBackgroundCanvas}`;
1623```
1624
1625## Contributing
1626
1627Please take a moment to read our contributing guidelines if you haven't yet done so.
1628
1629[CONTRIBUTING](./.github/CONTRIBUTING.md)
1630
1631## License
1632
1633[MIT](./LICENSE)
1634
1635[npm]: https://img.shields.io/npm/v/css-loader.svg
1636[npm-url]: https://npmjs.com/package/css-loader
1637[node]: https://img.shields.io/node/v/css-loader.svg
1638[node-url]: https://nodejs.org
1639[deps]: https://david-dm.org/webpack-contrib/css-loader.svg
1640[deps-url]: https://david-dm.org/webpack-contrib/css-loader
1641[tests]: https://github.com/webpack-contrib/css-loader/workflows/css-loader/badge.svg
1642[tests-url]: https://github.com/webpack-contrib/css-loader/actions
1643[cover]: https://codecov.io/gh/webpack-contrib/css-loader/branch/master/graph/badge.svg
1644[cover-url]: https://codecov.io/gh/webpack-contrib/css-loader
1645[chat]: https://badges.gitter.im/webpack/webpack.svg
1646[chat-url]: https://gitter.im/webpack/webpack
1647[size]: https://packagephobia.now.sh/badge?p=css-loader
1648[size-url]: https://packagephobia.now.sh/result?p=css-loader
Note: See TracBrowser for help on using the repository browser.