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 |
|
20 | The `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 |
|
26 | To begin, you'll need to install `css-loader`:
|
27 |
|
28 | ```console
|
29 | npm install --save-dev css-loader
|
30 | ```
|
31 |
|
32 | or
|
33 |
|
34 | ```console
|
35 | yarn add -D css-loader
|
36 | ```
|
37 |
|
38 | or
|
39 |
|
40 | ```console
|
41 | pnpm add -D css-loader
|
42 | ```
|
43 |
|
44 | Then add the plugin to your `webpack` config. For example:
|
45 |
|
46 | **file.js**
|
47 |
|
48 | ```js
|
49 | import css from "file.css";
|
50 | ```
|
51 |
|
52 | **webpack.config.js**
|
53 |
|
54 | ```js
|
55 | module.exports = {
|
56 | module: {
|
57 | rules: [
|
58 | {
|
59 | test: /\.css$/i,
|
60 | use: ["style-loader", "css-loader"],
|
61 | },
|
62 | ],
|
63 | },
|
64 | };
|
65 | ```
|
66 |
|
67 | And run `webpack` via your preferred method.
|
68 |
|
69 | If, for one reason or another, you need to extract CSS as a file (i.e. do not store CSS in a JS module) you might want to check out the [recommend example](https://github.com/webpack-contrib/css-loader#recommend).
|
70 |
|
71 | ## Options
|
72 |
|
73 | - **[`url`](#url)**
|
74 | - **[`import`](#import)**
|
75 | - **[`modules`](#modules)**
|
76 | - **[`sourceMap`](#sourcemap)**
|
77 | - **[`importLoaders`](#importloaders)**
|
78 | - **[`esModule`](#esmodule)**
|
79 | - **[`exportType`](#exporttype)**
|
80 |
|
81 | ### `url`
|
82 |
|
83 | Type:
|
84 |
|
85 | ```ts
|
86 | type url =
|
87 | | boolean
|
88 | | {
|
89 | url: (url: string, resourcePath: string) => boolean;
|
90 | };
|
91 | ```
|
92 |
|
93 | Default: `true`
|
94 |
|
95 | Allow to enable/disables handling the CSS functions `url` and `image-set`.
|
96 | If set to `false`, `css-loader` will not parse any paths specified in `url` or `image-set`.
|
97 | A function can also be passed to control this behavior dynamically based on the path to the asset.
|
98 | Starting 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.
|
99 |
|
100 | Examples resolutions:
|
101 |
|
102 | ```js
|
103 | url(image.png) => require('./image.png')
|
104 | url('image.png') => require('./image.png')
|
105 | url(./image.png) => require('./image.png')
|
106 | url('./image.png') => require('./image.png')
|
107 | url('http://dontwritehorriblecode.com/2112.png') => require('http://dontwritehorriblecode.com/2112.png')
|
108 | image-set(url('image2x.png') 1x, url('image1x.png') 2x) => require('./image1x.png') and require('./image2x.png')
|
109 | ```
|
110 |
|
111 | To import assets from a `node_modules` path (include `resolve.modules`) and for `alias`, prefix it with a `~`:
|
112 |
|
113 | ```js
|
114 | url(~module/image.png) => require('module/image.png')
|
115 | url('~module/image.png') => require('module/image.png')
|
116 | url(~aliasDirectory/image.png) => require('otherDirectory/image.png')
|
117 | ```
|
118 |
|
119 | #### `boolean`
|
120 |
|
121 | Enable/disable `url()` resolving.
|
122 |
|
123 | **webpack.config.js**
|
124 |
|
125 | ```js
|
126 | module.exports = {
|
127 | module: {
|
128 | rules: [
|
129 | {
|
130 | test: /\.css$/i,
|
131 | loader: "css-loader",
|
132 | options: {
|
133 | url: true,
|
134 | },
|
135 | },
|
136 | ],
|
137 | },
|
138 | };
|
139 | ```
|
140 |
|
141 | #### `object`
|
142 |
|
143 | Allow to filter `url()`. All filtered `url()` will not be resolved (left in the code as they were written).
|
144 |
|
145 | **webpack.config.js**
|
146 |
|
147 | ```js
|
148 | module.exports = {
|
149 | module: {
|
150 | rules: [
|
151 | {
|
152 | test: /\.css$/i,
|
153 | loader: "css-loader",
|
154 | options: {
|
155 | url: {
|
156 | filter: (url, resourcePath) => {
|
157 | // resourcePath - path to css file
|
158 |
|
159 | // Don't handle `img.png` urls
|
160 | if (url.includes("img.png")) {
|
161 | return false;
|
162 | }
|
163 |
|
164 | return true;
|
165 | },
|
166 | },
|
167 | },
|
168 | },
|
169 | ],
|
170 | },
|
171 | };
|
172 | ```
|
173 |
|
174 | ### `import`
|
175 |
|
176 | Type:
|
177 |
|
178 |
|
179 |
|
180 | ```ts
|
181 | type import =
|
182 | | boolean
|
183 | | { filter: (url: string, media: string, resourcePath: string) => boolean };
|
184 | ```
|
185 |
|
186 | Default: `true`
|
187 |
|
188 | Allows to enables/disables `@import` at-rules handling.
|
189 | Control `@import` resolving. Absolute urls in `@import` will be moved in runtime code.
|
190 |
|
191 | Examples resolutions:
|
192 |
|
193 | ```
|
194 | @import 'style.css' => require('./style.css')
|
195 | @import url(style.css) => require('./style.css')
|
196 | @import url('style.css') => require('./style.css')
|
197 | @import './style.css' => require('./style.css')
|
198 | @import url(./style.css) => require('./style.css')
|
199 | @import url('./style.css') => require('./style.css')
|
200 | @import url('http://dontwritehorriblecode.com/style.css') => @import url('http://dontwritehorriblecode.com/style.css') in runtime
|
201 | ```
|
202 |
|
203 | To import styles from a `node_modules` path (include `resolve.modules`) and for `alias`, prefix it with a `~`:
|
204 |
|
205 | ```
|
206 | @import url(~module/style.css) => require('module/style.css')
|
207 | @import url('~module/style.css') => require('module/style.css')
|
208 | @import url(~aliasDirectory/style.css) => require('otherDirectory/style.css')
|
209 | ```
|
210 |
|
211 | #### `boolean`
|
212 |
|
213 | Enable/disable `@import` resolving.
|
214 |
|
215 | **webpack.config.js**
|
216 |
|
217 | ```js
|
218 | module.exports = {
|
219 | module: {
|
220 | rules: [
|
221 | {
|
222 | test: /\.css$/i,
|
223 | loader: "css-loader",
|
224 | options: {
|
225 | import: true,
|
226 | },
|
227 | },
|
228 | ],
|
229 | },
|
230 | };
|
231 | ```
|
232 |
|
233 | #### `object`
|
234 |
|
235 | ##### `filter`
|
236 |
|
237 | Type:
|
238 |
|
239 | ```ts
|
240 | type filter = (url: string, media: string, resourcePath: string) => boolean;
|
241 | ```
|
242 |
|
243 | Default: `undefined`
|
244 |
|
245 | Allow to filter `@import`. All filtered `@import` will not be resolved (left in the code as they were written).
|
246 |
|
247 | **webpack.config.js**
|
248 |
|
249 | ```js
|
250 | module.exports = {
|
251 | module: {
|
252 | rules: [
|
253 | {
|
254 | test: /\.css$/i,
|
255 | loader: "css-loader",
|
256 | options: {
|
257 | import: {
|
258 | filter: (url, media, resourcePath) => {
|
259 | // resourcePath - path to css file
|
260 |
|
261 | // Don't handle `style.css` import
|
262 | if (url.includes("style.css")) {
|
263 | return false;
|
264 | }
|
265 |
|
266 | return true;
|
267 | },
|
268 | },
|
269 | },
|
270 | },
|
271 | ],
|
272 | },
|
273 | };
|
274 | ```
|
275 |
|
276 | ### `modules`
|
277 |
|
278 | Type:
|
279 |
|
280 | ```ts
|
281 | type modules =
|
282 | | boolean
|
283 | | "local"
|
284 | | "global"
|
285 | | "pure"
|
286 | | "icss"
|
287 | | {
|
288 | auto: boolean | regExp | ((resourcePath: string) => boolean);
|
289 | mode:
|
290 | | "local"
|
291 | | "global"
|
292 | | "pure"
|
293 | | "icss"
|
294 | | ((resourcePath) => "local" | "global" | "pure" | "icss");
|
295 | localIdentName: string;
|
296 | localIdentContext: string;
|
297 | localIdentHashSalt: string;
|
298 | localIdentHashFunction: string;
|
299 | localIdentHashDigest: string;
|
300 | localIdentRegExp: string | regExp;
|
301 | getLocalIdent: (
|
302 | context: LoaderContext,
|
303 | localIdentName: string,
|
304 | localName: string
|
305 | ) => string;
|
306 | namedExport: boolean;
|
307 | exportGlobals: boolean;
|
308 | exportLocalsConvention:
|
309 | | "asIs"
|
310 | | "camelCase"
|
311 | | "camelCaseOnly"
|
312 | | "dashes"
|
313 | | "dashesOnly"
|
314 | | ((name: string) => string);
|
315 | exportOnlyLocals: boolean;
|
316 | };
|
317 | ```
|
318 |
|
319 | Default: `undefined`
|
320 |
|
321 | Allows to enable/disable CSS Modules or ICSS and setup configuration:
|
322 |
|
323 | - `undefined` - enable CSS modules for all files matching `/\.module\.\w+$/i.test(filename)` and `/\.icss\.\w+$/i.test(filename)` regexp.
|
324 | - `true` - enable CSS modules for all files.
|
325 | - `false` - disables CSS Modules for all files.
|
326 | - `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)
|
327 | - `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)
|
328 |
|
329 | The `modules` option enables/disables the **[CSS Modules](https://github.com/css-modules/css-modules)** specification and setup basic behaviour.
|
330 |
|
331 | Using `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.
|
332 |
|
333 | **webpack.config.js**
|
334 |
|
335 | ```js
|
336 | module.exports = {
|
337 | module: {
|
338 | rules: [
|
339 | {
|
340 | test: /\.css$/i,
|
341 | loader: "css-loader",
|
342 | options: {
|
343 | modules: true,
|
344 | },
|
345 | },
|
346 | ],
|
347 | },
|
348 | };
|
349 | ```
|
350 |
|
351 | #### `Features`
|
352 |
|
353 | ##### `Scope`
|
354 |
|
355 | Using `local` value requires you to specify `:global` classes.
|
356 | Using `global` value requires you to specify `:local` classes.
|
357 | Using `pure` value requires selectors must contain at least one local class or id.
|
358 |
|
359 | You can find more information [here](https://github.com/css-modules/css-modules).
|
360 |
|
361 | Styles can be locally scoped to avoid globally scoping styles.
|
362 |
|
363 | The syntax `:local(.className)` can be used to declare `className` in the local scope. The local identifiers are exported by the module.
|
364 |
|
365 | With `:local` (without brackets) local mode can be switched on for this selector.
|
366 | The `:global(.className)` notation can be used to declare an explicit global selector.
|
367 | With `:global` (without brackets) global mode can be switched on for this selector.
|
368 |
|
369 | The loader replaces local selectors with unique identifiers. The chosen unique identifiers are exported by the module.
|
370 |
|
371 | ```css
|
372 | :local(.className) {
|
373 | background: red;
|
374 | }
|
375 | :local .className {
|
376 | color: green;
|
377 | }
|
378 | :local(.className .subClass) {
|
379 | color: green;
|
380 | }
|
381 | :local .className .subClass :global(.global-class-name) {
|
382 | color: blue;
|
383 | }
|
384 | ```
|
385 |
|
386 | ```css
|
387 | ._23_aKvs-b8bW2Vg3fwHozO {
|
388 | background: red;
|
389 | }
|
390 | ._23_aKvs-b8bW2Vg3fwHozO {
|
391 | color: green;
|
392 | }
|
393 | ._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 {
|
394 | color: green;
|
395 | }
|
396 | ._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 .global-class-name {
|
397 | color: blue;
|
398 | }
|
399 | ```
|
400 |
|
401 | > ℹ️ Identifiers are exported
|
402 |
|
403 | ```js
|
404 | exports.locals = {
|
405 | className: "_23_aKvs-b8bW2Vg3fwHozO",
|
406 | subClass: "_13LGdX8RMStbBE9w-t0gZ1",
|
407 | };
|
408 | ```
|
409 |
|
410 | CamelCase is recommended for local selectors. They are easier to use within the imported JS module.
|
411 |
|
412 | You can use `:local(#someId)`, but this is not recommended. Use classes instead of ids.
|
413 |
|
414 | ##### `Composing`
|
415 |
|
416 | When declaring a local classname you can compose a local class from another local classname.
|
417 |
|
418 | ```css
|
419 | :local(.className) {
|
420 | background: red;
|
421 | color: yellow;
|
422 | }
|
423 |
|
424 | :local(.subClass) {
|
425 | composes: className;
|
426 | background: blue;
|
427 | }
|
428 | ```
|
429 |
|
430 | This doesn't result in any change to the CSS itself but exports multiple classnames.
|
431 |
|
432 | ```js
|
433 | exports.locals = {
|
434 | className: "_23_aKvs-b8bW2Vg3fwHozO",
|
435 | subClass: "_13LGdX8RMStbBE9w-t0gZ1 _23_aKvs-b8bW2Vg3fwHozO",
|
436 | };
|
437 | ```
|
438 |
|
439 | ```css
|
440 | ._23_aKvs-b8bW2Vg3fwHozO {
|
441 | background: red;
|
442 | color: yellow;
|
443 | }
|
444 |
|
445 | ._13LGdX8RMStbBE9w-t0gZ1 {
|
446 | background: blue;
|
447 | }
|
448 | ```
|
449 |
|
450 | ##### `Importing`
|
451 |
|
452 | To import a local classname from another module.
|
453 |
|
454 | > 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.
|
455 |
|
456 | ```css
|
457 | :local(.continueButton) {
|
458 | composes: button from "library/button.css";
|
459 | background: red;
|
460 | }
|
461 | ```
|
462 |
|
463 | ```css
|
464 | :local(.nameEdit) {
|
465 | composes: edit highlight from "./edit.css";
|
466 | background: red;
|
467 | }
|
468 | ```
|
469 |
|
470 | To import from multiple modules use multiple `composes:` rules.
|
471 |
|
472 | ```css
|
473 | :local(.className) {
|
474 | composes: edit hightlight from "./edit.css";
|
475 | composes: button from "module/button.css";
|
476 | composes: classFromThisModule;
|
477 | background: red;
|
478 | }
|
479 | ```
|
480 |
|
481 | ##### `Values`
|
482 |
|
483 | You can use `@value` to specific values to be reused throughout a document.
|
484 |
|
485 | We recommend use prefix `v-` for values, `s-` for selectors and `m-` for media at-rules.
|
486 |
|
487 | ```css
|
488 | @value v-primary: #BF4040;
|
489 | @value s-black: black-selector;
|
490 | @value m-large: (min-width: 960px);
|
491 |
|
492 | .header {
|
493 | color: v-primary;
|
494 | padding: 0 10px;
|
495 | }
|
496 |
|
497 | .s-black {
|
498 | color: black;
|
499 | }
|
500 |
|
501 | @media m-large {
|
502 | .header {
|
503 | padding: 0 20px;
|
504 | }
|
505 | }
|
506 | ```
|
507 |
|
508 | #### `boolean`
|
509 |
|
510 | Enable **CSS Modules** features.
|
511 |
|
512 | **webpack.config.js**
|
513 |
|
514 | ```js
|
515 | module.exports = {
|
516 | module: {
|
517 | rules: [
|
518 | {
|
519 | test: /\.css$/i,
|
520 | loader: "css-loader",
|
521 | options: {
|
522 | modules: true,
|
523 | },
|
524 | },
|
525 | ],
|
526 | },
|
527 | };
|
528 | ```
|
529 |
|
530 | #### `string`
|
531 |
|
532 | Enable **CSS Modules** features and setup `mode`.
|
533 |
|
534 | **webpack.config.js**
|
535 |
|
536 | ```js
|
537 | module.exports = {
|
538 | module: {
|
539 | rules: [
|
540 | {
|
541 | test: /\.css$/i,
|
542 | loader: "css-loader",
|
543 | options: {
|
544 | // Using `local` value has same effect like using `modules: true`
|
545 | modules: "global",
|
546 | },
|
547 | },
|
548 | ],
|
549 | },
|
550 | };
|
551 | ```
|
552 |
|
553 | #### `object`
|
554 |
|
555 | Enable **CSS Modules** features and setup options for them.
|
556 |
|
557 | **webpack.config.js**
|
558 |
|
559 | ```js
|
560 | module.exports = {
|
561 | module: {
|
562 | rules: [
|
563 | {
|
564 | test: /\.css$/i,
|
565 | loader: "css-loader",
|
566 | options: {
|
567 | modules: {
|
568 | mode: "local",
|
569 | auto: true,
|
570 | exportGlobals: true,
|
571 | localIdentName: "[path][name]__[local]--[hash:base64:5]",
|
572 | localIdentContext: path.resolve(__dirname, "src"),
|
573 | localIdentHashSalt: "my-custom-hash",
|
574 | namedExport: true,
|
575 | exportLocalsConvention: "camelCase",
|
576 | exportOnlyLocals: false,
|
577 | },
|
578 | },
|
579 | },
|
580 | ],
|
581 | },
|
582 | };
|
583 | ```
|
584 |
|
585 | ##### `auto`
|
586 |
|
587 | Type:
|
588 |
|
589 | ```ts
|
590 | type auto = boolean | regExp | ((resourcePath: string) => boolean);
|
591 | ```
|
592 |
|
593 | Default: `undefined`
|
594 |
|
595 | Allows auto enable CSS modules/ICSS based on filename when `modules` option is object.
|
596 |
|
597 | Possible values:
|
598 |
|
599 | - `undefined` - enable CSS modules for all files.
|
600 | - `true` - enable CSS modules for all files matching `/\.module\.\w+$/i.test(filename)` and `/\.icss\.\w+$/i.test(filename)` regexp.
|
601 | - `false` - disables CSS Modules.
|
602 | - `RegExp` - enable CSS modules for all files matching `/RegExp/i.test(filename)` regexp.
|
603 | - `function` - enable CSS Modules for files based on the filename satisfying your filter function check.
|
604 |
|
605 | ###### `boolean`
|
606 |
|
607 | Possible values:
|
608 |
|
609 | - `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
|
610 | - `false` - disables CSS modules or interoperable CSS format based on filename
|
611 |
|
612 | **webpack.config.js**
|
613 |
|
614 | ```js
|
615 | module.exports = {
|
616 | module: {
|
617 | rules: [
|
618 | {
|
619 | test: /\.css$/i,
|
620 | loader: "css-loader",
|
621 | options: {
|
622 | modules: {
|
623 | auto: true,
|
624 | },
|
625 | },
|
626 | },
|
627 | ],
|
628 | },
|
629 | };
|
630 | ```
|
631 |
|
632 | ###### `RegExp`
|
633 |
|
634 | Enable css modules for files based on the filename satisfying your regex check.
|
635 |
|
636 | **webpack.config.js**
|
637 |
|
638 | ```js
|
639 | module.exports = {
|
640 | module: {
|
641 | rules: [
|
642 | {
|
643 | test: /\.css$/i,
|
644 | loader: "css-loader",
|
645 | options: {
|
646 | modules: {
|
647 | auto: /\.custom-module\.\w+$/i,
|
648 | },
|
649 | },
|
650 | },
|
651 | ],
|
652 | },
|
653 | };
|
654 | ```
|
655 |
|
656 | ###### `function`
|
657 |
|
658 | Enable css modules for files based on the filename satisfying your filter function check.
|
659 |
|
660 | **webpack.config.js**
|
661 |
|
662 | ```js
|
663 | module.exports = {
|
664 | module: {
|
665 | rules: [
|
666 | {
|
667 | test: /\.css$/i,
|
668 | loader: "css-loader",
|
669 | options: {
|
670 | modules: {
|
671 | auto: (resourcePath) => resourcePath.endsWith(".custom-module.css"),
|
672 | },
|
673 | },
|
674 | },
|
675 | ],
|
676 | },
|
677 | };
|
678 | ```
|
679 |
|
680 | ##### `mode`
|
681 |
|
682 | Type:
|
683 |
|
684 | ```ts
|
685 | type mode =
|
686 | | "local"
|
687 | | "global"
|
688 | | "pure"
|
689 | | "icss"
|
690 | | ((resourcePath) => "local" | "global" | "pure" | "icss"))`
|
691 | ```
|
692 |
|
693 | Default: `'local'`
|
694 |
|
695 | Setup `mode` option. You can omit the value when you want `local` mode.
|
696 |
|
697 | Controls the level of compilation applied to the input styles.
|
698 |
|
699 | The `local`, `global`, and `pure` handles `class` and `id` scoping and `@value` values.
|
700 | The `icss` will only compile the low level `Interoperable CSS` format for declaring `:import` and `:export` dependencies between CSS and other languages.
|
701 |
|
702 | ICSS underpins CSS Module support, and provides a low level syntax for other tools to implement CSS-module variations of their own.
|
703 |
|
704 | ###### `string`
|
705 |
|
706 | Possible values - `local`, `global`, `pure`, and `icss`.
|
707 |
|
708 | **webpack.config.js**
|
709 |
|
710 | ```js
|
711 | module.exports = {
|
712 | module: {
|
713 | rules: [
|
714 | {
|
715 | test: /\.css$/i,
|
716 | loader: "css-loader",
|
717 | options: {
|
718 | modules: {
|
719 | mode: "global",
|
720 | },
|
721 | },
|
722 | },
|
723 | ],
|
724 | },
|
725 | };
|
726 | ```
|
727 |
|
728 | ###### `function`
|
729 |
|
730 | Allows set different values for the `mode` option based on a filename
|
731 |
|
732 | Possible return values - `local`, `global`, `pure` and `icss`.
|
733 |
|
734 | **webpack.config.js**
|
735 |
|
736 | ```js
|
737 | module.exports = {
|
738 | module: {
|
739 | rules: [
|
740 | {
|
741 | test: /\.css$/i,
|
742 | loader: "css-loader",
|
743 | options: {
|
744 | modules: {
|
745 | // Callback must return "local", "global", or "pure" values
|
746 | mode: (resourcePath) => {
|
747 | if (/pure.css$/i.test(resourcePath)) {
|
748 | return "pure";
|
749 | }
|
750 |
|
751 | if (/global.css$/i.test(resourcePath)) {
|
752 | return "global";
|
753 | }
|
754 |
|
755 | return "local";
|
756 | },
|
757 | },
|
758 | },
|
759 | },
|
760 | ],
|
761 | },
|
762 | };
|
763 | ```
|
764 |
|
765 | ##### `localIdentName`
|
766 |
|
767 | Type:
|
768 |
|
769 | ```ts
|
770 | type localIdentName = string;
|
771 | ```
|
772 |
|
773 | Default: `'[hash:base64]'`
|
774 |
|
775 | Allows to configure the generated local ident name.
|
776 |
|
777 | For more information on options see:
|
778 |
|
779 | - [webpack template strings](https://webpack.js.org/configuration/output/#template-strings),
|
780 | - [output.hashDigest](https://webpack.js.org/configuration/output/#outputhashdigest),
|
781 | - [output.hashDigestLength](https://webpack.js.org/configuration/output/#outputhashdigestlength),
|
782 | - [output.hashFunction](https://webpack.js.org/configuration/output/#outputhashfunction),
|
783 | - [output.hashSalt](https://webpack.js.org/configuration/output/#outputhashsalt).
|
784 |
|
785 | Supported template strings:
|
786 |
|
787 | - `[name]` the basename of the resource
|
788 | - `[folder]` the folder the resource relative to the `compiler.context` option or `modules.localIdentContext` option.
|
789 | - `[path]` the path of the resource relative to the `compiler.context` option or `modules.localIdentContext` option.
|
790 | - `[file]` - filename and path.
|
791 | - `[ext]` - extension with leading `.`.
|
792 | - `[hash]` - the hash of the string, generated based on `localIdentHashSalt`, `localIdentHashFunction`, `localIdentHashDigest`, `localIdentHashDigestLength`, `localIdentContext`, `resourcePath` and `exportName`
|
793 | - `[<hashFunction>:hash:<hashDigest>:<hashDigestLength>]` - hash with hash settings.
|
794 | - `[local]` - original class.
|
795 |
|
796 | Recommendations:
|
797 |
|
798 | - use `'[path][name]__[local]'` for development
|
799 | - use `'[hash:base64]'` for production
|
800 |
|
801 | The `[local]` placeholder contains original class.
|
802 |
|
803 | **Note:** all reserved (`<>:"/\|?*`) and control filesystem characters (excluding characters in the `[local]` placeholder) will be converted to `-`.
|
804 |
|
805 | **webpack.config.js**
|
806 |
|
807 | ```js
|
808 | module.exports = {
|
809 | module: {
|
810 | rules: [
|
811 | {
|
812 | test: /\.css$/i,
|
813 | loader: "css-loader",
|
814 | options: {
|
815 | modules: {
|
816 | localIdentName: "[path][name]__[local]--[hash:base64:5]",
|
817 | },
|
818 | },
|
819 | },
|
820 | ],
|
821 | },
|
822 | };
|
823 | ```
|
824 |
|
825 | ##### `localIdentContext`
|
826 |
|
827 | Type:
|
828 |
|
829 | ```ts
|
830 | type localIdentContex = string;
|
831 | ```
|
832 |
|
833 | Default: `compiler.context`
|
834 |
|
835 | Allows to redefine basic loader context for local ident name.
|
836 |
|
837 | **webpack.config.js**
|
838 |
|
839 | ```js
|
840 | module.exports = {
|
841 | module: {
|
842 | rules: [
|
843 | {
|
844 | test: /\.css$/i,
|
845 | loader: "css-loader",
|
846 | options: {
|
847 | modules: {
|
848 | localIdentContext: path.resolve(__dirname, "src"),
|
849 | },
|
850 | },
|
851 | },
|
852 | ],
|
853 | },
|
854 | };
|
855 | ```
|
856 |
|
857 | ##### `localIdentHashSalt`
|
858 |
|
859 | Type:
|
860 |
|
861 | ```ts
|
862 | type localIdentHashSalt = string;
|
863 | ```
|
864 |
|
865 | Default: `undefined`
|
866 |
|
867 | Allows to add custom hash to generate more unique classes.
|
868 | For more information see [output.hashSalt](https://webpack.js.org/configuration/output/#outputhashsalt).
|
869 |
|
870 | **webpack.config.js**
|
871 |
|
872 | ```js
|
873 | module.exports = {
|
874 | module: {
|
875 | rules: [
|
876 | {
|
877 | test: /\.css$/i,
|
878 | loader: "css-loader",
|
879 | options: {
|
880 | modules: {
|
881 | localIdentHashSalt: "hash",
|
882 | },
|
883 | },
|
884 | },
|
885 | ],
|
886 | },
|
887 | };
|
888 | ```
|
889 |
|
890 | ##### `localIdentHashFunction`
|
891 |
|
892 | Type:
|
893 |
|
894 | ```ts
|
895 | type localIdentHashFunction = string;
|
896 | ```
|
897 |
|
898 | Default: `md4`
|
899 |
|
900 | Allows to specify hash function to generate classes .
|
901 | For more information see [output.hashFunction](https://webpack.js.org/configuration/output/#outputhashfunction).
|
902 |
|
903 | **webpack.config.js**
|
904 |
|
905 | ```js
|
906 | module.exports = {
|
907 | module: {
|
908 | rules: [
|
909 | {
|
910 | test: /\.css$/i,
|
911 | loader: "css-loader",
|
912 | options: {
|
913 | modules: {
|
914 | localIdentHashFunction: "md4",
|
915 | },
|
916 | },
|
917 | },
|
918 | ],
|
919 | },
|
920 | };
|
921 | ```
|
922 |
|
923 | ##### `localIdentHashDigest`
|
924 |
|
925 | Type:
|
926 |
|
927 | ```ts
|
928 | type localIdentHashDigest = string;
|
929 | ```
|
930 |
|
931 | Default: `hex`
|
932 |
|
933 | Allows to specify hash digest to generate classes.
|
934 | For more information see [output.hashDigest](https://webpack.js.org/configuration/output/#outputhashdigest).
|
935 |
|
936 | **webpack.config.js**
|
937 |
|
938 | ```js
|
939 | module.exports = {
|
940 | module: {
|
941 | rules: [
|
942 | {
|
943 | test: /\.css$/i,
|
944 | loader: "css-loader",
|
945 | options: {
|
946 | modules: {
|
947 | localIdentHashDigest: "base64",
|
948 | },
|
949 | },
|
950 | },
|
951 | ],
|
952 | },
|
953 | };
|
954 | ```
|
955 |
|
956 | ##### `localIdentHashDigestLength`
|
957 |
|
958 | Type:
|
959 |
|
960 | ```ts
|
961 | type localIdentHashDigestLength = number;
|
962 | ```
|
963 |
|
964 | Default: `20`
|
965 |
|
966 | Allows to specify hash digest length to generate classes.
|
967 | For more information see [output.hashDigestLength](https://webpack.js.org/configuration/output/#outputhashdigestlength).
|
968 |
|
969 | **webpack.config.js**
|
970 |
|
971 | ```js
|
972 | module.exports = {
|
973 | module: {
|
974 | rules: [
|
975 | {
|
976 | test: /\.css$/i,
|
977 | loader: "css-loader",
|
978 | options: {
|
979 | modules: {
|
980 | localIdentHashDigestLength: 5,
|
981 | },
|
982 | },
|
983 | },
|
984 | ],
|
985 | },
|
986 | };
|
987 | ```
|
988 |
|
989 | ##### `hashStrategy`
|
990 |
|
991 | Type: `'resource-path-and-local-name' | 'minimal-subset'`
|
992 | Default: `'resource-path-and-local-name'`
|
993 |
|
994 | Should local name be used when computing the hash.
|
995 |
|
996 | - `'resource-path-and-local-name'` Both resource path and local name are used when hashing. Each identifier in a module gets its own hash digest, always.
|
997 | - `'minimal-subset'` Auto detect if identifier names can be omitted from hashing. Use this value to optimize the output for better GZIP or Brotli compression.
|
998 |
|
999 | **webpack.config.js**
|
1000 |
|
1001 | ```js
|
1002 | module.exports = {
|
1003 | module: {
|
1004 | rules: [
|
1005 | {
|
1006 | test: /\.css$/i,
|
1007 | loader: "css-loader",
|
1008 | options: {
|
1009 | modules: {
|
1010 | hashStrategy: "minimal-subset",
|
1011 | },
|
1012 | },
|
1013 | },
|
1014 | ],
|
1015 | },
|
1016 | };
|
1017 | ```
|
1018 |
|
1019 | ##### `localIdentRegExp`
|
1020 |
|
1021 | Type:
|
1022 |
|
1023 | ```ts
|
1024 | type localIdentRegExp = string | RegExp;
|
1025 | ```
|
1026 |
|
1027 | Default: `undefined`
|
1028 |
|
1029 | **webpack.config.js**
|
1030 |
|
1031 | ```js
|
1032 | module.exports = {
|
1033 | module: {
|
1034 | rules: [
|
1035 | {
|
1036 | test: /\.css$/i,
|
1037 | loader: "css-loader",
|
1038 | options: {
|
1039 | modules: {
|
1040 | localIdentRegExp: /page-(.*)\.css/i,
|
1041 | },
|
1042 | },
|
1043 | },
|
1044 | ],
|
1045 | },
|
1046 | };
|
1047 | ```
|
1048 |
|
1049 | ##### `getLocalIdent`
|
1050 |
|
1051 | Type:
|
1052 |
|
1053 | ```ts
|
1054 | type getLocalIdent = (
|
1055 | context: LoaderContext,
|
1056 | localIdentName: string,
|
1057 | localName: string
|
1058 | ) => string;
|
1059 | ```
|
1060 |
|
1061 | Default: `undefined`
|
1062 |
|
1063 | Allows to specify a function to generate the classname.
|
1064 | By default we use built-in function to generate a classname.
|
1065 | If the custom function returns `null` or `undefined`, we fallback to the
|
1066 | built-in function to generate the classname.
|
1067 |
|
1068 | **webpack.config.js**
|
1069 |
|
1070 | ```js
|
1071 | module.exports = {
|
1072 | module: {
|
1073 | rules: [
|
1074 | {
|
1075 | test: /\.css$/i,
|
1076 | loader: "css-loader",
|
1077 | options: {
|
1078 | modules: {
|
1079 | getLocalIdent: (context, localIdentName, localName, options) => {
|
1080 | return "whatever_random_class_name";
|
1081 | },
|
1082 | },
|
1083 | },
|
1084 | },
|
1085 | ],
|
1086 | },
|
1087 | };
|
1088 | ```
|
1089 |
|
1090 | ##### `namedExport`
|
1091 |
|
1092 | Type:
|
1093 |
|
1094 | ```ts
|
1095 | type namedExport = boolean;
|
1096 | ```
|
1097 |
|
1098 | Default: `false`
|
1099 |
|
1100 | Enables/disables ES modules named export for locals.
|
1101 |
|
1102 | > ⚠ Names of locals are converted to camelcase, i.e. the `exportLocalsConvention` option has `camelCaseOnly` value by default.
|
1103 |
|
1104 | > ⚠ It is not allowed to use JavaScript reserved words in css class names.
|
1105 |
|
1106 | **styles.css**
|
1107 |
|
1108 | ```css
|
1109 | .foo-baz {
|
1110 | color: red;
|
1111 | }
|
1112 | .bar {
|
1113 | color: blue;
|
1114 | }
|
1115 | ```
|
1116 |
|
1117 | **index.js**
|
1118 |
|
1119 | ```js
|
1120 | import { fooBaz, bar } from "./styles.css";
|
1121 |
|
1122 | console.log(fooBaz, bar);
|
1123 | ```
|
1124 |
|
1125 | You can enable a ES module named export using:
|
1126 |
|
1127 | **webpack.config.js**
|
1128 |
|
1129 | ```js
|
1130 | module.exports = {
|
1131 | module: {
|
1132 | rules: [
|
1133 | {
|
1134 | test: /\.css$/i,
|
1135 | loader: "css-loader",
|
1136 | options: {
|
1137 | esModule: true,
|
1138 | modules: {
|
1139 | namedExport: true,
|
1140 | },
|
1141 | },
|
1142 | },
|
1143 | ],
|
1144 | },
|
1145 | };
|
1146 | ```
|
1147 |
|
1148 | To set a custom name for namedExport, can use [`exportLocalsConvention`](#exportLocalsConvention) option as a function.
|
1149 | Example below in the [`examples`](#examples) section.
|
1150 |
|
1151 | ##### `exportGlobals`
|
1152 |
|
1153 | Type:
|
1154 |
|
1155 | ```ts
|
1156 | type exportsGLobals = boolean;
|
1157 | ```
|
1158 |
|
1159 | Default: `false`
|
1160 |
|
1161 | Allow `css-loader` to export names from global class or id, so you can use that as local name.
|
1162 |
|
1163 | **webpack.config.js**
|
1164 |
|
1165 | ```js
|
1166 | module.exports = {
|
1167 | module: {
|
1168 | rules: [
|
1169 | {
|
1170 | test: /\.css$/i,
|
1171 | loader: "css-loader",
|
1172 | options: {
|
1173 | modules: {
|
1174 | exportGlobals: true,
|
1175 | },
|
1176 | },
|
1177 | },
|
1178 | ],
|
1179 | },
|
1180 | };
|
1181 | ```
|
1182 |
|
1183 | ##### `exportLocalsConvention`
|
1184 |
|
1185 | Type:
|
1186 |
|
1187 | ```ts
|
1188 | type exportLocalsConvention =
|
1189 | | "asIs"
|
1190 | | "camelCase"
|
1191 | | "camelCaseOnly"
|
1192 | | "dashes"
|
1193 | | "dashesOnly"
|
1194 | | ((name: string) => string);
|
1195 | ```
|
1196 |
|
1197 | Default: based on the `modules.namedExport` option value, if `true` - `camelCaseOnly`, otherwise `asIs`
|
1198 |
|
1199 | Style of exported class names.
|
1200 |
|
1201 | ###### `string`
|
1202 |
|
1203 | By default, the exported JSON keys mirror the class names (i.e `asIs` value).
|
1204 |
|
1205 | > ⚠ Only `camelCaseOnly` value allowed if you set the `namedExport` value to `true`.
|
1206 |
|
1207 | | Name | Type | Description |
|
1208 | | :-------------------: | :------: | :----------------------------------------------------------------------------------------------- |
|
1209 | | **`'asIs'`** | `string` | Class names will be exported as is. |
|
1210 | | **`'camelCase'`** | `string` | Class names will be camelized, the original class name will not to be removed from the locals |
|
1211 | | **`'camelCaseOnly'`** | `string` | Class names will be camelized, the original class name will be removed from the locals |
|
1212 | | **`'dashes'`** | `string` | Only dashes in class names will be camelized |
|
1213 | | **`'dashesOnly'`** | `string` | Dashes in class names will be camelized, the original class name will be removed from the locals |
|
1214 |
|
1215 | **file.css**
|
1216 |
|
1217 | ```css
|
1218 | .class-name {
|
1219 | }
|
1220 | ```
|
1221 |
|
1222 | **file.js**
|
1223 |
|
1224 | ```js
|
1225 | import { className } from "file.css";
|
1226 | ```
|
1227 |
|
1228 | **webpack.config.js**
|
1229 |
|
1230 | ```js
|
1231 | module.exports = {
|
1232 | module: {
|
1233 | rules: [
|
1234 | {
|
1235 | test: /\.css$/i,
|
1236 | loader: "css-loader",
|
1237 | options: {
|
1238 | modules: {
|
1239 | exportLocalsConvention: "camelCase",
|
1240 | },
|
1241 | },
|
1242 | },
|
1243 | ],
|
1244 | },
|
1245 | };
|
1246 | ```
|
1247 |
|
1248 | ###### `function`
|
1249 |
|
1250 | **webpack.config.js**
|
1251 |
|
1252 | ```js
|
1253 | module.exports = {
|
1254 | module: {
|
1255 | rules: [
|
1256 | {
|
1257 | test: /\.css$/i,
|
1258 | loader: "css-loader",
|
1259 | options: {
|
1260 | modules: {
|
1261 | exportLocalsConvention: function (name) {
|
1262 | return name.replace(/-/g, "_");
|
1263 | },
|
1264 | },
|
1265 | },
|
1266 | },
|
1267 | ],
|
1268 | },
|
1269 | };
|
1270 | ```
|
1271 |
|
1272 | **webpack.config.js**
|
1273 |
|
1274 | ```js
|
1275 | module.exports = {
|
1276 | module: {
|
1277 | rules: [
|
1278 | {
|
1279 | test: /\.css$/i,
|
1280 | loader: "css-loader",
|
1281 | options: {
|
1282 | modules: {
|
1283 | exportLocalsConvention: function (name) {
|
1284 | return [
|
1285 | name.replace(/-/g, "_"),
|
1286 | // dashesCamelCase
|
1287 | name.replace(/-+(\w)/g, (match, firstLetter) =>
|
1288 | firstLetter.toUpperCase()
|
1289 | ),
|
1290 | ];
|
1291 | },
|
1292 | },
|
1293 | },
|
1294 | },
|
1295 | ],
|
1296 | },
|
1297 | };
|
1298 | ```
|
1299 |
|
1300 | ##### `exportOnlyLocals`
|
1301 |
|
1302 | Type:
|
1303 |
|
1304 | ```ts
|
1305 | type exportOnlyLocals = boolean;
|
1306 | ```
|
1307 |
|
1308 | Default: `false`
|
1309 |
|
1310 | Export only locals.
|
1311 |
|
1312 | **Useful** when you use **css modules** for pre-rendering (for example SSR).
|
1313 | For pre-rendering with `mini-css-extract-plugin` you should use this option instead of `style-loader!css-loader` **in the pre-rendering bundle**.
|
1314 | It doesn't embed CSS but only exports the identifier mappings.
|
1315 |
|
1316 | **webpack.config.js**
|
1317 |
|
1318 | ```js
|
1319 | module.exports = {
|
1320 | module: {
|
1321 | rules: [
|
1322 | {
|
1323 | test: /\.css$/i,
|
1324 | loader: "css-loader",
|
1325 | options: {
|
1326 | modules: {
|
1327 | exportOnlyLocals: true,
|
1328 | },
|
1329 | },
|
1330 | },
|
1331 | ],
|
1332 | },
|
1333 | };
|
1334 | ```
|
1335 |
|
1336 | ### `importLoaders`
|
1337 |
|
1338 | Type:
|
1339 |
|
1340 | ```ts
|
1341 | type importLoaders = number;
|
1342 | ```
|
1343 |
|
1344 | Default: `0`
|
1345 |
|
1346 | Allows 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.
|
1347 |
|
1348 | The option `importLoaders` allows you to configure how many loaders before `css-loader` should be applied to `@import`ed resources and CSS modules/ICSS imports.
|
1349 |
|
1350 | **webpack.config.js**
|
1351 |
|
1352 | ```js
|
1353 | module.exports = {
|
1354 | module: {
|
1355 | rules: [
|
1356 | {
|
1357 | test: /\.css$/i,
|
1358 | use: [
|
1359 | "style-loader",
|
1360 | {
|
1361 | loader: "css-loader",
|
1362 | options: {
|
1363 | importLoaders: 2,
|
1364 | // 0 => no loaders (default);
|
1365 | // 1 => postcss-loader;
|
1366 | // 2 => postcss-loader, sass-loader
|
1367 | },
|
1368 | },
|
1369 | "postcss-loader",
|
1370 | "sass-loader",
|
1371 | ],
|
1372 | },
|
1373 | ],
|
1374 | },
|
1375 | };
|
1376 | ```
|
1377 |
|
1378 | This may change in the future when the module system (i. e. webpack) supports loader matching by origin.
|
1379 |
|
1380 | ### `sourceMap`
|
1381 |
|
1382 | Type:
|
1383 |
|
1384 | ```ts
|
1385 | type sourceMap = boolean;
|
1386 | ```
|
1387 |
|
1388 | Default: depends on the `compiler.devtool` value
|
1389 |
|
1390 | By 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.
|
1391 |
|
1392 | **webpack.config.js**
|
1393 |
|
1394 | ```js
|
1395 | module.exports = {
|
1396 | module: {
|
1397 | rules: [
|
1398 | {
|
1399 | test: /\.css$/i,
|
1400 | loader: "css-loader",
|
1401 | options: {
|
1402 | sourceMap: true,
|
1403 | },
|
1404 | },
|
1405 | ],
|
1406 | },
|
1407 | };
|
1408 | ```
|
1409 |
|
1410 | ### `esModule`
|
1411 |
|
1412 | Type:
|
1413 |
|
1414 | ```ts
|
1415 | type esModule = boolean;
|
1416 | ```
|
1417 |
|
1418 | Default: `true`
|
1419 |
|
1420 | By default, `css-loader` generates JS modules that use the ES modules syntax.
|
1421 | There 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/).
|
1422 |
|
1423 | You can enable a CommonJS modules syntax using:
|
1424 |
|
1425 | **webpack.config.js**
|
1426 |
|
1427 | ```js
|
1428 | module.exports = {
|
1429 | module: {
|
1430 | rules: [
|
1431 | {
|
1432 | test: /\.css$/i,
|
1433 | loader: "css-loader",
|
1434 | options: {
|
1435 | esModule: false,
|
1436 | },
|
1437 | },
|
1438 | ],
|
1439 | },
|
1440 | };
|
1441 | ```
|
1442 |
|
1443 | ### `exportType`
|
1444 |
|
1445 | Type:
|
1446 |
|
1447 | ```ts
|
1448 | type exportType = "array" | "string" | "css-style-sheet";
|
1449 | ```
|
1450 |
|
1451 | Default: `'array'`
|
1452 |
|
1453 | Allows exporting styles as array with modules, string or [constructable stylesheet](https://developers.google.com/web/updates/2019/02/constructable-stylesheets) (i.e. [`CSSStyleSheet`](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet)).
|
1454 | Default value is `'array'`, i.e. loader exports array of modules with specific API which is used in `style-loader` or other.
|
1455 |
|
1456 | **webpack.config.js**
|
1457 |
|
1458 | ```js
|
1459 | module.exports = {
|
1460 | module: {
|
1461 | rules: [
|
1462 | {
|
1463 | assert: { type: "css" },
|
1464 | loader: "css-loader",
|
1465 | options: {
|
1466 | exportType: "css-style-sheet",
|
1467 | },
|
1468 | },
|
1469 | ],
|
1470 | },
|
1471 | };
|
1472 | ```
|
1473 |
|
1474 | **src/index.js**
|
1475 |
|
1476 | ```js
|
1477 | import sheet from "./styles.css" assert { type: "css" };
|
1478 |
|
1479 | document.adoptedStyleSheets = [sheet];
|
1480 | shadowRoot.adoptedStyleSheets = [sheet];
|
1481 | ```
|
1482 |
|
1483 | #### `'array'`
|
1484 |
|
1485 | The default export is array of modules with specific API which is used in `style-loader` or other.
|
1486 |
|
1487 | **webpack.config.js**
|
1488 |
|
1489 | ```js
|
1490 | module.exports = {
|
1491 | module: {
|
1492 | rules: [
|
1493 | {
|
1494 | test: /\.(sa|sc|c)ss$/i,
|
1495 | use: ["style-loader", "css-loader", "postcss-loader", "sass-loader"],
|
1496 | },
|
1497 | ],
|
1498 | },
|
1499 | };
|
1500 | ```
|
1501 |
|
1502 | **src/index.js**
|
1503 |
|
1504 | ```js
|
1505 | // `style-loader` applies styles to DOM
|
1506 | import "./styles.css";
|
1507 | ```
|
1508 |
|
1509 | #### `'string'`
|
1510 |
|
1511 | > ⚠ You don't need [`style-loader`](https://github.com/webpack-contrib/style-loader) anymore, please remove it.
|
1512 | > ⚠ The `esModules` option should be enabled if you want to use it with [`CSS modules`](https://github.com/webpack-contrib/css-loader#modules), by default for locals will be used [named export](https://github.com/webpack-contrib/css-loader#namedexport).
|
1513 |
|
1514 | The default export is `string`.
|
1515 |
|
1516 | **webpack.config.js**
|
1517 |
|
1518 | ```js
|
1519 | module.exports = {
|
1520 | module: {
|
1521 | rules: [
|
1522 | {
|
1523 | test: /\.(sa|sc|c)ss$/i,
|
1524 | use: ["css-loader", "postcss-loader", "sass-loader"],
|
1525 | },
|
1526 | ],
|
1527 | },
|
1528 | };
|
1529 | ```
|
1530 |
|
1531 | **src/index.js**
|
1532 |
|
1533 | ```js
|
1534 | import sheet from "./styles.css";
|
1535 |
|
1536 | console.log(sheet);
|
1537 | ```
|
1538 |
|
1539 | #### `'css-style-sheet'`
|
1540 |
|
1541 | > ⚠ `@import` rules not yet allowed, more [information](https://web.dev/css-module-scripts/#@import-rules-not-yet-allowed)
|
1542 | > ⚠ You don't need [`style-loader`](https://github.com/webpack-contrib/style-loader) anymore, please remove it.
|
1543 | > ⚠ The `esModules` option should be enabled if you want to use it with [`CSS modules`](https://github.com/webpack-contrib/css-loader#modules), by default for locals will be used [named export](https://github.com/webpack-contrib/css-loader#namedexport).
|
1544 | > ⚠ Source maps are not currently supported in `Chrome` due [bug](https://bugs.chromium.org/p/chromium/issues/detail?id=1174094&q=CSSStyleSheet%20source%20maps&can=2)
|
1545 |
|
1546 | The default export is a [constructable stylesheet](https://developers.google.com/web/updates/2019/02/constructable-stylesheets) (i.e. [`CSSStyleSheet`](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet)).
|
1547 |
|
1548 | Useful for [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) and shadow DOM.
|
1549 |
|
1550 | More information:
|
1551 |
|
1552 | - [Using CSS Module Scripts to import stylesheets](https://web.dev/css-module-scripts/)
|
1553 | - [Constructable Stylesheets: seamless reusable styles](https://developers.google.com/web/updates/2019/02/constructable-stylesheets)
|
1554 |
|
1555 | **webpack.config.js**
|
1556 |
|
1557 | ```js
|
1558 | module.exports = {
|
1559 | module: {
|
1560 | rules: [
|
1561 | {
|
1562 | assert: { type: "css" },
|
1563 | loader: "css-loader",
|
1564 | options: {
|
1565 | exportType: "css-style-sheet",
|
1566 | },
|
1567 | },
|
1568 |
|
1569 | // For Sass/SCSS:
|
1570 | //
|
1571 | // {
|
1572 | // assert: { type: "css" },
|
1573 | // rules: [
|
1574 | // {
|
1575 | // loader: "css-loader",
|
1576 | // options: {
|
1577 | // exportType: "css-style-sheet",
|
1578 | // // Other options
|
1579 | // },
|
1580 | // },
|
1581 | // {
|
1582 | // loader: "sass-loader",
|
1583 | // options: {
|
1584 | // // Other options
|
1585 | // },
|
1586 | // },
|
1587 | // ],
|
1588 | // },
|
1589 | ],
|
1590 | },
|
1591 | };
|
1592 | ```
|
1593 |
|
1594 | **src/index.js**
|
1595 |
|
1596 | ```js
|
1597 | // Example for Sass/SCSS:
|
1598 | // import sheet from "./styles.scss" assert { type: "css" };
|
1599 |
|
1600 | // Example for CSS modules:
|
1601 | // import sheet, { myClass } from "./styles.scss" assert { type: "css" };
|
1602 |
|
1603 | // Example for CSS:
|
1604 | import sheet from "./styles.css" assert { type: "css" };
|
1605 |
|
1606 | document.adoptedStyleSheets = [sheet];
|
1607 | shadowRoot.adoptedStyleSheets = [sheet];
|
1608 | ```
|
1609 |
|
1610 | For migration purposes, you can use the following configuration:
|
1611 |
|
1612 | ```js
|
1613 | module.exports = {
|
1614 | module: {
|
1615 | rules: [
|
1616 | {
|
1617 | test: /\.css$/i,
|
1618 | oneOf: [
|
1619 | {
|
1620 | assert: { type: "css" },
|
1621 | loader: "css-loader",
|
1622 | options: {
|
1623 | exportType: "css-style-sheet",
|
1624 | // Other options
|
1625 | },
|
1626 | },
|
1627 | {
|
1628 | use: [
|
1629 | "style-loader",
|
1630 | {
|
1631 | loader: "css-loader",
|
1632 | options: {
|
1633 | // Other options
|
1634 | },
|
1635 | },
|
1636 | ],
|
1637 | },
|
1638 | ],
|
1639 | },
|
1640 | ],
|
1641 | },
|
1642 | };
|
1643 | ```
|
1644 |
|
1645 | ## Examples
|
1646 |
|
1647 | ### Recommend
|
1648 |
|
1649 | For `production` builds it's recommended to extract the CSS from your bundle being able to use parallel loading of CSS/JS resources later on.
|
1650 | This 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.
|
1651 | For `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.
|
1652 |
|
1653 | > i Do not use `style-loader` and `mini-css-extract-plugin` together.
|
1654 |
|
1655 | **webpack.config.js**
|
1656 |
|
1657 | ```js
|
1658 | const MiniCssExtractPlugin = require("mini-css-extract-plugin");
|
1659 | const devMode = process.env.NODE_ENV !== "production";
|
1660 |
|
1661 | module.exports = {
|
1662 | module: {
|
1663 | rules: [
|
1664 | {
|
1665 | test: /\.(sa|sc|c)ss$/i,
|
1666 | use: [
|
1667 | devMode ? "style-loader" : MiniCssExtractPlugin.loader,
|
1668 | "css-loader",
|
1669 | "postcss-loader",
|
1670 | "sass-loader",
|
1671 | ],
|
1672 | },
|
1673 | ],
|
1674 | },
|
1675 | plugins: [].concat(devMode ? [] : [new MiniCssExtractPlugin()]),
|
1676 | };
|
1677 | ```
|
1678 |
|
1679 | ### Disable url resolving using the `/* webpackIgnore: true */` comment
|
1680 |
|
1681 | With the help of the `/* webpackIgnore: true */`comment, it is possible to disable sources handling for rules and for individual declarations.
|
1682 |
|
1683 | ```css
|
1684 | /* webpackIgnore: true */
|
1685 | @import url(./basic.css);
|
1686 | @import /* webpackIgnore: true */ url(./imported.css);
|
1687 |
|
1688 | .class {
|
1689 | /* Disabled url handling for the all urls in the 'background' declaration */
|
1690 | color: red;
|
1691 | /* webpackIgnore: true */
|
1692 | background: url("./url/img.png"), url("./url/img.png");
|
1693 | }
|
1694 |
|
1695 | .class {
|
1696 | /* Disabled url handling for the first url in the 'background' declaration */
|
1697 | color: red;
|
1698 | background:
|
1699 | /* webpackIgnore: true */ url("./url/img.png"), url("./url/img.png");
|
1700 | }
|
1701 |
|
1702 | .class {
|
1703 | /* Disabled url handling for the second url in the 'background' declaration */
|
1704 | color: red;
|
1705 | background: url("./url/img.png"),
|
1706 | /* webpackIgnore: true */ url("./url/img.png");
|
1707 | }
|
1708 |
|
1709 | /* prettier-ignore */
|
1710 | .class {
|
1711 | /* Disabled url handling for the second url in the 'background' declaration */
|
1712 | color: red;
|
1713 | background: url("./url/img.png"),
|
1714 | /* webpackIgnore: true */
|
1715 | url("./url/img.png");
|
1716 | }
|
1717 |
|
1718 | /* prettier-ignore */
|
1719 | .class {
|
1720 | /* Disabled url handling for third and sixth urls in the 'background-image' declaration */
|
1721 | background-image: image-set(
|
1722 | url(./url/img.png) 2x,
|
1723 | url(./url/img.png) 3x,
|
1724 | /* webpackIgnore: true */ url(./url/img.png) 4x,
|
1725 | url(./url/img.png) 5x,
|
1726 | url(./url/img.png) 6x,
|
1727 | /* webpackIgnore: true */
|
1728 | url(./url/img.png) 7x
|
1729 | );
|
1730 | }
|
1731 | ```
|
1732 |
|
1733 | ### Assets
|
1734 |
|
1735 | The 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.
|
1736 |
|
1737 | **For webpack v5:**
|
1738 |
|
1739 | **webpack.config.js**
|
1740 |
|
1741 | ```js
|
1742 | module.exports = {
|
1743 | module: {
|
1744 | rules: [
|
1745 | {
|
1746 | test: /\.css$/i,
|
1747 | use: ["style-loader", "css-loader"],
|
1748 | },
|
1749 | {
|
1750 | test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
|
1751 | // More information here https://webpack.js.org/guides/asset-modules/
|
1752 | type: "asset",
|
1753 | },
|
1754 | ],
|
1755 | },
|
1756 | };
|
1757 | ```
|
1758 |
|
1759 | ### Extract
|
1760 |
|
1761 | For production builds it's recommended to extract the CSS from your bundle being able to use parallel loading of CSS/JS resources later on.
|
1762 |
|
1763 | - 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.
|
1764 |
|
1765 | - 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
|
1766 |
|
1767 | ### Pure CSS, CSS modules and PostCSS
|
1768 |
|
1769 | When you have pure CSS (without CSS modules), CSS modules and PostCSS in your project you can use this setup:
|
1770 |
|
1771 | **webpack.config.js**
|
1772 |
|
1773 | ```js
|
1774 | module.exports = {
|
1775 | module: {
|
1776 | rules: [
|
1777 | {
|
1778 | // For pure CSS - /\.css$/i,
|
1779 | // For Sass/SCSS - /\.((c|sa|sc)ss)$/i,
|
1780 | // For Less - /\.((c|le)ss)$/i,
|
1781 | test: /\.((c|sa|sc)ss)$/i,
|
1782 | use: [
|
1783 | "style-loader",
|
1784 | {
|
1785 | loader: "css-loader",
|
1786 | options: {
|
1787 | // 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
|
1788 | // If you need run `sass-loader` and `postcss-loader` on each CSS `@import` please set it to `2`
|
1789 | importLoaders: 1,
|
1790 | },
|
1791 | },
|
1792 | {
|
1793 | loader: "postcss-loader",
|
1794 | options: { plugins: () => [postcssPresetEnv({ stage: 0 })] },
|
1795 | },
|
1796 | // Can be `less-loader`
|
1797 | {
|
1798 | loader: "sass-loader",
|
1799 | },
|
1800 | ],
|
1801 | },
|
1802 | // For webpack v5
|
1803 | {
|
1804 | test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
|
1805 | // More information here https://webpack.js.org/guides/asset-modules/
|
1806 | type: "asset",
|
1807 | },
|
1808 | ],
|
1809 | },
|
1810 | };
|
1811 | ```
|
1812 |
|
1813 | ### Resolve unresolved URLs using an alias
|
1814 |
|
1815 | **index.css**
|
1816 |
|
1817 | ```css
|
1818 | .class {
|
1819 | background: url(/assets/unresolved/img.png);
|
1820 | }
|
1821 | ```
|
1822 |
|
1823 | **webpack.config.js**
|
1824 |
|
1825 | ```js
|
1826 | module.exports = {
|
1827 | module: {
|
1828 | rules: [
|
1829 | {
|
1830 | test: /\.css$/i,
|
1831 | use: ["style-loader", "css-loader"],
|
1832 | },
|
1833 | ],
|
1834 | },
|
1835 | resolve: {
|
1836 | alias: {
|
1837 | "/assets/unresolved/img.png": path.resolve(
|
1838 | __dirname,
|
1839 | "assets/real-path-to-img/img.png"
|
1840 | ),
|
1841 | },
|
1842 | },
|
1843 | };
|
1844 | ```
|
1845 |
|
1846 | ### Named export with custom export names
|
1847 |
|
1848 | **webpack.config.js**
|
1849 |
|
1850 | ```js
|
1851 | module.exports = {
|
1852 | module: {
|
1853 | rules: [
|
1854 | {
|
1855 | test: /\.css$/i,
|
1856 | loader: "css-loader",
|
1857 | options: {
|
1858 | modules: {
|
1859 | namedExport: true,
|
1860 | exportLocalsConvention: function (name) {
|
1861 | return name.replace(/-/g, "_");
|
1862 | },
|
1863 | },
|
1864 | },
|
1865 | },
|
1866 | ],
|
1867 | },
|
1868 | };
|
1869 | ```
|
1870 |
|
1871 | ### Separating `Interoperable CSS`-only and `CSS Module` features
|
1872 |
|
1873 | The 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.
|
1874 | Meanwhile all files matching `*.module.scss` are treated as `CSS Modules` in this example.
|
1875 |
|
1876 | An 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).
|
1877 |
|
1878 | **webpack.config.js**
|
1879 |
|
1880 | ```js
|
1881 | module.exports = {
|
1882 | module: {
|
1883 | rules: [
|
1884 | // ...
|
1885 | // --------
|
1886 | // SCSS ALL EXCEPT MODULES
|
1887 | {
|
1888 | test: /\.scss$/i,
|
1889 | exclude: /\.module\.scss$/i,
|
1890 | use: [
|
1891 | {
|
1892 | loader: "style-loader",
|
1893 | },
|
1894 | {
|
1895 | loader: "css-loader",
|
1896 | options: {
|
1897 | importLoaders: 1,
|
1898 | modules: {
|
1899 | mode: "icss",
|
1900 | },
|
1901 | },
|
1902 | },
|
1903 | {
|
1904 | loader: "sass-loader",
|
1905 | },
|
1906 | ],
|
1907 | },
|
1908 | // --------
|
1909 | // SCSS MODULES
|
1910 | {
|
1911 | test: /\.module\.scss$/i,
|
1912 | use: [
|
1913 | {
|
1914 | loader: "style-loader",
|
1915 | },
|
1916 | {
|
1917 | loader: "css-loader",
|
1918 | options: {
|
1919 | importLoaders: 1,
|
1920 | modules: {
|
1921 | mode: "local",
|
1922 | },
|
1923 | },
|
1924 | },
|
1925 | {
|
1926 | loader: "sass-loader",
|
1927 | },
|
1928 | ],
|
1929 | },
|
1930 | // --------
|
1931 | // ...
|
1932 | ],
|
1933 | },
|
1934 | };
|
1935 | ```
|
1936 |
|
1937 | **variables.scss**
|
1938 |
|
1939 | File treated as `ICSS`-only.
|
1940 |
|
1941 | ```scss
|
1942 | $colorBackground: red;
|
1943 | :export {
|
1944 | colorBackgroundCanvas: $colorBackground;
|
1945 | }
|
1946 | ```
|
1947 |
|
1948 | **Component.module.scss**
|
1949 |
|
1950 | File treated as `CSS Module`.
|
1951 |
|
1952 | ```scss
|
1953 | @import "variables.scss";
|
1954 | .componentClass {
|
1955 | background-color: $colorBackground;
|
1956 | }
|
1957 | ```
|
1958 |
|
1959 | **Component.jsx**
|
1960 |
|
1961 | Using both `CSS Module` functionality as well as SCSS variables directly in JavaScript.
|
1962 |
|
1963 | ```jsx
|
1964 | import svars from "variables.scss";
|
1965 | import styles from "Component.module.scss";
|
1966 |
|
1967 | // Render DOM with CSS modules class name
|
1968 | // <div className={styles.componentClass}>
|
1969 | // <canvas ref={mountsCanvas}/>
|
1970 | // </div>
|
1971 |
|
1972 | // Somewhere in JavaScript canvas drawing code use the variable directly
|
1973 | // const ctx = mountsCanvas.current.getContext('2d',{alpha: false});
|
1974 | ctx.fillStyle = `${svars.colorBackgroundCanvas}`;
|
1975 | ```
|
1976 |
|
1977 | ## Contributing
|
1978 |
|
1979 | Please take a moment to read our contributing guidelines if you haven't yet done so.
|
1980 |
|
1981 | [CONTRIBUTING](./.github/CONTRIBUTING.md)
|
1982 |
|
1983 | ## License
|
1984 |
|
1985 | [MIT](./LICENSE)
|
1986 |
|
1987 | [npm]: https://img.shields.io/npm/v/css-loader.svg
|
1988 | [npm-url]: https://npmjs.com/package/css-loader
|
1989 | [node]: https://img.shields.io/node/v/css-loader.svg
|
1990 | [node-url]: https://nodejs.org
|
1991 | [deps]: https://david-dm.org/webpack-contrib/css-loader.svg
|
1992 | [deps-url]: https://david-dm.org/webpack-contrib/css-loader
|
1993 | [tests]: https://github.com/webpack-contrib/css-loader/workflows/css-loader/badge.svg
|
1994 | [tests-url]: https://github.com/webpack-contrib/css-loader/actions
|
1995 | [cover]: https://codecov.io/gh/webpack-contrib/css-loader/branch/master/graph/badge.svg
|
1996 | [cover-url]: https://codecov.io/gh/webpack-contrib/css-loader
|
1997 | [chat]: https://badges.gitter.im/webpack/webpack.svg
|
1998 | [chat-url]: https://gitter.im/webpack/webpack
|
1999 | [size]: https://packagephobia.now.sh/badge?p=css-loader
|
2000 | [size-url]: https://packagephobia.now.sh/result?p=css-loader
|