css-loader 5.2.7 → 6.3.0

package/README.md

@@ -21,6 +21,8 @@ The `css-loader` interprets `@import` and `url()` like `import/require()` and wi
 
 ## Getting Started
 
+> ⚠ To use css-loader, webpack@5 is required
+
 To begin, you'll need to install `css-loader`:
 
 ```console
@@ -50,82 +52,31 @@ module.exports = {
 };
 ```
 
-**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.
 
-### `toString`
-
-You can also use the css-loader results directly as a string, such as in Angular's component style.
-
-**webpack.config.js**
-
-```js
-module.exports = {
-  module: {
-    rules: [
-      {
-        test: /\.css$/i,
-        use: ["to-string-loader", "css-loader"],
-      },
-    ],
-  },
-};
-```
-
-or
-
-```js
-const css = require("./test.css").toString();
-
-console.log(css); // {String}
-```
-
-If there are SourceMaps, they will also be included in the result string.
-
-If, for one reason or another, you need to extract CSS as a
-plain string resource (i.e. not wrapped in a JS module) you
-might want to check out the [extract-loader](https://github.com/peerigon/extract-loader).
-It's useful when you, for instance, need to post process the CSS as a string.
-
-**webpack.config.js**
-
-```js
-module.exports = {
-  module: {
-    rules: [
-      {
-        test: /\.css$/i,
-        use: [
-          "handlebars-loader", // handlebars loader expects raw resource string
-          "extract-loader",
-          "css-loader",
-        ],
-      },
-    ],
-  },
-};
-```
+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).
 
 ## Options
 
-|                 Name                  |            Type             |      Default       | Description                                                            |
-| :-----------------------------------: | :-------------------------: | :----------------: | :--------------------------------------------------------------------- |
-|           **[`url`](#url)**           |    `{Boolean\|Function}`    |       `true`       | Enables/Disables `url`/`image-set` functions handling                  |
-|        **[`import`](#import)**        |    `{Boolean\|Function}`    |       `true`       | Enables/Disables `@import` at-rules handling                           |
-|       **[`modules`](#modules)**       | `{Boolean\|String\|Object}` |   `{auto: true}`   | Enables/Disables CSS Modules and their configuration                   |
-|     **[`sourceMap`](#sourcemap)**     |         `{Boolean}`         | `compiler.devtool` | Enables/Disables generation of source maps                             |
-| **[`importLoaders`](#importloaders)** |         `{Number}`          |        `0`         | Enables/Disables or setups number of loaders applied before CSS loader |
-|      **[`esModule`](#esmodule)**      |         `{Boolean}`         |       `true`       | Use ES modules syntax                                                  |
+|                 Name                  |                     Type                     |      Default       | Description                                                                                                                                                                                                                                               |
+| :-----------------------------------: | :------------------------------------------: | :----------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|           **[`url`](#url)**           |             `{Boolean\|Object}`              |       `true`       | Allows to enables/disables `url()`/`image-set()` functions handling                                                                                                                                                                                       |
+|        **[`import`](#import)**        |             `{Boolean\|Object}`              |       `true`       | Allows to enables/disables `@import` at-rules handling                                                                                                                                                                                                    |
+|       **[`modules`](#modules)**       |         `{Boolean\|String\|Object}`          |   `{auto: true}`   | Allows to enables/disables or setup CSS Modules options                                                                                                                                                                                                   |
+|     **[`sourceMap`](#sourcemap)**     |                 `{Boolean}`                  | `compiler.devtool` | Enables/Disables generation of source maps                                                                                                                                                                                                                |
+| **[`importLoaders`](#importloaders)** |                  `{Number}`                  |        `0`         | Allows enables/disables or setups number of loaders applied before CSS loader for `@import`/CSS Modules and ICSS imports                                                                                                                                  |
+|      **[`esModule`](#esmodule)**      |                 `{Boolean}`                  |       `true`       | Use ES modules syntax                                                                                                                                                                                                                                     |
+|    **[`exportType`](#exporttype)**    | `{'array' \| 'string' \| 'css-style-sheet'}` |      `array`       | 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)) |
 
 ### `url`
 
-Type: `Boolean|Function`
+Type: `Boolean|Object`
 Default: `true`
 
-Enables/Disables handling the CSS functions `url` and `image-set`. If set to `false`, `css-loader` will not parse any paths specified in `url` or `image-set`. A function can also be passed to control this behavior dynamically based on the path to the asset. 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.
+Allow to enable/disables handling the CSS functions `url` and `image-set`.
+If set to `false`, `css-loader` will not parse any paths specified in `url` or `image-set`.
+A function can also be passed to control this behavior dynamically based on the path to the asset.
+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.
 
 Examples resolutions:
 
@@ -168,7 +119,7 @@ module.exports = {
 };
 ```
 
-#### `Function`
+#### `Object`
 
 Allow to filter `url()`. All filtered `url()` will not be resolved (left in the code as they were written).
 
@@ -182,15 +133,17 @@ module.exports = {
         test: /\.css$/i,
         loader: "css-loader",
         options: {
-          url: (url, resourcePath) => {
-            // resourcePath - path to css file
+          url: {
+            filter: (url, resourcePath) => {
+              // resourcePath - path to css file
 
-            // Don't handle `img.png` urls
-            if (url.includes("img.png")) {
-              return false;
-            }
+              // Don't handle `img.png` urls
+              if (url.includes("img.png")) {
+                return false;
+              }
 
-            return true;
+              return true;
+            },
           },
         },
       },
@@ -201,10 +154,10 @@ module.exports = {
 
 ### `import`
 
-Type: `Boolean|Function`
+Type: `Boolean|Object`
 Default: `true`
 
-Enables/Disables `@import` at-rules handling.
+Allows to enables/disables `@import` at-rules handling.
 Control `@import` resolving. Absolute urls in `@import` will be moved in runtime code.
 
 Examples resolutions:
@@ -249,7 +202,16 @@ module.exports = {
 };
 ```
 
-#### `Function`
+#### `Object`
+
+|          Name           |     Type     |   Default   | Description               |
+| :---------------------: | :----------: | :---------: | :------------------------ |
+| **[`filter`](#filter)** | `{Function}` | `undefined` | Allow to filter `@import` |
+
+##### `filter`
+
+Type: `Function`
+Default: `undefined`
 
 Allow to filter `@import`. All filtered `@import` will not be resolved (left in the code as they were written).
 
@@ -263,15 +225,17 @@ module.exports = {
         test: /\.css$/i,
         loader: "css-loader",
         options: {
-          import: (url, media, resourcePath) => {
-            // resourcePath - path to css file
+          import: {
+            filter: (url, media, resourcePath) => {
+              // resourcePath - path to css file
 
-            // Don't handle `style.css` import
-            if (url.includes("style.css")) {
-              return false;
-            }
+              // Don't handle `style.css` import
+              if (url.includes("style.css")) {
+                return false;
+              }
 
-            return true;
+              return true;
+            },
           },
         },
       },
@@ -283,9 +247,15 @@ module.exports = {
 ### `modules`
 
 Type: `Boolean|String|Object`
-Default: based on filename, `true` for all files matching `/\.module\.\w+$/i.test(filename)` regular expression, more information you can read [here](https://github.com/webpack-contrib/css-loader#auto)
+Default: `undefined`
+
+Allows to enable/disable CSS Modules or ICSS and setup configuration:
 
-Enables/Disables CSS Modules and their configuration.
+- `undefined` - enable CSS modules for all files matching `/\.module\.\w+$/i.test(filename)` and `/\.icss\.\w+$/i.test(filename)` regexp.
+- `true` - enable CSS modules for all files.
+- `false` - disables CSS Modules for all files.
+- `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)
+- `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)
 
 The `modules` option enables/disables the **[CSS Modules](https://github.com/css-modules/css-modules)** specification and setup basic behaviour.
 
@@ -526,13 +496,12 @@ module.exports = {
         loader: "css-loader",
         options: {
           modules: {
-            compileType: "module",
             mode: "local",
             auto: true,
             exportGlobals: true,
             localIdentName: "[path][name]__[local]--[hash:base64:5]",
             localIdentContext: path.resolve(__dirname, "src"),
-            localIdentHashPrefix: "my-custom-hash",
+            localIdentHashSalt: "my-custom-hash",
             namedExport: true,
             exportLocalsConvention: "camelCase",
             exportOnlyLocals: false,
@@ -544,50 +513,26 @@ module.exports = {
 };
 ```
 
-##### `compileType`
-
-Type: `'module' | 'icss'`
-Default: `'module'`
-
-Controls the level of compilation applied to the input styles.
-
-The `module` handles `class` and `id` scoping and `@value` values.
-The `icss` will only compile the low level `Interoperable CSS` format for declaring `:import` and `:export` dependencies between CSS and other languages.
-
-ICSS underpins CSS Module support, and provides a low level syntax for other tools to implement CSS-module variations of their own.
-
-**webpack.config.js**
-
-```js
-module.exports = {
-  module: {
-    rules: [
-      {
-        test: /\.css$/i,
-        loader: "css-loader",
-        options: {
-          modules: {
-            compileType: "icss",
-          },
-        },
-      },
-    ],
-  },
-};
-```
-
 ##### `auto`
 
 Type: `Boolean|RegExp|Function`
-Default: `'true'`
+Default: `undefined`
 
-Allows auto enable CSS modules based on filename.
+Allows auto enable CSS modules/ICSS based on filename when `modules` option is object.
+
+Possible values:
+
+- `undefined` - enable CSS modules for all files.
+- `true` - enable CSS modules for all files matching `/\.module\.\w+$/i.test(filename)` and `/\.icss\.\w+$/i.test(filename)` regexp.
+- `false` - disables CSS Modules.
+- `RegExp` - enable CSS modules for all files matching `/RegExp/i.test(filename)` regexp.
+- `function` - enable CSS Modules for files based on the filename satisfying your filter function check.
 
 ###### `Boolean`
 
 Possible values:
 
-- `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
+- `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
 - `false` - disables CSS modules or interoperable CSS format based on filename
 
 **webpack.config.js**
@@ -665,9 +610,16 @@ Default: `'local'`
 
 Setup `mode` option. You can omit the value when you want `local` mode.
 
+Controls the level of compilation applied to the input styles.
+
+The `local`, `global`, and `pure` handles `class` and `id` scoping and `@value` values.
+The `icss` will only compile the low level `Interoperable CSS` format for declaring `:import` and `:export` dependencies between CSS and other languages.
+
+ICSS underpins CSS Module support, and provides a low level syntax for other tools to implement CSS-module variations of their own.
+
 ###### `String`
 
-Possible values - `local`, `global`, and `pure`.
+Possible values - `local`, `global`, `pure`, and `icss`.
 
 **webpack.config.js**
 
@@ -693,7 +645,7 @@ module.exports = {
 
 Allows set different values for the `mode` option based on a filename
 
-Possible return values - `local`, `global`, and `pure`.
+Possible return values - `local`, `global`, `pure` and `icss`.
 
 **webpack.config.js**
 
@@ -732,7 +684,25 @@ Type: `String`
 Default: `'[hash:base64]'`
 
 Allows to configure the generated local ident name.
-See [loader-utils's documentation](https://github.com/webpack/loader-utils#interpolatename) for more information on options.
+
+For more information on options see:
+
+- [webpack template strings](https://webpack.js.org/configuration/output/#template-strings),
+- [output.hashDigest](https://webpack.js.org/configuration/output/#outputhashdigest),
+- [output.hashDigestLength](https://webpack.js.org/configuration/output/#outputhashdigestlength),
+- [output.hashFunction](https://webpack.js.org/configuration/output/#outputhashfunction),
+- [output.hashSalt](https://webpack.js.org/configuration/output/#outputhashsalt).
+
+Supported template strings:
+
+- `[name]` the basename of the resource
+- `[folder]` the folder the resource relative to the `compiler.context` option or `modules.localIdentContext` option.
+- `[path]` the path of the resource relative to the `compiler.context` option or `modules.localIdentContext` option.
+- `[file]` - filename and path.
+- `[ext]` - extension with leading `.`.
+- `[hash]` - the hash of the string, generated based on `localIdentHashSalt`, `localIdentHashFunction`, `localIdentHashDigest`, `localIdentHashDigestLength`, `localIdentContext`, `resourcePath` and `exportName`
+- `[<hashFunction>:hash:<hashDigest>:<hashDigestLength>]` - hash with hash settings.
+- `[local]` - original class.
 
 Recommendations:
 
@@ -790,12 +760,97 @@ module.exports = {
 };
 ```
 
-##### `localIdentHashPrefix`
+##### `localIdentHashSalt`
 
 Type: `String`
 Default: `undefined`
 
 Allows to add custom hash to generate more unique classes.
+For more information see [output.hashSalt](https://webpack.js.org/configuration/output/#outputhashsalt).
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        loader: "css-loader",
+        options: {
+          modules: {
+            localIdentHashSalt: "hash",
+          },
+        },
+      },
+    ],
+  },
+};
+```
+
+##### `localIdentHashFunction`
+
+Type: `String`
+Default: `md4`
+
+Allows to specify hash function to generate classes .
+For more information see [output.hashFunction](https://webpack.js.org/configuration/output/#outputhashfunction).
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        loader: "css-loader",
+        options: {
+          modules: {
+            localIdentHashFunction: "md4",
+          },
+        },
+      },
+    ],
+  },
+};
+```
+
+##### `localIdentHashDigest`
+
+Type: `String`
+Default: `hex`
+
+Allows to specify hash digest to generate classes.
+For more information see [output.hashDigest](https://webpack.js.org/configuration/output/#outputhashdigest).
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        loader: "css-loader",
+        options: {
+          modules: {
+            localIdentHashDigest: "base64",
+          },
+        },
+      },
+    ],
+  },
+};
+```
+
+##### `localIdentHashDigestLength`
+
+Type: `Number`
+Default: `20`
+
+Allows to specify hash digest length to generate classes.
+For more information see [output.hashDigestLength](https://webpack.js.org/configuration/output/#outputhashdigestlength).
 
 **webpack.config.js**
 
@@ -808,7 +863,7 @@ module.exports = {
         loader: "css-loader",
         options: {
           modules: {
-            localIdentHashPrefix: "hash",
+            localIdentHashDigestLength: 5,
           },
         },
       },
@@ -927,6 +982,9 @@ module.exports = {
 };
 ```
 
+To set a custom name for namedExport, can use [`exportLocalsConvention`](#exportLocalsConvention) option as a function.
+Example below in the [`examples`](#examples) section.
+
 ##### `exportGlobals`
 
 Type: `Boolean`
@@ -956,11 +1014,13 @@ module.exports = {
 
 ##### `exportLocalsConvention`
 
-Type: `String`
+Type: `String|Function`
 Default: based on the `modules.namedExport` option value, if `true` - `camelCaseOnly`, otherwise `asIs`
 
 Style of exported class names.
 
+###### `String`
+
 By default, the exported JSON keys mirror the class names (i.e `asIs` value).
 
 > ⚠ Only `camelCaseOnly` value allowed if you set the `namedExport` value to `true`.
@@ -1006,16 +1066,29 @@ module.exports = {
 };
 ```
 
-##### `exportOnlyLocals`
-
-Type: `Boolean`
-Default: `false`
+###### `Function`
 
-Export only locals.
+**webpack.config.js**
 
-**Useful** when you use **css modules** for pre-rendering (for example SSR).
-For pre-rendering with `mini-css-extract-plugin` you should use this option instead of `style-loader!css-loader` **in the pre-rendering bundle**.
-It doesn't embed CSS but only exports the identifier mappings.
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        loader: "css-loader",
+        options: {
+          modules: {
+            exportLocalsConvention: function (name) {
+              return name.replace(/-/g, "_");
+            },
+          },
+        },
+      },
+    ],
+  },
+};
+```
 
 **webpack.config.js**
 
@@ -1028,7 +1101,15 @@ module.exports = {
         loader: "css-loader",
         options: {
           modules: {
-            exportOnlyLocals: true,
+            exportLocalsConvention: function (name) {
+              return [
+                name.replace(/-/g, "_"),
+                // dashesCamelCase
+                name.replace(/-+(\w)/g, (match, firstLetter) =>
+                  firstLetter.toUpperCase()
+                ),
+              ];
+            },
           },
         },
       },
@@ -1037,12 +1118,16 @@ module.exports = {
 };
 ```
 
-### `sourceMap`
+##### `exportOnlyLocals`
 
 Type: `Boolean`
-Default: depends on the `compiler.devtool` value
+Default: `false`
 
-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.
+Export only locals.
+
+**Useful** when you use **css modules** for pre-rendering (for example SSR).
+For pre-rendering with `mini-css-extract-plugin` you should use this option instead of `style-loader!css-loader` **in the pre-rendering bundle**.
+It doesn't embed CSS but only exports the identifier mappings.
 
 **webpack.config.js**
 
@@ -1054,7 +1139,9 @@ module.exports = {
         test: /\.css$/i,
         loader: "css-loader",
         options: {
-          sourceMap: true,
+          modules: {
+            exportOnlyLocals: true,
+          },
         },
       },
     ],
@@ -1067,9 +1154,9 @@ module.exports = {
 Type: `Number`
 Default: `0`
 
-Enables/Disables or setups number of loaders applied before CSS loader.
+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.
 
-The option `importLoaders` allows you to configure how many loaders before `css-loader` should be applied to `@import`ed resources.
+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.
 
 **webpack.config.js**
 
@@ -1101,6 +1188,31 @@ module.exports = {
 
 This may change in the future when the module system (i. e. webpack) supports loader matching by origin.
 
+### `sourceMap`
+
+Type: `Boolean`
+Default: depends on the `compiler.devtool` value
+
+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.
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        loader: "css-loader",
+        options: {
+          sourceMap: true,
+        },
+      },
+    ],
+  },
+};
+```
+
 ### `esModule`
 
 Type: `Boolean`
@@ -1129,6 +1241,203 @@ module.exports = {
 };
 ```
 
+### `exportType`
+
+Type: `'array' | 'string' | 'css-style-sheet'`
+Default: `'array'`
+
+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)).
+Default value is `'array'`, i.e. loader exports array of modules with specific API which is used in `style-loader` or other.
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        assert: { type: "css" },
+        loader: "css-loader",
+        options: {
+          exportType: "css-style-sheet",
+        },
+      },
+    ],
+  },
+};
+```
+
+**src/index.js**
+
+```js
+import sheet from "./styles.css" assert { type: "css" };
+
+document.adoptedStyleSheets = [sheet];
+shadowRoot.adoptedStyleSheets = [sheet];
+```
+
+#### `'array'`
+
+The default export is array of modules with specific API which is used in `style-loader` or other.
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.(sa|sc|c)ss$/i,
+        use: ["style-loader", "css-loader", "postcss-loader", "sass-loader"],
+      },
+    ],
+  },
+};
+```
+
+**src/index.js**
+
+```js
+// `style-loader` applies styles to DOM
+import "./styles.css";
+```
+
+#### `'string'`
+
+> ⚠ You don't need [`style-loader`](https://github.com/webpack-contrib/style-loader) anymore, please remove it.
+> ⚠ 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).
+
+The default export is `string`.
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.(sa|sc|c)ss$/i,
+        use: ["css-loader", "postcss-loader", "sass-loader"],
+      },
+    ],
+  },
+};
+```
+
+**src/index.js**
+
+```js
+import sheet from "./styles.css";
+
+console.log(sheet);
+```
+
+#### `'css-style-sheet'`
+
+> ⚠ `@import` rules not yet allowed, more [information](https://web.dev/css-module-scripts/#@import-rules-not-yet-allowed)
+> ⚠ You don't need [`style-loader`](https://github.com/webpack-contrib/style-loader) anymore, please remove it.
+> ⚠ 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).
+> ⚠ 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)
+
+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)).
+
+Useful for [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) and shadow DOM.
+
+More information:
+
+- [Using CSS Module Scripts to import stylesheets](https://web.dev/css-module-scripts/)
+- [Constructable Stylesheets: seamless reusable styles](https://developers.google.com/web/updates/2019/02/constructable-stylesheets)
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        assert: { type: "css" },
+        loader: "css-loader",
+        options: {
+          exportType: "css-style-sheet",
+        },
+      },
+
+      // For Sass/SCSS:
+      //
+      // {
+      //   assert: { type: "css" },
+      //   rules: [
+      //     {
+      //       loader: "css-loader",
+      //       options: {
+      //         exportType: "css-style-sheet",
+      //         // Other options
+      //       },
+      //     },
+      //     {
+      //       loader: "sass-loader",
+      //       options: {
+      //         // Other options
+      //       },
+      //     },
+      //   ],
+      // },
+    ],
+  },
+};
+```
+
+**src/index.js**
+
+```js
+// Example for Sass/SCSS:
+// import sheet from "./styles.scss" assert { type: "css" };
+
+// Example for CSS modules:
+// import sheet, { myClass } from "./styles.scss" assert { type: "css" };
+
+// Example for CSS:
+import sheet from "./styles.css" assert { type: "css" };
+
+document.adoptedStyleSheets = [sheet];
+shadowRoot.adoptedStyleSheets = [sheet];
+```
+
+For migration purposes, you can use the following configuration:
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        oneOf: [
+          {
+            assert: { type: "css" },
+            loader: "css-loader",
+            options: {
+              exportType: "css-style-sheet",
+              // Other options
+            },
+          },
+          {
+            use: [
+              "style-loader",
+              {
+                loader: "css-loader",
+                options: {
+                  // Other options
+                },
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
 ## Examples
 
 ### Recommend
@@ -1149,7 +1458,7 @@ module.exports = {
   module: {
     rules: [
       {
-        test: /\.(sa|sc|c)ss$/,
+        test: /\.(sa|sc|c)ss$/i,
         use: [
           devMode ? "style-loader" : MiniCssExtractPlugin.loader,
           "css-loader",
@@ -1243,29 +1552,13 @@ module.exports = {
 };
 ```
 
-**For webpack v4:**
+### Extract
 
-**webpack.config.js**
+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.
 
-```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,
-        },
-      },
-    ],
-  },
-};
-```
+- 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.
+
+- 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
 
 ### Pure CSS, CSS modules and PostCSS
 
@@ -1287,7 +1580,7 @@ module.exports = {
           {
             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
+              // 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
               // If you need run `sass-loader` and `postcss-loader` on each CSS `@import` please set it to `2`
               importLoaders: 1,
             },
@@ -1308,14 +1601,6 @@ module.exports = {
         // 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,
-      //  },
-      // },
     ],
   },
 };
@@ -1354,9 +1639,34 @@ module.exports = {
 };
 ```
 
+### Named export with custom export names
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        loader: "css-loader",
+        options: {
+          modules: {
+            namedExport: true,
+            exportLocalsConvention: function (name) {
+              return name.replace(/-/g, "_");
+            },
+          },
+        },
+      },
+    ],
+  },
+};
+```
+
 ### 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 `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.
 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).
@@ -1371,50 +1681,51 @@ module.exports = {
       // --------
       // SCSS ALL EXCEPT MODULES
       {
-        test: /\.scss$/,
-        exclude: /\.module\.scss$/,
+        test: /\.scss$/i,
+        exclude: /\.module\.scss$/i,
         use: [
           {
-            loader: 'style-loader'
+            loader: "style-loader",
           },
           {
-            loader: 'css-loader',
+            loader: "css-loader",
             options: {
               importLoaders: 1,
               modules: {
-                compileType: 'icss'
-              }
-            }
+                mode: "icss",
+              },
+            },
           },
           {
-            loader: 'sass-loader'
+            loader: "sass-loader",
           },
         ],
       },
       // --------
       // SCSS MODULES
       {
-        test: /\.module\.scss$/,
+        test: /\.module\.scss$/i,
         use: [
           {
-            loader: 'style-loader'
+            loader: "style-loader",
           },
           {
-            loader: 'css-loader',
+            loader: "css-loader",
             options: {
               importLoaders: 1,
               modules: {
-                compileType: 'module'
-              }
-            }
+                mode: "local",
+              },
+            },
           },
           {
-            loader: 'sass-loader'
+            loader: "sass-loader",
           },
         ],
       },
       // --------
       // ...
+    ],
   },
 };
 ```