css-loader 3.6.0 → 4.2.0

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [4.2.0](https://github.com/webpack-contrib/css-loader/compare/v4.1.1...v4.2.0) (2020-07-31)
+
+
+### Features
+
+* add `module.type` option, the `icss` option is deprecated ([#1150](https://github.com/webpack-contrib/css-loader/issues/1150)) ([68f72af](https://github.com/webpack-contrib/css-loader/commit/68f72af2a09111f74dcacbf7af019fe7eb40cb6c))
+
+### [4.1.1](https://github.com/webpack-contrib/css-loader/compare/v4.1.0...v4.1.1) (2020-07-30)
+
+
+### Bug Fixes
+
+* remove unnecessary `console` call ([#1148](https://github.com/webpack-contrib/css-loader/issues/1148)) ([b1b90ca](https://github.com/webpack-contrib/css-loader/commit/b1b90caaea8eb045177749729340c7906454a84b))
+
+## [4.1.0](https://github.com/webpack-contrib/css-loader/compare/v4.0.0...v4.1.0) (2020-07-29)
+
+
+### Features
+
+* add `icss` option ([#1140](https://github.com/webpack-contrib/css-loader/issues/1140)) ([a8ec7da](https://github.com/webpack-contrib/css-loader/commit/a8ec7da42234e0b2eb061d2a920669940bcbdf05))
+* support absolute paths ([f9ba0ce](https://github.com/webpack-contrib/css-loader/commit/f9ba0ce11789770c4c9220478e9c98dbd432a5d6))
+
+
+### Bug Fixes
+
+* do not crash with `data` URLs ([#1142](https://github.com/webpack-contrib/css-loader/issues/1142)) ([91bc64b](https://github.com/webpack-contrib/css-loader/commit/91bc64b81abfeffd174639a8fdf2366412c11426))
+* performance ([#1144](https://github.com/webpack-contrib/css-loader/issues/1144)) ([4f1baa2](https://github.com/webpack-contrib/css-loader/commit/4f1baa211eb27b0b281ba9f262fa12e8aaefc0ba))
+
+## [4.0.0](https://github.com/webpack-contrib/css-loader/compare/v3.6.0...v4.0.0) (2020-07-25)
+
+
+### ⚠ BREAKING CHANGES
+
+* minimum required `Node.js` version is `10.13.0`
+* minimum required `webpack` version is `4.27.0`
+* the `esModule` option is `true` by default
+* default value of the `sourceMap` option depends on the `devtool` option
+* `icss` plugin disable by default, you need to setup the `modules` option to enable it
+* the `modules` option is `true` by default for all files matching `/\.module\.\w+$/i.test(filename)` regular expression, `module.auto` is `true` by default
+* the `modules.context` option was renamed to the `modules.localIdentContext` option
+* default the `modules.localIdentContext` value is `compiler.context` for the `module.getLocalIdent` option
+* the `modules.hashPrefix` option was renamed to the `modules.localIdentHashPrefix` option
+* the `localsConvention` option was moved and renamed to the `modules.exportLocalsConvention` option
+* the `getLocalIndent` option should be always `Function` and should always return `String` value
+* the `onlyLocals` option was moved and renamed to the `modules.exportOnlyLocals` option
+* function arguments of the `import` option were changed, it is now `function(url, media, resourcePath) {}`
+* inline syntax was changed, please write `~` before the file request, i.e. rewrite `url(~!!loader!package/img.png)` to `url(!!loader!~package/img.png)`
+
+
+### Features
+
+* `@value` supports importing `url()` ([#1126](https://github.com/webpack-contrib/css-loader/issues/1126)) ([7f49a0a](https://github.com/webpack-contrib/css-loader/commit/7f49a0a6047846bb2e432558365e19d4a0dfb366))
+* improve `url()` resolving algorithm ([bc19ddd](https://github.com/webpack-contrib/css-loader/commit/bc19ddd8779dafbc2a420870a3cb841041ce9c7c))
+* named export for locals ([#1108](https://github.com/webpack-contrib/css-loader/issues/1108)) ([d139ec1](https://github.com/webpack-contrib/css-loader/commit/d139ec1d763f9944550b31f2a75183e488dd1224))
+* respected the `style` field from package.json ([#1099](https://github.com/webpack-contrib/css-loader/issues/1099)) ([edf5347](https://github.com/webpack-contrib/css-loader/commit/edf5347e4203a62e50b87248a83da198afdc6eba))
+* support `file:` protocol ([5604205](https://github.com/webpack-contrib/css-loader/commit/560420567eb0e1a635648b7f4ff0365db475384c))
+* support server relative URLs
+
+### Bug Fixes
+
+* resolution algorithm, you don't need `~` inside packages in `node_modules` ([76f1480](https://github.com/webpack-contrib/css-loader/commit/76f1480b14265369ac5dc8dbbce467cfb8e814c5))
+
+
 ## [3.6.0](https://github.com/webpack-contrib/css-loader/compare/v3.5.3...v3.6.0) (2020-06-13)
 
 

package/README.md

@@ -109,16 +109,14 @@ module.exports = {
 
 ## 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}` | `false`  | Enables/Disables CSS Modules and their configuration                   |
-|        **[`sourceMap`](#sourcemap)**        |         `{Boolean}`         | `false`  | Enables/Disables generation of source maps                             |
-|    **[`importLoaders`](#importloaders)**    |         `{Number}`          |   `0`    | Enables/Disables or setups number of loaders applied before CSS loader |
-| **[`localsConvention`](#localsconvention)** |         `{String}`          | `'asIs'` | Style of exported classnames                                           |
-|       **[`onlyLocals`](#onlylocals)**       |         `{Boolean}`         | `false`  | Export only locals                                                     |
-|         **[`esModule`](#esmodule)**         |         `{Boolean}`         | `false`  | Use ES modules syntax                                                  |
+|                 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                                                  |
 
 ### `url`
 
@@ -126,7 +124,7 @@ Type: `Boolean|Function`
 Default: `true`
 
 Enables/Disables `url`/`image-set` functions handling.
-Control `url()` resolving. Absolute URLs and root-relative URLs are not resolving.
+Control `url()` resolving. Absolute URLs are not resolving.
 
 Examples resolutions:
 
@@ -264,13 +262,11 @@ module.exports = {
         test: /\.css$/i,
         loader: 'css-loader',
         options: {
-          import: (parsedImport, resourcePath) => {
-            // parsedImport.url - url of `@import`
-            // parsedImport.media - media query of `@import`
+          import: (url, media, resourcePath) => {
             // resourcePath - path to css file
 
             // Don't handle `style.css` import
-            if (parsedImport.url.includes('style.css')) {
+            if (url.includes('style.css')) {
               return false;
             }
 
@@ -286,7 +282,7 @@ module.exports = {
 ### `modules`
 
 Type: `Boolean|String|Object`
-Default: `false`
+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)
 
 Enables/Disables CSS Modules and their configuration.
 
@@ -415,6 +411,8 @@ exports.locals = {
 
 To import a local classname from another module.
 
+> i We strongly recommend that you specify the extension when importing a file, since it is possible to import a file with any extension and it is not known in advance which file to use.
+
 ```css
 :local(.continueButton) {
   composes: button from 'library/button.css';
@@ -527,11 +525,48 @@ module.exports = {
         loader: 'css-loader',
         options: {
           modules: {
+            compileType: 'module',
             mode: 'local',
+            auto: true,
             exportGlobals: true,
             localIdentName: '[path][name]__[local]--[hash:base64:5]',
             context: path.resolve(__dirname, 'src'),
-            hashPrefix: 'my-custom-hash',
+            localIdentHashPrefix: 'my-custom-hash',
+            namedExport: true,
+            exportLocalsConvention: 'camelCase',
+            exportOnlyLocals: false,
+          },
+        },
+      },
+    ],
+  },
+};
+```
+
+##### `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',
           },
         },
       },
@@ -543,9 +578,9 @@ module.exports = {
 ##### `auto`
 
 Type: `Boolean|RegExp|Function`
-Default: `'undefined'`
+Default: `'true'`
 
-Allows auto enable css modules based on filename.
+Allows auto enable CSS modules based on filename.
 
 ###### `Boolean`
 
@@ -690,39 +725,12 @@ module.exports = {
 };
 ```
 
-##### `exportGlobals`
-
-Type: `Boolean`
-Default: `false`
-
-Allow `css-loader` to export names from global class or id, so you can use that as local name.
-
-**webpack.config.js**
-
-```js
-module.exports = {
-  module: {
-    rules: [
-      {
-        test: /\.css$/i,
-        loader: 'css-loader',
-        options: {
-          modules: {
-            exportGlobals: true,
-          },
-        },
-      },
-    ],
-  },
-};
-```
-
 ##### `localIdentName`
 
 Type: `String`
 Default: `'[hash:base64]'`
 
-You can configure the generated ident with the `localIdentName` query parameter.
+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.
 
 Recommendations:
@@ -754,13 +762,12 @@ module.exports = {
 };
 ```
 
-##### `context`
+##### `localIdentContext`
 
 Type: `String`
-Default: `undefined`
+Default: `compiler.context`
 
-Allow to redefine basic loader context for local ident name.
-By default we use `rootContext` of loader.
+Allows to redefine basic loader context for local ident name.
 
 **webpack.config.js**
 
@@ -782,12 +789,12 @@ module.exports = {
 };
 ```
 
-##### `hashPrefix`
+##### `localIdentHashPrefix`
 
 Type: `String`
 Default: `undefined`
 
-Allow to add custom hash to generate more unique classes.
+Allows to add custom hash to generate more unique classes.
 
 **webpack.config.js**
 
@@ -800,7 +807,7 @@ module.exports = {
         loader: 'css-loader',
         options: {
           modules: {
-            hashPrefix: 'hash',
+            localIdentHashPrefix: 'hash',
           },
         },
       },
@@ -809,14 +816,11 @@ module.exports = {
 };
 ```
 
-##### `getLocalIdent`
+##### `localIdentRegExp`
 
-Type: `Function`
+Type: `String|RegExp`
 Default: `undefined`
 
-You can also specify the absolute path to your custom `getLocalIdent` function to generate classname based on a different schema.
-By default we use built-in function to generate a classname.
-
 **webpack.config.js**
 
 ```js
@@ -828,9 +832,7 @@ module.exports = {
         loader: 'css-loader',
         options: {
           modules: {
-            getLocalIdent: (context, localIdentName, localName, options) => {
-              return 'whatever_random_class_name';
-            },
+            localIdentRegExp: /page-(.*)\.css/i,
           },
         },
       },
@@ -839,11 +841,14 @@ module.exports = {
 };
 ```
 
-##### `localIdentRegExp`
+##### `getLocalIdent`
 
-Type: `String|RegExp`
+Type: `Function`
 Default: `undefined`
 
+Allows to specify a function to generate the classname.
+By default we use built-in function to generate a classname.
+
 **webpack.config.js**
 
 ```js
@@ -855,7 +860,9 @@ module.exports = {
         loader: 'css-loader',
         options: {
           modules: {
-            localIdentRegExp: /page-(.*)\.css/i,
+            getLocalIdent: (context, localIdentName, localName, options) => {
+              return 'whatever_random_class_name';
+            },
           },
         },
       },
@@ -864,16 +871,37 @@ module.exports = {
 };
 ```
 
-### `sourceMap`
+##### `namedExport`
 
 Type: `Boolean`
 Default: `false`
 
-Enables/Disables generation of source maps.
+Enables/disables ES modules named export for locals.
+
+> ⚠ Names of locals are converted to camelcase, i.e. the `exportLocalsConvention` option has `camelCaseOnly` value by default.
 
-To include source maps set the `sourceMap` option.
+> ⚠ It is not allowed to use JavaScript reserved words in css class names.
 
-They are not enabled by default because they expose a runtime overhead and increase in bundle size (JS source maps do not).
+**styles.css**
+
+```css
+.foo-baz {
+  color: red;
+}
+.bar {
+  color: blue;
+}
+```
+
+**index.js**
+
+```js
+import { fooBaz, bar } from './styles.css';
+
+console.log(fooBaz, bar);
+```
+
+You can enable a ES module named export using:
 
 **webpack.config.js**
 
@@ -885,7 +913,10 @@ module.exports = {
         test: /\.css$/i,
         loader: 'css-loader',
         options: {
-          sourceMap: true,
+          esModule: true,
+          modules: {
+            namedExport: true,
+          },
         },
       },
     ],
@@ -893,14 +924,12 @@ module.exports = {
 };
 ```
 
-### `importLoaders`
-
-Type: `Number`
-Default: `0`
+##### `exportGlobals`
 
-Enables/Disables or setups number of loaders applied before CSS loader.
+Type: `Boolean`
+Default: `false`
 
-The option `importLoaders` allows you to configure how many loaders before `css-loader` should be applied to `@import`ed resources.
+Allow `css-loader` to export names from global class or id, so you can use that as local name.
 
 **webpack.config.js**
 
@@ -910,37 +939,29 @@ module.exports = {
     rules: [
       {
         test: /\.css$/i,
-        use: [
-          'style-loader',
-          {
-            loader: 'css-loader',
-            options: {
-              importLoaders: 2,
-              // 0 => no loaders (default);
-              // 1 => postcss-loader;
-              // 2 => postcss-loader, sass-loader
-            },
+        loader: 'css-loader',
+        options: {
+          modules: {
+            exportGlobals: true,
           },
-          'postcss-loader',
-          'sass-loader',
-        ],
+        },
       },
     ],
   },
 };
 ```
 
-This may change in the future when the module system (i. e. webpack) supports loader matching by origin.
-
-### `localsConvention`
+##### `exportlocalsConvention`
 
 Type: `String`
-Default: `'asIs'`
+Default: based on the `modules.namedExport` option value, if `true` - `camelCaseOnly`, otherwise `asIs`
 
-Style of exported classnames.
+Style of exported class names.
 
 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`.
+
 |         Name          |    Type    | Description                                                                                      |
 | :-------------------: | :--------: | :----------------------------------------------------------------------------------------------- |
 |     **`'asIs'`**      | `{String}` | Class names will be exported as is.                                                              |
@@ -972,6 +993,7 @@ module.exports = {
         test: /\.css$/i,
         loader: 'css-loader',
         options: {
+          mode: 'local',
           localsConvention: 'camelCase',
         },
       },
@@ -980,7 +1002,7 @@ module.exports = {
 };
 ```
 
-### `onlyLocals`
+##### `exportOnlyLocals`
 
 Type: `Boolean`
 Default: `false`
@@ -1001,7 +1023,9 @@ module.exports = {
         test: /\.css$/i,
         loader: 'css-loader',
         options: {
-          onlyLocals: true,
+          modules: {
+            exportOnlyLocals: true,
+          },
         },
       },
     ],
@@ -1009,15 +1033,79 @@ module.exports = {
 };
 ```
 
+### `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,
+        },
+      },
+    ],
+  },
+};
+```
+
+### `importLoaders`
+
+Type: `Number`
+Default: `0`
+
+Enables/Disables or setups number of loaders applied before CSS loader.
+
+The option `importLoaders` allows you to configure how many loaders before `css-loader` should be applied to `@import`ed resources.
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        use: [
+          'style-loader',
+          {
+            loader: 'css-loader',
+            options: {
+              importLoaders: 2,
+              // 0 => no loaders (default);
+              // 1 => postcss-loader;
+              // 2 => postcss-loader, sass-loader
+            },
+          },
+          'postcss-loader',
+          'sass-loader',
+        ],
+      },
+    ],
+  },
+};
+```
+
+This may change in the future when the module system (i. e. webpack) supports loader matching by origin.
+
 ### `esModule`
 
 Type: `Boolean`
-Default: `false`
+Default: `true`
 
-By default, `css-loader` generates JS modules that use the CommonJS modules syntax.
+By default, `css-loader` generates JS modules that use the ES modules syntax.
 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/).
 
-You can enable a ES module syntax using:
+You can enable a CommonJS modules syntax using:
 
 **webpack.config.js**
 
@@ -1029,7 +1117,7 @@ module.exports = {
         test: /\.css$/i,
         loader: 'css-loader',
         options: {
-          esModule: true,
+          esModule: false,
         },
       },
     ],
@@ -1084,7 +1172,6 @@ module.exports = {
   module: {
     rules: [
       {
-        // For CSS modules
         // For pure CSS - /\.css$/i,
         // For Sass/SCSS - /\.((c|sa|sc)ss)$/i,
         // For Less - /\.((c|le)ss)$/i,
@@ -1106,9 +1193,7 @@ module.exports = {
             options: { plugins: () => [postcssPresetEnv({ stage: 0 })] },
           },
           // Can be `less-loader`
-          // The `test` property should be `\.less/i`
           {
-            test: /\.s[ac]ss$/i,
             loader: 'sass-loader',
           },
         ],
@@ -1125,6 +1210,39 @@ module.exports = {
 };
 ```
 
+### Resolve unresolved URLs using an alias
+
+**index.css**
+
+```css
+.class {
+  background: url(/assets/unresolved/img.png);
+}
+```
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        use: ['style-loader', 'css-loader'],
+      },
+    ],
+  },
+  resolve: {
+    alias: {
+      '/assets/unresolved/img.png': path.resolve(
+        __dirname,
+        'assets/real-path-to-img/img.png'
+      ),
+    },
+  },
+};
+```
+
 ## Contributing
 
 Please take a moment to read our contributing guidelines if you haven't yet done so.