less-loader 12.3.3 → 13.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -45,18 +45,26 @@ module.exports = {
45
45
  rules: [
46
46
  {
47
47
  test: /\.less$/i,
48
- use: [
49
- // compiles Less to CSS
50
- "style-loader",
51
- "css-loader",
52
- "less-loader",
53
- ],
48
+ // Uses the built-in CSS support of webpack, i.e. `.module.less` files
49
+ // are treated as CSS modules, other files are treated as plain CSS
50
+ type: "css/auto",
51
+ // Compiles Less to CSS
52
+ use: ["less-loader"],
54
53
  },
55
54
  ],
56
55
  },
56
+ experiments: {
57
+ // Enables the built-in CSS support of webpack
58
+ css: true,
59
+ },
57
60
  };
58
61
  ```
59
62
 
63
+ > [!NOTE]
64
+ >
65
+ > The built-in CSS support of webpack requires `experiments.css` to be enabled.
66
+ > Alternatively you can still chain the loader with [`css-loader`](https://github.com/webpack/css-loader) and [`style-loader`](https://github.com/webpack/style-loader) (or the [`mini-css-extract-plugin`](https://github.com/webpack/mini-css-extract-plugin)), see [Using `css-loader` and `style-loader`](#using-css-loader-and-style-loader).
67
+
60
68
  Finally, run `webpack` using the method you normally use (e.g., via CLI or an npm script).
61
69
 
62
70
  ## Options
@@ -96,13 +104,8 @@ module.exports = {
96
104
  rules: [
97
105
  {
98
106
  test: /\.less$/i,
107
+ type: "css/auto",
99
108
  use: [
100
- {
101
- loader: "style-loader",
102
- },
103
- {
104
- loader: "css-loader",
105
- },
106
109
  {
107
110
  loader: "less-loader",
108
111
  options: {
@@ -115,6 +118,9 @@ module.exports = {
115
118
  },
116
119
  ],
117
120
  },
121
+ experiments: {
122
+ css: true,
123
+ },
118
124
  };
119
125
  ```
120
126
 
@@ -128,9 +134,8 @@ module.exports = {
128
134
  rules: [
129
135
  {
130
136
  test: /\.less$/i,
137
+ type: "css/auto",
131
138
  use: [
132
- "style-loader",
133
- "css-loader",
134
139
  {
135
140
  loader: "less-loader",
136
141
  options: {
@@ -155,6 +160,9 @@ module.exports = {
155
160
  },
156
161
  ],
157
162
  },
163
+ experiments: {
164
+ css: true,
165
+ },
158
166
  };
159
167
  ```
160
168
 
@@ -185,9 +193,8 @@ module.exports = {
185
193
  rules: [
186
194
  {
187
195
  test: /\.less$/i,
196
+ type: "css/auto",
188
197
  use: [
189
- "style-loader",
190
- "css-loader",
191
198
  {
192
199
  loader: "less-loader",
193
200
  options: {
@@ -198,6 +205,9 @@ module.exports = {
198
205
  },
199
206
  ],
200
207
  },
208
+ experiments: {
209
+ css: true,
210
+ },
201
211
  };
202
212
  ```
203
213
 
@@ -211,9 +221,8 @@ module.exports = {
211
221
  rules: [
212
222
  {
213
223
  test: /\.less$/i,
224
+ type: "css/auto",
214
225
  use: [
215
- "style-loader",
216
- "css-loader",
217
226
  {
218
227
  loader: "less-loader",
219
228
  options: {
@@ -234,6 +243,9 @@ module.exports = {
234
243
  },
235
244
  ],
236
245
  },
246
+ experiments: {
247
+ css: true,
248
+ },
237
249
  };
238
250
  ```
239
251
 
@@ -245,9 +257,8 @@ module.exports = {
245
257
  rules: [
246
258
  {
247
259
  test: /\.less$/i,
260
+ type: "css/auto",
248
261
  use: [
249
- "style-loader",
250
- "css-loader",
251
262
  {
252
263
  loader: "less-loader",
253
264
  options: {
@@ -268,6 +279,9 @@ module.exports = {
268
279
  },
269
280
  ],
270
281
  },
282
+ experiments: {
283
+ css: true,
284
+ },
271
285
  };
272
286
  ```
273
287
 
@@ -292,14 +306,8 @@ module.exports = {
292
306
  rules: [
293
307
  {
294
308
  test: /\.less$/i,
309
+ type: "css/auto",
295
310
  use: [
296
- "style-loader",
297
- {
298
- loader: "css-loader",
299
- options: {
300
- sourceMap: true,
301
- },
302
- },
303
311
  {
304
312
  loader: "less-loader",
305
313
  options: {
@@ -310,6 +318,9 @@ module.exports = {
310
318
  },
311
319
  ],
312
320
  },
321
+ experiments: {
322
+ css: true,
323
+ },
313
324
  };
314
325
  ```
315
326
 
@@ -335,9 +346,8 @@ module.exports = {
335
346
  rules: [
336
347
  {
337
348
  test: /\.less$/i,
349
+ type: "css/auto",
338
350
  use: [
339
- "style-loader",
340
- "css-loader",
341
351
  {
342
352
  loader: "less-loader",
343
353
  options: {
@@ -348,6 +358,9 @@ module.exports = {
348
358
  },
349
359
  ],
350
360
  },
361
+ experiments: {
362
+ css: true,
363
+ },
351
364
  };
352
365
  ```
353
366
 
@@ -377,9 +390,8 @@ module.exports = {
377
390
  rules: [
378
391
  {
379
392
  test: /\.less$/i,
393
+ type: "css/auto",
380
394
  use: [
381
- "style-loader",
382
- "css-loader",
383
395
  {
384
396
  loader: "less-loader",
385
397
  options: {
@@ -390,6 +402,9 @@ module.exports = {
390
402
  },
391
403
  ],
392
404
  },
405
+ experiments: {
406
+ css: true,
407
+ },
393
408
  };
394
409
  ```
395
410
 
@@ -405,9 +420,8 @@ module.exports = {
405
420
  rules: [
406
421
  {
407
422
  test: /\.less$/i,
423
+ type: "css/auto",
408
424
  use: [
409
- "style-loader",
410
- "css-loader",
411
425
  {
412
426
  loader: "less-loader",
413
427
  options: {
@@ -418,6 +432,9 @@ module.exports = {
418
432
  },
419
433
  ],
420
434
  },
435
+ experiments: {
436
+ css: true,
437
+ },
421
438
  };
422
439
  ```
423
440
 
@@ -429,7 +446,7 @@ Type:
429
446
  type lessLogAsWarnOrErr = boolean;
430
447
  ```
431
448
 
432
- Default: `false`
449
+ Default: `true`
433
450
 
434
451
  `Less` warnings and errors will be treated as webpack warnings and errors, instead of being logged silently.
435
452
 
@@ -441,7 +458,7 @@ div {
441
458
  }
442
459
  ```
443
460
 
444
- If `lessLogAsWarnOrErr` is set to `false` it will be just a log and webpack will compile successfully, but if you set this option to `true` webpack will compile fail with a warning(or error), and can break the build if configured accordingly.
461
+ If `lessLogAsWarnOrErr` is set to `false` it will be just a log and webpack will compile successfully, but if you leave the default value (or set this option to `true`) webpack will compile fail with a warning(or error), and can break the build if configured accordingly.
445
462
 
446
463
  **webpack.config.js**
447
464
 
@@ -451,9 +468,8 @@ module.exports = {
451
468
  rules: [
452
469
  {
453
470
  test: /\.less$/i,
471
+ type: "css/auto",
454
472
  use: [
455
- "style-loader",
456
- "css-loader",
457
473
  {
458
474
  loader: "less-loader",
459
475
  options: {
@@ -464,6 +480,9 @@ module.exports = {
464
480
  },
465
481
  ],
466
482
  },
483
+ experiments: {
484
+ css: true,
485
+ },
467
486
  };
468
487
  ```
469
488
 
@@ -471,7 +490,35 @@ module.exports = {
471
490
 
472
491
  ### Normal usage
473
492
 
474
- Chain the `less-loader` with [`css-loader`](https://github.com/webpack/css-loader) and [`style-loader`](https://github.com/webpack/style-loader) to immediately apply all styles to the DOM.
493
+ Set the module `type` to `css/auto` and enable `experiments.css` to let webpack handle the generated CSS with its built-in CSS support, without any extra loaders or plugins.
494
+
495
+ **webpack.config.js**
496
+
497
+ ```js
498
+ module.exports = {
499
+ module: {
500
+ rules: [
501
+ {
502
+ test: /\.less$/i,
503
+ type: "css/auto", // Handles the generated CSS using the built-in CSS support of webpack
504
+ use: ["less-loader"], // Compiles Less to CSS
505
+ },
506
+ ],
507
+ },
508
+ experiments: {
509
+ css: true,
510
+ },
511
+ };
512
+ ```
513
+
514
+ The `css/auto` module type treats `*.module.less` files as [CSS modules](#css-modules) and any other file as plain CSS.
515
+ Use `type: "css"` to always treat the file as plain CSS, or `type: "css/module"` to always treat it as a CSS module.
516
+
517
+ Unfortunately, Less doesn't map all options 1-by-1 to camelCase. When in doubt, [check their executable](https://github.com/less/less.js/blob/3.x/bin/lessc) and search for the dash-case option.
518
+
519
+ ### Using `css-loader` and `style-loader`
520
+
521
+ The built-in CSS support of webpack is not mandatory, you can still chain the `less-loader` with [`css-loader`](https://github.com/webpack/css-loader) and [`style-loader`](https://github.com/webpack/style-loader) to immediately apply all styles to the DOM.
475
522
 
476
523
  **webpack.config.js**
477
524
 
@@ -498,7 +545,7 @@ module.exports = {
498
545
  };
499
546
  ```
500
547
 
501
- Unfortunately, Less doesn't map all options 1-by-1 to camelCase. When in doubt, [check their executable](https://github.com/less/less.js/blob/3.x/bin/lessc) and search for the dash-case option.
548
+ Note that in this case the `type` and `experiments.css` options should not be set for this rule, and options like `sourceMap` have to be enabled for the `css-loader` too.
502
549
 
503
550
  ### Source maps
504
551
 
@@ -513,14 +560,8 @@ module.exports = {
513
560
  rules: [
514
561
  {
515
562
  test: /\.less$/i,
563
+ type: "css/auto",
516
564
  use: [
517
- "style-loader",
518
- {
519
- loader: "css-loader",
520
- options: {
521
- sourceMap: true,
522
- },
523
- },
524
565
  {
525
566
  loader: "less-loader",
526
567
  options: {
@@ -531,6 +572,9 @@ module.exports = {
531
572
  },
532
573
  ],
533
574
  },
575
+ experiments: {
576
+ css: true,
577
+ },
534
578
  };
535
579
  ```
536
580
 
@@ -538,7 +582,10 @@ If you want to edit the original Less files inside Chrome, [there's a good blog
538
582
 
539
583
  ### In production
540
584
 
541
- Usually, it's recommended to extract the style sheets into a dedicated file in production using the [MiniCssExtractPlugin](https://github.com/webpack/mini-css-extract-plugin). This way your styles are not dependent on JavaScript, improving performance and cacheability.
585
+ The built-in CSS support of webpack always extracts style sheets into dedicated files, so your styles are not dependent on JavaScript, which improves performance and cacheability.
586
+ The name of the generated files can be configured using the [`output.cssFilename`](https://webpack.js.org/configuration/output/#outputcssfilename) and [`output.cssChunkFilename`](https://webpack.js.org/configuration/output/#outputcsschunkfilename) options.
587
+
588
+ When you chain the loader with `css-loader` and `style-loader` instead, it's recommended to extract the style sheets into a dedicated file in production using the [MiniCssExtractPlugin](https://github.com/webpack/mini-css-extract-plugin).
542
589
 
543
590
  ### Imports
544
591
 
@@ -568,10 +615,14 @@ module.exports = {
568
615
  rules: [
569
616
  {
570
617
  test: /\.less$/i,
571
- use: ["style-loader", "css-loader", "less-loader"],
618
+ type: "css/auto",
619
+ use: ["less-loader"],
572
620
  },
573
621
  ],
574
622
  },
623
+ experiments: {
624
+ css: true,
625
+ },
575
626
  resolve: {
576
627
  byDependency: {
577
628
  // More options can be found here https://webpack.js.org/configuration/resolve/
@@ -595,13 +646,8 @@ module.exports = {
595
646
  rules: [
596
647
  {
597
648
  test: /\.less$/i,
649
+ type: "css/auto",
598
650
  use: [
599
- {
600
- loader: "style-loader",
601
- },
602
- {
603
- loader: "css-loader",
604
- },
605
651
  {
606
652
  loader: "less-loader",
607
653
  options: {
@@ -614,6 +660,9 @@ module.exports = {
614
660
  },
615
661
  ],
616
662
  },
663
+ experiments: {
664
+ css: true,
665
+ },
617
666
  };
618
667
  ```
619
668
 
@@ -668,14 +717,41 @@ Bundling CSS with webpack has some nice advantages like referencing images and f
668
717
 
669
718
  In production, on the other hand, it's not a good idea to apply your style sheets depending on JS execution. Rendering may be delayed or even a [FOUC](https://en.wikipedia.org/wiki/Flash_of_unstyled_content) might be visible. Thus it's often still better to have them as separate files in your final production build.
670
719
 
671
- There are two possibilities to extract a style sheet from the bundle:
720
+ The built-in CSS support of webpack does this out of the box: every entry point and chunk gets its own style sheet, no extra plugin required.
721
+ When you chain the loader with the `css-loader` instead, use the [`MiniCssExtractPlugin`](https://github.com/webpack/mini-css-extract-plugin) to extract a style sheet from the bundle.
672
722
 
673
- - [`extract-loader`](https://github.com/peerigon/extract-loader) (simpler, but specialized on the css-loader's output)
674
- - [`MiniCssExtractPlugin`](https://github.com/webpack/mini-css-extract-plugin) (more complex, but works in all use-cases)
723
+ ### CSS modules
675
724
 
676
- ### CSS modules gotcha
725
+ With the built-in CSS support of webpack, `*.module.less` files are treated as [CSS modules](https://github.com/css-modules/css-modules) when the module `type` is `css/auto`, and all files are treated as CSS modules when the module `type` is `css/module`:
726
+
727
+ **webpack.config.js**
728
+
729
+ ```js
730
+ module.exports = {
731
+ module: {
732
+ rules: [
733
+ {
734
+ test: /\.less$/i,
735
+ type: "css/auto",
736
+ use: ["less-loader"],
737
+ },
738
+ ],
739
+ },
740
+ experiments: {
741
+ css: true,
742
+ },
743
+ };
744
+ ```
745
+
746
+ **index.js**
747
+
748
+ ```js
749
+ import * as styles from "./style.module.less";
750
+
751
+ document.body.className = styles.box;
752
+ ```
677
753
 
678
- There is a known problem when using Less with [CSS modules](https://github.com/css-modules/css-modules) regarding relative file paths in `url(...)` statements.
754
+ There is a known problem when using Less with CSS modules regarding relative file paths in `url(...)` statements.
679
755
  [See this issue for an explanation](https://github.com/webpack/less-loader/issues/109#issuecomment-253797335).
680
756
 
681
757
  ## Contributing
@@ -6,79 +6,113 @@ Object.defineProperty(exports, "__esModule", {
6
6
  exports.default = void 0;
7
7
  var _nodePath = _interopRequireDefault(require("node:path"));
8
8
  var _options = _interopRequireDefault(require("./options.json"));
9
- var _utils = require("./utils");
9
+ var _utils = require("./utils.js");
10
10
  function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
11
- async function lessLoader(source) {
12
- const options = this.getOptions(_options.default);
11
+ /** @typedef {import("webpack").LoaderContext<LoaderOptions>} LoaderContext */
12
+ /** @typedef {import("schema-utils/declarations/validate").Schema} Schema */
13
+ /** @typedef {import("./utils.js").LoaderOptions} LoaderOptions */
14
+ /** @typedef {import("./utils.js").LessError} LessError */
15
+ /** @typedef {import("./utils.js").SourceMap} SourceMap */
16
+
17
+ /**
18
+ * Webpack loader that compiles Less to CSS.
19
+ * @this {LoaderContext}
20
+ * @param {string} content content
21
+ * @returns {Promise<void>} loader result
22
+ */
23
+ async function lessLoader(content) {
24
+ const options = this.getOptions(/** @type {Schema} */_options.default);
13
25
  const callback = this.async();
14
26
  let implementation;
15
27
  try {
16
- implementation = (0, _utils.getLessImplementation)(this, options.implementation);
28
+ implementation = await (0, _utils.getLessImplementation)(this, options.implementation);
17
29
  } catch (error) {
18
- callback(error);
30
+ callback(/** @type {Error} */error);
19
31
  return;
20
32
  }
21
33
  if (!implementation) {
22
34
  callback(new Error(`The Less implementation "${options.implementation}" not found`));
23
35
  return;
24
36
  }
25
- const lessOptions = (0, _utils.getLessOptions)(this, options, implementation);
37
+ const {
38
+ lessOptions,
39
+ pendingDependencyTasks
40
+ } = (0, _utils.getLessOptions)(this, options, implementation);
26
41
  const useSourceMap = typeof options.sourceMap === "boolean" ? options.sourceMap : this.sourceMap;
27
42
  if (useSourceMap) {
28
43
  lessOptions.sourceMap = {
29
44
  sourceMapBasepath: "",
30
45
  outputSourceFiles: true,
46
+ // @ts-expect-error bad types
31
47
  disableSourcemapAnnotation: true
32
48
  };
33
49
  }
34
- let data = source;
50
+ let data = content;
35
51
  if (typeof options.additionalData !== "undefined") {
36
52
  data = typeof options.additionalData === "function" ? `${await options.additionalData(data, this)}` : `${options.additionalData}\n${data}`;
37
53
  }
38
54
  const logger = this.getLogger("less-loader");
39
55
  const loaderContext = this;
56
+ const lessLogAsWarnOrErr = options.lessLogAsWarnOrErr !== false;
40
57
  const loggerListener = {
58
+ /** @param {string} message message */
41
59
  error(message) {
42
- // TODO enable by default in the next major release
43
- if (options.lessLogAsWarnOrErr) {
60
+ if (lessLogAsWarnOrErr) {
44
61
  loaderContext.emitError(new Error(message));
45
62
  } else {
46
63
  logger.error(message);
47
64
  }
48
65
  },
66
+ /** @param {string} message message */
49
67
  warn(message) {
50
- // TODO enable by default in the next major release
51
- if (options.lessLogAsWarnOrErr) {
68
+ if (lessLogAsWarnOrErr) {
52
69
  loaderContext.emitWarning(new Error(message));
53
70
  } else {
54
71
  logger.warn(message);
55
72
  }
56
73
  },
74
+ /** @param {string} message message */
57
75
  info(message) {
58
76
  logger.log(message);
59
77
  },
78
+ /** @param {string} message message */
60
79
  debug(message) {
61
80
  logger.debug(message);
62
81
  }
63
82
  };
83
+
84
+ // @ts-expect-error bad types
64
85
  implementation.logger.addListener(loggerListener);
65
86
  let result;
66
87
  try {
67
88
  result = await implementation.render(data, lessOptions);
68
89
  } catch (error) {
69
- if (error.filename) {
90
+ const lessError = /** @type {LessError} */error;
91
+ if (lessError.filename) {
70
92
  // `less` returns forward slashes on windows when `webpack` resolver return an absolute windows path in `WebpackFileManager`
71
93
  // Ref: https://github.com/webpack/less-loader/issues/357
72
- this.addDependency(_nodePath.default.normalize(error.filename));
94
+ this.addDependency(_nodePath.default.normalize(lessError.filename));
73
95
  }
74
- callback((0, _utils.errorFactory)(error));
96
+
97
+ // Wait for any pending sync-load dependency tracking so the failed
98
+ // build still snapshots the files it touched.
99
+ await Promise.all(pendingDependencyTasks);
100
+ callback((0, _utils.errorFactory)(lessError));
75
101
  return;
76
102
  } finally {
77
103
  // Fix memory leaks in `less`
104
+ // @ts-expect-error bad types
78
105
  implementation.logger.removeListener(loggerListener);
106
+
107
+ // @ts-expect-error we need it to reset loader context
79
108
  delete lessOptions.pluginManager.webpackLoaderContext;
109
+ // @ts-expect-error we need it to reset loader context
80
110
  delete lessOptions.pluginManager;
81
111
  }
112
+
113
+ // Ensure dependencies for any synchronously loaded resources (e.g.
114
+ // `data-uri()`, `@plugin`) are tracked before the loader completes.
115
+ await Promise.all(pendingDependencyTasks);
82
116
  const {
83
117
  css,
84
118
  imports
@@ -103,4 +137,5 @@ async function lessLoader(source) {
103
137
  }
104
138
  callback(null, css, map);
105
139
  }
106
- var _default = exports.default = lessLoader;
140
+ var _default = exports.default = lessLoader;module.exports = exports.default;
141
+ module.exports.default = exports.default;
@@ -0,0 +1 @@
1
+ {"type":"commonjs"}