css-loader 4.3.0 → 5.1.0

package/README.md

@@ -32,7 +32,7 @@ Then add the plugin to your `webpack` config. For example:
 **file.js**
 
 ```js
-import css from 'file.css';
+import css from "file.css";
 ```
 
 **webpack.config.js**
@@ -43,13 +43,15 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        use: ['style-loader', 'css-loader'],
+        use: ["style-loader", "css-loader"],
       },
     ],
   },
 };
 ```
 
+**Only for webpack v4:**
+
 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)).
 
 And run `webpack` via your preferred method.
@@ -66,7 +68,7 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        use: ['to-string-loader', 'css-loader'],
+        use: ["to-string-loader", "css-loader"],
       },
     ],
   },
@@ -76,7 +78,7 @@ module.exports = {
 or
 
 ```js
-const css = require('./test.css').toString();
+const css = require("./test.css").toString();
 
 console.log(css); // {String}
 ```
@@ -97,9 +99,9 @@ module.exports = {
       {
         test: /\.css$/i,
         use: [
-          'handlebars-loader', // handlebars loader expects raw resource string
-          'extract-loader',
-          'css-loader',
+          "handlebars-loader", // handlebars loader expects raw resource string
+          "extract-loader",
+          "css-loader",
         ],
       },
     ],
@@ -124,7 +126,7 @@ Type: `Boolean|Function`
 Default: `true`
 
 Enables/Disables `url`/`image-set` functions handling.
-Control `url()` resolving. Absolute URLs are not resolving.
+Control `url()` resolving. Absolute paths and root-relative URLs now resolving(Version [4.0.0](https://github.com/webpack-contrib/css-loader/blob/master/CHANGELOG.md#400-2020-07-25) and above).
 
 Examples resolutions:
 
@@ -157,7 +159,7 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           url: true,
         },
@@ -179,13 +181,13 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           url: (url, resourcePath) => {
             // resourcePath - path to css file
 
             // Don't handle `img.png` urls
-            if (url.includes('img.png')) {
+            if (url.includes("img.png")) {
               return false;
             }
 
@@ -238,7 +240,7 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           import: true,
         },
@@ -260,13 +262,13 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           import: (url, media, resourcePath) => {
             // resourcePath - path to css file
 
             // Don't handle `style.css` import
-            if (url.includes('style.css')) {
+            if (url.includes("style.css")) {
               return false;
             }
 
@@ -298,7 +300,7 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           modules: true,
         },
@@ -362,8 +364,8 @@ The loader replaces local selectors with unique identifiers. The chosen unique i
 
 ```js
 exports.locals = {
-  className: '_23_aKvs-b8bW2Vg3fwHozO',
-  subClass: '_13LGdX8RMStbBE9w-t0gZ1',
+  className: "_23_aKvs-b8bW2Vg3fwHozO",
+  subClass: "_13LGdX8RMStbBE9w-t0gZ1",
 };
 ```
 
@@ -391,8 +393,8 @@ This doesn't result in any change to the CSS itself but exports multiple classna
 
 ```js
 exports.locals = {
-  className: '_23_aKvs-b8bW2Vg3fwHozO',
-  subClass: '_13LGdX8RMStbBE9w-t0gZ1 _23_aKvs-b8bW2Vg3fwHozO',
+  className: "_23_aKvs-b8bW2Vg3fwHozO",
+  subClass: "_13LGdX8RMStbBE9w-t0gZ1 _23_aKvs-b8bW2Vg3fwHozO",
 };
 ```
 
@@ -415,14 +417,14 @@ To import a local classname from another module.
 
 ```css
 :local(.continueButton) {
-  composes: button from 'library/button.css';
+  composes: button from "library/button.css";
   background: red;
 }
 ```
 
 ```css
 :local(.nameEdit) {
-  composes: edit highlight from './edit.css';
+  composes: edit highlight from "./edit.css";
   background: red;
 }
 ```
@@ -431,8 +433,8 @@ To import from multiple modules use multiple `composes:` rules.
 
 ```css
 :local(.className) {
-  composes: edit hightlight from './edit.css';
-  composes: button from 'module/button.css';
+  composes: edit hightlight from "./edit.css";
+  composes: button from "module/button.css";
   composes: classFromThisModule;
   background: red;
 }
@@ -477,7 +479,7 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           modules: true,
         },
@@ -499,10 +501,10 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           // Using `local` value has same effect like using `modules: true`
-          modules: 'global',
+          modules: "global",
         },
       },
     ],
@@ -522,18 +524,18 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           modules: {
-            compileType: 'module',
-            mode: 'local',
+            compileType: "module",
+            mode: "local",
             auto: true,
             exportGlobals: true,
-            localIdentName: '[path][name]__[local]--[hash:base64:5]',
-            context: path.resolve(__dirname, 'src'),
-            localIdentHashPrefix: 'my-custom-hash',
+            localIdentName: "[path][name]__[local]--[hash:base64:5]",
+            localIdentContext: path.resolve(__dirname, "src"),
+            localIdentHashPrefix: "my-custom-hash",
             namedExport: true,
-            exportLocalsConvention: 'camelCase',
+            exportLocalsConvention: "camelCase",
             exportOnlyLocals: false,
           },
         },
@@ -563,10 +565,10 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           modules: {
-            compileType: 'icss',
+            compileType: "icss",
           },
         },
       },
@@ -586,8 +588,8 @@ Allows auto enable CSS modules based on filename.
 
 Possible values:
 
-- `true` - enable css modules for all files for which `/\.module\.\w+$/i.test(filename)` return true
-- `false` - disable css modules
+- `true` - enables CSS modules or interoperable CSS format, sets the [`modules.compileType`](#compiletype) option to `module` value for all files which satisfy `/\.module(s)?\.\w+$/i.test(filename)` condition or sets the [`modules.compileType`](#compiletype) option to `icss` value for all files which satisfy `/\.icss\.\w+$/i.test(filename)` condition
+- `false` - disables CSS modules or interoperable CSS format based on filename
 
 **webpack.config.js**
 
@@ -597,7 +599,7 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           modules: {
             auto: true,
@@ -621,7 +623,7 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           modules: {
             auto: /\.custom-module\.\w+$/i,
@@ -645,10 +647,10 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           modules: {
-            auto: (resourcePath) => resourcePath.endsWith('.custom-module.css'),
+            auto: (resourcePath) => resourcePath.endsWith(".custom-module.css"),
           },
         },
       },
@@ -676,10 +678,10 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           modules: {
-            mode: 'global',
+            mode: "global",
           },
         },
       },
@@ -702,20 +704,20 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           modules: {
             // Callback must return "local", "global", or "pure" values
             mode: (resourcePath) => {
               if (/pure.css$/i.test(resourcePath)) {
-                return 'pure';
+                return "pure";
               }
 
               if (/global.css$/i.test(resourcePath)) {
-                return 'global';
+                return "global";
               }
 
-              return 'local';
+              return "local";
             },
           },
         },
@@ -750,10 +752,10 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           modules: {
-            localIdentName: '[path][name]__[local]--[hash:base64:5]',
+            localIdentName: "[path][name]__[local]--[hash:base64:5]",
           },
         },
       },
@@ -777,10 +779,10 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           modules: {
-            context: path.resolve(__dirname, 'context'),
+            localIdentContext: path.resolve(__dirname, "src"),
           },
         },
       },
@@ -804,10 +806,10 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           modules: {
-            localIdentHashPrefix: 'hash',
+            localIdentHashPrefix: "hash",
           },
         },
       },
@@ -829,7 +831,7 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           modules: {
             localIdentRegExp: /page-(.*)\.css/i,
@@ -848,6 +850,8 @@ Default: `undefined`
 
 Allows to specify a function to generate the classname.
 By default we use built-in function to generate a classname.
+If the custom function returns `null` or `undefined`, we fallback to the
+built-in function to generate the classname.
 
 **webpack.config.js**
 
@@ -857,11 +861,11 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           modules: {
             getLocalIdent: (context, localIdentName, localName, options) => {
-              return 'whatever_random_class_name';
+              return "whatever_random_class_name";
             },
           },
         },
@@ -896,7 +900,7 @@ Enables/disables ES modules named export for locals.
 **index.js**
 
 ```js
-import { fooBaz, bar } from './styles.css';
+import { fooBaz, bar } from "./styles.css";
 
 console.log(fooBaz, bar);
 ```
@@ -911,7 +915,7 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           esModule: true,
           modules: {
@@ -939,7 +943,7 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           modules: {
             exportGlobals: true,
@@ -980,7 +984,7 @@ By default, the exported JSON keys mirror the class names (i.e `asIs` value).
 **file.js**
 
 ```js
-import { className } from 'file.css';
+import { className } from "file.css";
 ```
 
 **webpack.config.js**
@@ -991,10 +995,11 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
-          mode: 'local',
-          localsConvention: 'camelCase',
+          modules: {
+            exportLocalsConvention: "camelCase",
+          },
         },
       },
     ],
@@ -1021,7 +1026,7 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           modules: {
             exportOnlyLocals: true,
@@ -1048,7 +1053,7 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           sourceMap: true,
         },
@@ -1076,9 +1081,9 @@ module.exports = {
       {
         test: /\.css$/i,
         use: [
-          'style-loader',
+          "style-loader",
           {
-            loader: 'css-loader',
+            loader: "css-loader",
             options: {
               importLoaders: 2,
               // 0 => no loaders (default);
@@ -1086,8 +1091,8 @@ module.exports = {
               // 2 => postcss-loader, sass-loader
             },
           },
-          'postcss-loader',
-          'sass-loader',
+          "postcss-loader",
+          "sass-loader",
         ],
       },
     ],
@@ -1115,7 +1120,7 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        loader: 'css-loader',
+        loader: "css-loader",
         options: {
           esModule: false,
         },
@@ -1127,10 +1132,66 @@ module.exports = {
 
 ## Examples
 
+### Disable url resolving using the `/* webpackIgnore: true */` comment
+
+With the help of the `/* webpackIgnore: true */`comment, it is possible to disable sources handling for rules and for individual declarations.
+
+```css
+/* webpackIgnore: true */
+@import url(./basic.css);
+@import /* webpackIgnore: true */ url(./imported.css);
+
+.class {
+  /* Disabled url handling for the all urls in the 'background' declaration */
+  color: red;
+  /* webpackIgnore: true */
+  background: url("./url/img.png"), url("./url/img.png");
+}
+
+.class {
+  /* Disabled url handling for the first url in the 'background' declaration */
+  color: red;
+  background: 
+    /* webpackIgnore: true */ url("./url/img.png"), url("./url/img.png");
+}
+
+.class {
+  /* Disabled url handling for the second url in the 'background' declaration */
+  color: red;
+  background: url("./url/img.png"),
+    /* webpackIgnore: true */ url("./url/img.png");
+}
+
+/* prettier-ignore */
+.class {
+  /* Disabled url handling for the second url in the 'background' declaration */
+  color: red;
+  background: url("./url/img.png"),
+    /* webpackIgnore: true */ 
+    url("./url/img.png");
+}
+
+/* prettier-ignore */
+.class {
+  /* Disabled url handling for third and sixth urls in the 'background-image' declaration */
+  background-image: image-set(
+    url(./url/img.png) 2x,
+    url(./url/img.png) 3x,
+    /* webpackIgnore:  true */ url(./url/img.png) 4x,
+    url(./url/img.png) 5x,
+    url(./url/img.png) 6x,
+    /* webpackIgnore:  true */
+    url(./url/img.png) 7x
+  );
+}
+```
+
 ### Assets
 
 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.
 
+**For webpack v5:**
+
 **webpack.config.js**
 
 ```js
@@ -1139,11 +1200,33 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        use: ['style-loader', 'css-loader'],
+        use: ["style-loader", "css-loader"],
       },
       {
         test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
-        loader: 'url-loader',
+        // More information here https://webpack.js.org/guides/asset-modules/
+        type: "asset",
+      },
+    ],
+  },
+};
+```
+
+**For webpack v4:**
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        use: ["style-loader", "css-loader"],
+      },
+      {
+        test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
+        loader: "url-loader",
         options: {
           limit: 8192,
         },
@@ -1177,34 +1260,39 @@ module.exports = {
         // For Less - /\.((c|le)ss)$/i,
         test: /\.((c|sa|sc)ss)$/i,
         use: [
-          'style-loader',
+          "style-loader",
           {
-            loader: 'css-loader',
+            loader: "css-loader",
             options: {
               // Run `postcss-loader` on each CSS `@import`, do not forget that `sass-loader` compile non CSS `@import`'s into a single file
               // If you need run `sass-loader` and `postcss-loader` on each CSS `@import` please set it to `2`
               importLoaders: 1,
-              // Automatically enable css modules for files satisfying `/\.module\.\w+$/i` RegExp.
-              modules: { auto: true },
             },
           },
           {
-            loader: 'postcss-loader',
+            loader: "postcss-loader",
             options: { plugins: () => [postcssPresetEnv({ stage: 0 })] },
           },
           // Can be `less-loader`
           {
-            loader: 'sass-loader',
+            loader: "sass-loader",
           },
         ],
       },
+      // For webpack v5
       {
         test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
-        loader: 'url-loader',
-        options: {
-          limit: 8192,
-        },
+        // More information here https://webpack.js.org/guides/asset-modules/
+        type: "asset",
       },
+      // For webpack v4
+      // {
+      //  test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
+      //  loader: "url-loader",
+      //  options: {
+      //    limit: 8192,
+      //  },
+      // },
     ],
   },
 };
@@ -1228,15 +1316,15 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        use: ['style-loader', 'css-loader'],
+        use: ["style-loader", "css-loader"],
       },
     ],
   },
   resolve: {
     alias: {
-      '/assets/unresolved/img.png': path.resolve(
+      "/assets/unresolved/img.png": path.resolve(
         __dirname,
-        'assets/real-path-to-img/img.png'
+        "assets/real-path-to-img/img.png"
       ),
     },
   },
@@ -1245,7 +1333,7 @@ module.exports = {
 
 ### Separating `Interoperable CSS`-only and `CSS Module` features
 
-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 `compileType` 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.  
+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 `compileType` 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.
 Meanwhile all files matching `*.module.scss` are treated as `CSS Modules` in this example.
 
 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).
@@ -1324,7 +1412,7 @@ $colorBackground: red;
 File treated as `CSS Module`.
 
 ```scss
-@import 'variables.scss';
+@import "variables.scss";
 .componentClass {
   background-color: $colorBackground;
 }
@@ -1335,8 +1423,8 @@ File treated as `CSS Module`.
 Using both `CSS Module` functionality as well as SCSS variables directly in JavaScript.
 
 ```jsx
-import svars from 'variables.scss';
-import styles from 'Component.module.scss';
+import svars from "variables.scss";
+import styles from "Component.module.scss";
 
 // Render DOM with CSS modules class name
 // <div className={styles.componentClass}>

package/dist/CssSyntaxError.js

@@ -11,17 +11,19 @@ class CssSyntaxError extends Error {
     const {
       reason,
       line,
-      column
+      column,
+      file
     } = error;
-    this.name = 'CssSyntaxError'; // Based on https://github.com/postcss/postcss/blob/master/lib/css-syntax-error.es6#L132
+    this.name = "CssSyntaxError"; // Based on https://github.com/postcss/postcss/blob/master/lib/css-syntax-error.es6#L132
     // We don't need `plugin` and `file` properties.
 
     this.message = `${this.name}\n\n`;
 
-    if (typeof line !== 'undefined') {
+    if (typeof line !== "undefined") {
       this.message += `(${line}:${column}) `;
     }
 
+    this.message += file ? `${file} ` : "<css input> ";
     this.message += `${reason}`;
     const code = error.showSourceCode();