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 begin, you'll need to install `css-loader`:
|
25 |
|
26 | ```console
|
27 | npm install --save-dev css-loader
|
28 | ```
|
29 |
|
30 | Then add the plugin to your `webpack` config. For example:
|
31 |
|
32 | **file.js**
|
33 |
|
34 | ```js
|
35 | import css from 'file.css';
|
36 | ```
|
37 |
|
38 | **webpack.config.js**
|
39 |
|
40 | ```js
|
41 | module.exports = {
|
42 | module: {
|
43 | rules: [
|
44 | {
|
45 | test: /\.css$/i,
|
46 | use: ['style-loader', 'css-loader'],
|
47 | },
|
48 | ],
|
49 | },
|
50 | };
|
51 | ```
|
52 |
|
53 | Good loaders for requiring your assets are the [file-loader](https://github.com/webpack/file-loader) and the [url-loader](https://github.com/webpack/url-loader) which you should specify in your config (see [below](https://github.com/webpack-contrib/css-loader#assets)).
|
54 |
|
55 | And run `webpack` via your preferred method.
|
56 |
|
57 | ### `toString`
|
58 |
|
59 | You 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
|
64 | module.exports = {
|
65 | module: {
|
66 | rules: [
|
67 | {
|
68 | test: /\.css$/i,
|
69 | use: ['to-string-loader', 'css-loader'],
|
70 | },
|
71 | ],
|
72 | },
|
73 | };
|
74 | ```
|
75 |
|
76 | or
|
77 |
|
78 | ```js
|
79 | const css = require('./test.css').toString();
|
80 |
|
81 | console.log(css); // {String}
|
82 | ```
|
83 |
|
84 | If there are SourceMaps, they will also be included in the result string.
|
85 |
|
86 | If, for one reason or another, you need to extract CSS as a
|
87 | plain string resource (i.e. not wrapped in a JS module) you
|
88 | might want to check out the [extract-loader](https://github.com/peerigon/extract-loader).
|
89 | It's useful when you, for instance, need to post process the CSS as a string.
|
90 |
|
91 | **webpack.config.js**
|
92 |
|
93 | ```js
|
94 | module.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\|Function}` | `true` | Enables/Disables `url`/`image-set` functions handling |
|
115 | | **[`import`](#import)** | `{Boolean\|Function}` | `true` | Enables/Disables `@import` at-rules handling |
|
116 | | **[`modules`](#modules)** | `{Boolean\|String\|Object}` | `false` | Enables/Disables CSS Modules and their configuration |
|
117 | | **[`sourceMap`](#sourcemap)** | `{Boolean}` | `false` | Enables/Disables generation of source maps |
|
118 | | **[`importLoaders`](#importloaders)** | `{Number}` | `0` | Enables/Disables or setups number of loaders applied before CSS loader |
|
119 | | **[`localsConvention`](#localsconvention)** | `{String}` | `'asIs'` | Style of exported classnames |
|
120 | | **[`onlyLocals`](#onlylocals)** | `{Boolean}` | `false` | Export only locals |
|
121 | | **[`esModule`](#esmodule)** | `{Boolean}` | `false` | Use ES modules syntax |
|
122 |
|
123 | ### `url`
|
124 |
|
125 | Type: `Boolean|Function`
|
126 | Default: `true`
|
127 |
|
128 | Enables/Disables `url`/`image-set` functions handling.
|
129 | Control `url()` resolving. Absolute URLs and root-relative URLs are not resolving.
|
130 |
|
131 | Examples resolutions:
|
132 |
|
133 | ```
|
134 | url(image.png) => require('./image.png')
|
135 | url('image.png') => require('./image.png')
|
136 | url(./image.png) => require('./image.png')
|
137 | url('./image.png') => require('./image.png')
|
138 | url('http://dontwritehorriblecode.com/2112.png') => require('http://dontwritehorriblecode.com/2112.png')
|
139 | image-set(url('image2x.png') 1x, url('image1x.png') 2x) => require('./image1x.png') and require('./image2x.png')
|
140 | ```
|
141 |
|
142 | To import assets from a `node_modules` path (include `resolve.modules`) and for `alias`, prefix it with a `~`:
|
143 |
|
144 | ```
|
145 | url(~module/image.png) => require('module/image.png')
|
146 | url('~module/image.png') => require('module/image.png')
|
147 | url(~aliasDirectory/image.png) => require('otherDirectory/image.png')
|
148 | ```
|
149 |
|
150 | #### `Boolean`
|
151 |
|
152 | Enable/disable `url()` resolving.
|
153 |
|
154 | **webpack.config.js**
|
155 |
|
156 | ```js
|
157 | module.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 | #### `Function`
|
173 |
|
174 | Allow 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
|
179 | module.exports = {
|
180 | module: {
|
181 | rules: [
|
182 | {
|
183 | test: /\.css$/i,
|
184 | loader: 'css-loader',
|
185 | options: {
|
186 | url: (url, resourcePath) => {
|
187 | // resourcePath - path to css file
|
188 |
|
189 | // Don't handle `img.png` urls
|
190 | if (url.includes('img.png')) {
|
191 | return false;
|
192 | }
|
193 |
|
194 | return true;
|
195 | },
|
196 | },
|
197 | },
|
198 | ],
|
199 | },
|
200 | };
|
201 | ```
|
202 |
|
203 | ### `import`
|
204 |
|
205 | Type: `Boolean|Function`
|
206 | Default: `true`
|
207 |
|
208 | Enables/Disables `@import` at-rules handling.
|
209 | Control `@import` resolving. Absolute urls in `@import` will be moved in runtime code.
|
210 |
|
211 | Examples resolutions:
|
212 |
|
213 | ```
|
214 | @import 'style.css' => require('./style.css')
|
215 | @import url(style.css) => require('./style.css')
|
216 | @import url('style.css') => require('./style.css')
|
217 | @import './style.css' => require('./style.css')
|
218 | @import url(./style.css) => require('./style.css')
|
219 | @import url('./style.css') => require('./style.css')
|
220 | @import url('http://dontwritehorriblecode.com/style.css') => @import url('http://dontwritehorriblecode.com/style.css') in runtime
|
221 | ```
|
222 |
|
223 | To import styles from a `node_modules` path (include `resolve.modules`) and for `alias`, prefix it with a `~`:
|
224 |
|
225 | ```
|
226 | @import url(~module/style.css) => require('module/style.css')
|
227 | @import url('~module/style.css') => require('module/style.css')
|
228 | @import url(~aliasDirectory/style.css) => require('otherDirectory/style.css')
|
229 | ```
|
230 |
|
231 | #### `Boolean`
|
232 |
|
233 | Enable/disable `@import` resolving.
|
234 |
|
235 | **webpack.config.js**
|
236 |
|
237 | ```js
|
238 | module.exports = {
|
239 | module: {
|
240 | rules: [
|
241 | {
|
242 | test: /\.css$/i,
|
243 | loader: 'css-loader',
|
244 | options: {
|
245 | import: true,
|
246 | },
|
247 | },
|
248 | ],
|
249 | },
|
250 | };
|
251 | ```
|
252 |
|
253 | #### `Function`
|
254 |
|
255 | Allow to filter `@import`. All filtered `@import` will not be resolved (left in the code as they were written).
|
256 |
|
257 | **webpack.config.js**
|
258 |
|
259 | ```js
|
260 | module.exports = {
|
261 | module: {
|
262 | rules: [
|
263 | {
|
264 | test: /\.css$/i,
|
265 | loader: 'css-loader',
|
266 | options: {
|
267 | import: (parsedImport, resourcePath) => {
|
268 | // parsedImport.url - url of `@import`
|
269 | // parsedImport.media - media query of `@import`
|
270 | // resourcePath - path to css file
|
271 |
|
272 | // Don't handle `style.css` import
|
273 | if (parsedImport.url.includes('style.css')) {
|
274 | return false;
|
275 | }
|
276 |
|
277 | return true;
|
278 | },
|
279 | },
|
280 | },
|
281 | ],
|
282 | },
|
283 | };
|
284 | ```
|
285 |
|
286 | ### `modules`
|
287 |
|
288 | Type: `Boolean|String|Object`
|
289 | Default: `false`
|
290 |
|
291 | Enables/Disables CSS Modules and their configuration.
|
292 |
|
293 | The `modules` option enables/disables the **[CSS Modules](https://github.com/css-modules/css-modules)** specification and setup basic behaviour.
|
294 |
|
295 | 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.
|
296 |
|
297 | **webpack.config.js**
|
298 |
|
299 | ```js
|
300 | module.exports = {
|
301 | module: {
|
302 | rules: [
|
303 | {
|
304 | test: /\.css$/i,
|
305 | loader: 'css-loader',
|
306 | options: {
|
307 | modules: true,
|
308 | },
|
309 | },
|
310 | ],
|
311 | },
|
312 | };
|
313 | ```
|
314 |
|
315 | #### `Features`
|
316 |
|
317 | ##### `Scope`
|
318 |
|
319 | Using `local` value requires you to specify `:global` classes.
|
320 | Using `global` value requires you to specify `:local` classes.
|
321 | Using `pure` value requires selectors must contain at least one local class or id.
|
322 |
|
323 | You can find more information [here](https://github.com/css-modules/css-modules).
|
324 |
|
325 | Styles can be locally scoped to avoid globally scoping styles.
|
326 |
|
327 | The syntax `:local(.className)` can be used to declare `className` in the local scope. The local identifiers are exported by the module.
|
328 |
|
329 | With `:local` (without brackets) local mode can be switched on for this selector.
|
330 | The `:global(.className)` notation can be used to declare an explicit global selector.
|
331 | With `:global` (without brackets) global mode can be switched on for this selector.
|
332 |
|
333 | The loader replaces local selectors with unique identifiers. The chosen unique identifiers are exported by the module.
|
334 |
|
335 | ```css
|
336 | :local(.className) {
|
337 | background: red;
|
338 | }
|
339 | :local .className {
|
340 | color: green;
|
341 | }
|
342 | :local(.className .subClass) {
|
343 | color: green;
|
344 | }
|
345 | :local .className .subClass :global(.global-class-name) {
|
346 | color: blue;
|
347 | }
|
348 | ```
|
349 |
|
350 | ```css
|
351 | ._23_aKvs-b8bW2Vg3fwHozO {
|
352 | background: red;
|
353 | }
|
354 | ._23_aKvs-b8bW2Vg3fwHozO {
|
355 | color: green;
|
356 | }
|
357 | ._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 {
|
358 | color: green;
|
359 | }
|
360 | ._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 .global-class-name {
|
361 | color: blue;
|
362 | }
|
363 | ```
|
364 |
|
365 | > ℹ️ Identifiers are exported
|
366 |
|
367 | ```js
|
368 | exports.locals = {
|
369 | className: '_23_aKvs-b8bW2Vg3fwHozO',
|
370 | subClass: '_13LGdX8RMStbBE9w-t0gZ1',
|
371 | };
|
372 | ```
|
373 |
|
374 | CamelCase is recommended for local selectors. They are easier to use within the imported JS module.
|
375 |
|
376 | You can use `:local(#someId)`, but this is not recommended. Use classes instead of ids.
|
377 |
|
378 | ##### `Composing`
|
379 |
|
380 | When declaring a local classname you can compose a local class from another local classname.
|
381 |
|
382 | ```css
|
383 | :local(.className) {
|
384 | background: red;
|
385 | color: yellow;
|
386 | }
|
387 |
|
388 | :local(.subClass) {
|
389 | composes: className;
|
390 | background: blue;
|
391 | }
|
392 | ```
|
393 |
|
394 | This doesn't result in any change to the CSS itself but exports multiple classnames.
|
395 |
|
396 | ```js
|
397 | exports.locals = {
|
398 | className: '_23_aKvs-b8bW2Vg3fwHozO',
|
399 | subClass: '_13LGdX8RMStbBE9w-t0gZ1 _23_aKvs-b8bW2Vg3fwHozO',
|
400 | };
|
401 | ```
|
402 |
|
403 | ```css
|
404 | ._23_aKvs-b8bW2Vg3fwHozO {
|
405 | background: red;
|
406 | color: yellow;
|
407 | }
|
408 |
|
409 | ._13LGdX8RMStbBE9w-t0gZ1 {
|
410 | background: blue;
|
411 | }
|
412 | ```
|
413 |
|
414 | ##### `Importing`
|
415 |
|
416 | To import a local classname from another module.
|
417 |
|
418 | ```css
|
419 | :local(.continueButton) {
|
420 | composes: button from 'library/button.css';
|
421 | background: red;
|
422 | }
|
423 | ```
|
424 |
|
425 | ```css
|
426 | :local(.nameEdit) {
|
427 | composes: edit highlight from './edit.css';
|
428 | background: red;
|
429 | }
|
430 | ```
|
431 |
|
432 | To import from multiple modules use multiple `composes:` rules.
|
433 |
|
434 | ```css
|
435 | :local(.className) {
|
436 | composes: edit hightlight from './edit.css';
|
437 | composes: button from 'module/button.css';
|
438 | composes: classFromThisModule;
|
439 | background: red;
|
440 | }
|
441 | ```
|
442 |
|
443 | ##### `Values`
|
444 |
|
445 | You can use `@value` to specific values to be reused throughout a document.
|
446 |
|
447 | We recommend use prefix `v-` for values, `s-` for selectors and `m-` for media at-rules.
|
448 |
|
449 | ```css
|
450 | @value v-primary: #BF4040;
|
451 | @value s-black: black-selector;
|
452 | @value m-large: (min-width: 960px);
|
453 |
|
454 | .header {
|
455 | color: v-primary;
|
456 | padding: 0 10px;
|
457 | }
|
458 |
|
459 | .s-black {
|
460 | color: black;
|
461 | }
|
462 |
|
463 | @media m-large {
|
464 | .header {
|
465 | padding: 0 20px;
|
466 | }
|
467 | }
|
468 | ```
|
469 |
|
470 | #### `Boolean`
|
471 |
|
472 | Enable **CSS Modules** features.
|
473 |
|
474 | **webpack.config.js**
|
475 |
|
476 | ```js
|
477 | module.exports = {
|
478 | module: {
|
479 | rules: [
|
480 | {
|
481 | test: /\.css$/i,
|
482 | loader: 'css-loader',
|
483 | options: {
|
484 | modules: true,
|
485 | },
|
486 | },
|
487 | ],
|
488 | },
|
489 | };
|
490 | ```
|
491 |
|
492 | #### `String`
|
493 |
|
494 | Enable **CSS Modules** features and setup `mode`.
|
495 |
|
496 | **webpack.config.js**
|
497 |
|
498 | ```js
|
499 | module.exports = {
|
500 | module: {
|
501 | rules: [
|
502 | {
|
503 | test: /\.css$/i,
|
504 | loader: 'css-loader',
|
505 | options: {
|
506 | // Using `local` value has same effect like using `modules: true`
|
507 | modules: 'global',
|
508 | },
|
509 | },
|
510 | ],
|
511 | },
|
512 | };
|
513 | ```
|
514 |
|
515 | #### `Object`
|
516 |
|
517 | Enable **CSS Modules** features and setup options for them.
|
518 |
|
519 | **webpack.config.js**
|
520 |
|
521 | ```js
|
522 | module.exports = {
|
523 | module: {
|
524 | rules: [
|
525 | {
|
526 | test: /\.css$/i,
|
527 | loader: 'css-loader',
|
528 | options: {
|
529 | modules: {
|
530 | mode: 'local',
|
531 | exportGlobals: true,
|
532 | localIdentName: '[path][name]__[local]--[hash:base64:5]',
|
533 | context: path.resolve(__dirname, 'src'),
|
534 | hashPrefix: 'my-custom-hash',
|
535 | },
|
536 | },
|
537 | },
|
538 | ],
|
539 | },
|
540 | };
|
541 | ```
|
542 |
|
543 | ##### `auto`
|
544 |
|
545 | Type: `Boolean|RegExp`
|
546 | Default: `'undefined'`
|
547 |
|
548 | Allows auto enable css modules based on filename.
|
549 |
|
550 | ###### `Boolean`
|
551 |
|
552 | Possible values:
|
553 |
|
554 | - `true` - enable css modules for all files for which `/\.module\.\w+$/i.test(filename)` return true
|
555 | - `false` - disable css modules
|
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 | auto: true,
|
569 | },
|
570 | },
|
571 | },
|
572 | ],
|
573 | },
|
574 | };
|
575 | ```
|
576 |
|
577 | ###### `RegExp`
|
578 |
|
579 | Enable css modules for files based on a filename and satisfying your regex.
|
580 |
|
581 | **webpack.config.js**
|
582 |
|
583 | ```js
|
584 | module.exports = {
|
585 | module: {
|
586 | rules: [
|
587 | {
|
588 | test: /\.css$/i,
|
589 | loader: 'css-loader',
|
590 | options: {
|
591 | modules: {
|
592 | auto: /\.custom-module\.\w+$/i,
|
593 | },
|
594 | },
|
595 | },
|
596 | ],
|
597 | },
|
598 | };
|
599 | ```
|
600 |
|
601 | ##### `mode`
|
602 |
|
603 | Type: `String|Function`
|
604 | Default: `'local'`
|
605 |
|
606 | Setup `mode` option. You can omit the value when you want `local` mode.
|
607 |
|
608 | ###### `String`
|
609 |
|
610 | Possible values - `local`, `global`, and `pure`.
|
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 | mode: 'global',
|
624 | },
|
625 | },
|
626 | },
|
627 | ],
|
628 | },
|
629 | };
|
630 | ```
|
631 |
|
632 | ###### `Function`
|
633 |
|
634 | Allows set different values for the `mode` option based on a filename
|
635 |
|
636 | Possible return values - `local`, `global`, and `pure`.
|
637 |
|
638 | **webpack.config.js**
|
639 |
|
640 | ```js
|
641 | module.exports = {
|
642 | module: {
|
643 | rules: [
|
644 | {
|
645 | test: /\.css$/i,
|
646 | loader: 'css-loader',
|
647 | options: {
|
648 | modules: {
|
649 | // Callback must return "local", "global", or "pure" values
|
650 | mode: (resourcePath) => {
|
651 | if (/pure.css$/i.test(resourcePath)) {
|
652 | return 'pure';
|
653 | }
|
654 |
|
655 | if (/global.css$/i.test(resourcePath)) {
|
656 | return 'global';
|
657 | }
|
658 |
|
659 | return 'local';
|
660 | },
|
661 | },
|
662 | },
|
663 | },
|
664 | ],
|
665 | },
|
666 | };
|
667 | ```
|
668 |
|
669 | ##### `exportGlobals`
|
670 |
|
671 | Type: `Boolean`
|
672 | Default: `false`
|
673 |
|
674 | Allow `css-loader` to export names from global class or id, so you can use that as local name.
|
675 |
|
676 | **webpack.config.js**
|
677 |
|
678 | ```js
|
679 | module.exports = {
|
680 | module: {
|
681 | rules: [
|
682 | {
|
683 | test: /\.css$/i,
|
684 | loader: 'css-loader',
|
685 | options: {
|
686 | modules: {
|
687 | exportGlobals: true,
|
688 | },
|
689 | },
|
690 | },
|
691 | ],
|
692 | },
|
693 | };
|
694 | ```
|
695 |
|
696 | ##### `localIdentName`
|
697 |
|
698 | Type: `String`
|
699 | Default: `'[hash:base64]'`
|
700 |
|
701 | You can configure the generated ident with the `localIdentName` query parameter.
|
702 | See [loader-utils's documentation](https://github.com/webpack/loader-utils#interpolatename) for more information on options.
|
703 |
|
704 | Recommendations:
|
705 |
|
706 | - use `'[path][name]__[local]'` for development
|
707 | - use `'[hash:base64]'` for production
|
708 |
|
709 | The `[local]` placeholder contains original class.
|
710 |
|
711 | **Note:** all reserved (`<>:"/\|?*`) and control filesystem characters (excluding characters in the `[local]` placeholder) will be converted to `-`.
|
712 |
|
713 | **webpack.config.js**
|
714 |
|
715 | ```js
|
716 | module.exports = {
|
717 | module: {
|
718 | rules: [
|
719 | {
|
720 | test: /\.css$/i,
|
721 | loader: 'css-loader',
|
722 | options: {
|
723 | modules: {
|
724 | localIdentName: '[path][name]__[local]--[hash:base64:5]',
|
725 | },
|
726 | },
|
727 | },
|
728 | ],
|
729 | },
|
730 | };
|
731 | ```
|
732 |
|
733 | ##### `context`
|
734 |
|
735 | Type: `String`
|
736 | Default: `undefined`
|
737 |
|
738 | Allow to redefine basic loader context for local ident name.
|
739 | By default we use `rootContext` of loader.
|
740 |
|
741 | **webpack.config.js**
|
742 |
|
743 | ```js
|
744 | module.exports = {
|
745 | module: {
|
746 | rules: [
|
747 | {
|
748 | test: /\.css$/i,
|
749 | loader: 'css-loader',
|
750 | options: {
|
751 | modules: {
|
752 | context: path.resolve(__dirname, 'context'),
|
753 | },
|
754 | },
|
755 | },
|
756 | ],
|
757 | },
|
758 | };
|
759 | ```
|
760 |
|
761 | ##### `hashPrefix`
|
762 |
|
763 | Type: `String`
|
764 | Default: `undefined`
|
765 |
|
766 | Allow to add custom hash to generate more unique classes.
|
767 |
|
768 | **webpack.config.js**
|
769 |
|
770 | ```js
|
771 | module.exports = {
|
772 | module: {
|
773 | rules: [
|
774 | {
|
775 | test: /\.css$/i,
|
776 | loader: 'css-loader',
|
777 | options: {
|
778 | modules: {
|
779 | hashPrefix: 'hash',
|
780 | },
|
781 | },
|
782 | },
|
783 | ],
|
784 | },
|
785 | };
|
786 | ```
|
787 |
|
788 | ##### `getLocalIdent`
|
789 |
|
790 | Type: `Function`
|
791 | Default: `undefined`
|
792 |
|
793 | You can also specify the absolute path to your custom `getLocalIdent` function to generate classname based on a different schema.
|
794 | By default we use built-in function to generate a classname.
|
795 |
|
796 | **webpack.config.js**
|
797 |
|
798 | ```js
|
799 | module.exports = {
|
800 | module: {
|
801 | rules: [
|
802 | {
|
803 | test: /\.css$/i,
|
804 | loader: 'css-loader',
|
805 | options: {
|
806 | modules: {
|
807 | getLocalIdent: (context, localIdentName, localName, options) => {
|
808 | return 'whatever_random_class_name';
|
809 | },
|
810 | },
|
811 | },
|
812 | },
|
813 | ],
|
814 | },
|
815 | };
|
816 | ```
|
817 |
|
818 | ##### `localIdentRegExp`
|
819 |
|
820 | Type: `String|RegExp`
|
821 | Default: `undefined`
|
822 |
|
823 | **webpack.config.js**
|
824 |
|
825 | ```js
|
826 | module.exports = {
|
827 | module: {
|
828 | rules: [
|
829 | {
|
830 | test: /\.css$/i,
|
831 | loader: 'css-loader',
|
832 | options: {
|
833 | modules: {
|
834 | localIdentRegExp: /page-(.*)\.css/i,
|
835 | },
|
836 | },
|
837 | },
|
838 | ],
|
839 | },
|
840 | };
|
841 | ```
|
842 |
|
843 | ### `sourceMap`
|
844 |
|
845 | Type: `Boolean`
|
846 | Default: `false`
|
847 |
|
848 | Enables/Disables generation of source maps.
|
849 |
|
850 | To include source maps set the `sourceMap` option.
|
851 |
|
852 | They are not enabled by default because they expose a runtime overhead and increase in bundle size (JS source maps do not).
|
853 |
|
854 | **webpack.config.js**
|
855 |
|
856 | ```js
|
857 | module.exports = {
|
858 | module: {
|
859 | rules: [
|
860 | {
|
861 | test: /\.css$/i,
|
862 | loader: 'css-loader',
|
863 | options: {
|
864 | sourceMap: true,
|
865 | },
|
866 | },
|
867 | ],
|
868 | },
|
869 | };
|
870 | ```
|
871 |
|
872 | ### `importLoaders`
|
873 |
|
874 | Type: `Number`
|
875 | Default: `0`
|
876 |
|
877 | Enables/Disables or setups number of loaders applied before CSS loader.
|
878 |
|
879 | The option `importLoaders` allows you to configure how many loaders before `css-loader` should be applied to `@import`ed resources.
|
880 |
|
881 | **webpack.config.js**
|
882 |
|
883 | ```js
|
884 | module.exports = {
|
885 | module: {
|
886 | rules: [
|
887 | {
|
888 | test: /\.css$/i,
|
889 | use: [
|
890 | 'style-loader',
|
891 | {
|
892 | loader: 'css-loader',
|
893 | options: {
|
894 | importLoaders: 2,
|
895 | // 0 => no loaders (default);
|
896 | // 1 => postcss-loader;
|
897 | // 2 => postcss-loader, sass-loader
|
898 | },
|
899 | },
|
900 | 'postcss-loader',
|
901 | 'sass-loader',
|
902 | ],
|
903 | },
|
904 | ],
|
905 | },
|
906 | };
|
907 | ```
|
908 |
|
909 | This may change in the future when the module system (i. e. webpack) supports loader matching by origin.
|
910 |
|
911 | ### `localsConvention`
|
912 |
|
913 | Type: `String`
|
914 | Default: `'asIs'`
|
915 |
|
916 | Style of exported classnames.
|
917 |
|
918 | By default, the exported JSON keys mirror the class names (i.e `asIs` value).
|
919 |
|
920 | | Name | Type | Description |
|
921 | | :-------------------: | :--------: | :----------------------------------------------------------------------------------------------- |
|
922 | | **`'asIs'`** | `{String}` | Class names will be exported as is. |
|
923 | | **`'camelCase'`** | `{String}` | Class names will be camelized, the original class name will not to be removed from the locals |
|
924 | | **`'camelCaseOnly'`** | `{String}` | Class names will be camelized, the original class name will be removed from the locals |
|
925 | | **`'dashes'`** | `{String}` | Only dashes in class names will be camelized |
|
926 | | **`'dashesOnly'`** | `{String}` | Dashes in class names will be camelized, the original class name will be removed from the locals |
|
927 |
|
928 | **file.css**
|
929 |
|
930 | ```css
|
931 | .class-name {
|
932 | }
|
933 | ```
|
934 |
|
935 | **file.js**
|
936 |
|
937 | ```js
|
938 | import { className } from 'file.css';
|
939 | ```
|
940 |
|
941 | **webpack.config.js**
|
942 |
|
943 | ```js
|
944 | module.exports = {
|
945 | module: {
|
946 | rules: [
|
947 | {
|
948 | test: /\.css$/i,
|
949 | loader: 'css-loader',
|
950 | options: {
|
951 | localsConvention: 'camelCase',
|
952 | },
|
953 | },
|
954 | ],
|
955 | },
|
956 | };
|
957 | ```
|
958 |
|
959 | ### `onlyLocals`
|
960 |
|
961 | Type: `Boolean`
|
962 | Default: `false`
|
963 |
|
964 | Export only locals.
|
965 |
|
966 | **Useful** when you use **css modules** for pre-rendering (for example SSR).
|
967 | For pre-rendering with `mini-css-extract-plugin` you should use this option instead of `style-loader!css-loader` **in the pre-rendering bundle**.
|
968 | It doesn't embed CSS but only exports the identifier mappings.
|
969 |
|
970 | **webpack.config.js**
|
971 |
|
972 | ```js
|
973 | module.exports = {
|
974 | module: {
|
975 | rules: [
|
976 | {
|
977 | test: /\.css$/i,
|
978 | loader: 'css-loader',
|
979 | options: {
|
980 | onlyLocals: true,
|
981 | },
|
982 | },
|
983 | ],
|
984 | },
|
985 | };
|
986 | ```
|
987 |
|
988 | ### `esModule`
|
989 |
|
990 | Type: `Boolean`
|
991 | Default: `false`
|
992 |
|
993 | By default, `css-loader` generates JS modules that use the CommonJS modules syntax.
|
994 | 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/).
|
995 |
|
996 | You can enable a ES module syntax using:
|
997 |
|
998 | **webpack.config.js**
|
999 |
|
1000 | ```js
|
1001 | module.exports = {
|
1002 | module: {
|
1003 | rules: [
|
1004 | {
|
1005 | test: /\.css$/i,
|
1006 | loader: 'css-loader',
|
1007 | options: {
|
1008 | esModule: true,
|
1009 | },
|
1010 | },
|
1011 | ],
|
1012 | },
|
1013 | };
|
1014 | ```
|
1015 |
|
1016 | ## Examples
|
1017 |
|
1018 | ### Assets
|
1019 |
|
1020 | 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.
|
1021 |
|
1022 | **webpack.config.js**
|
1023 |
|
1024 | ```js
|
1025 | module.exports = {
|
1026 | module: {
|
1027 | rules: [
|
1028 | {
|
1029 | test: /\.css$/i,
|
1030 | use: ['style-loader', 'css-loader'],
|
1031 | },
|
1032 | {
|
1033 | test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
|
1034 | loader: 'url-loader',
|
1035 | options: {
|
1036 | limit: 8192,
|
1037 | },
|
1038 | },
|
1039 | ],
|
1040 | },
|
1041 | };
|
1042 | ```
|
1043 |
|
1044 | ### Extract
|
1045 |
|
1046 | 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.
|
1047 |
|
1048 | - 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.
|
1049 |
|
1050 | - 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
|
1051 |
|
1052 | ### Pure CSS, CSS modules and PostCSS
|
1053 |
|
1054 | When you have pure CSS (without CSS modules), CSS modules and PostCSS in your project you can use this setup:
|
1055 |
|
1056 | **webpack.config.js**
|
1057 |
|
1058 | ```js
|
1059 | module.exports = {
|
1060 | module: {
|
1061 | rules: [
|
1062 | {
|
1063 | // For CSS modules
|
1064 | // For pure CSS - /\.css$/i,
|
1065 | // For Sass/SCSS - /\.((c|sa|sc)ss)$/i,
|
1066 | // For Less - /\.((c|le)ss)$/i,
|
1067 | test: /\.((c|sa|sc)ss)$/i,
|
1068 | use: [
|
1069 | 'style-loader',
|
1070 | {
|
1071 | loader: 'css-loader',
|
1072 | options: {
|
1073 | // Run `postcss-loader` on each CSS `@import`, do not forget that `sass-loader` compile non CSS `@import`'s into a single file
|
1074 | // If you need run `sass-loader` and `postcss-loader` on each CSS `@import` please set it to `2`
|
1075 | importLoaders: 1,
|
1076 | // Automatically enable css modules for files satisfying `/\.module\.\w+$/i` RegExp.
|
1077 | modules: { auto: true },
|
1078 | },
|
1079 | },
|
1080 | {
|
1081 | loader: 'postcss-loader',
|
1082 | options: { plugins: () => [postcssPresetEnv({ stage: 0 })] },
|
1083 | },
|
1084 | // Can be `less-loader`
|
1085 | // The `test` property should be `\.less/i`
|
1086 | {
|
1087 | test: /\.s[ac]ss$/i,
|
1088 | loader: 'sass-loader',
|
1089 | },
|
1090 | ],
|
1091 | },
|
1092 | {
|
1093 | test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
|
1094 | loader: 'url-loader',
|
1095 | options: {
|
1096 | limit: 8192,
|
1097 | },
|
1098 | },
|
1099 | ],
|
1100 | },
|
1101 | };
|
1102 | ```
|
1103 |
|
1104 | ## Contributing
|
1105 |
|
1106 | Please take a moment to read our contributing guidelines if you haven't yet done so.
|
1107 |
|
1108 | [CONTRIBUTING](./.github/CONTRIBUTING.md)
|
1109 |
|
1110 | ## License
|
1111 |
|
1112 | [MIT](./LICENSE)
|
1113 |
|
1114 | [npm]: https://img.shields.io/npm/v/css-loader.svg
|
1115 | [npm-url]: https://npmjs.com/package/css-loader
|
1116 | [node]: https://img.shields.io/node/v/css-loader.svg
|
1117 | [node-url]: https://nodejs.org
|
1118 | [deps]: https://david-dm.org/webpack-contrib/css-loader.svg
|
1119 | [deps-url]: https://david-dm.org/webpack-contrib/css-loader
|
1120 | [tests]: https://github.com/webpack-contrib/css-loader/workflows/css-loader/badge.svg
|
1121 | [tests-url]: https://github.com/webpack-contrib/css-loader/actions
|
1122 | [cover]: https://codecov.io/gh/webpack-contrib/css-loader/branch/master/graph/badge.svg
|
1123 | [cover-url]: https://codecov.io/gh/webpack-contrib/css-loader
|
1124 | [chat]: https://badges.gitter.im/webpack/webpack.svg
|
1125 | [chat-url]: https://gitter.im/webpack/webpack
|
1126 | [size]: https://packagephobia.now.sh/badge?p=css-loader
|
1127 | [size-url]: https://packagephobia.now.sh/result?p=css-loader
|