feat: add module.type option, the icss option is deprecated (#1150)

Author: evilebottnawi

README.md

@@ -109,15 +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}` |                   `{auto: true}`                   | Enables/Disables CSS Modules and their configuration                   |
-|          **[`icss`](#icss)**          |         `{Boolean}`         | `true` if `modules` are enabled, `false` otherwise | Enables/Disables Interoperable CSS                                     |
-|     **[`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\|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`
 
@@ -526,6 +525,7 @@ module.exports = {
         loader: 'css-loader',
         options: {
           modules: {
+            compileType: 'module',
             mode: 'local',
             auto: true,
             exportGlobals: true,
@@ -543,6 +543,38 @@ 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`
@@ -1001,33 +1033,6 @@ module.exports = {
 };
 ```
 
-### `icss`
-
-Type: Boolean Default: `true` if `modules` are enabled, false otherwise
-
-Enables/disables handling of the low level "Interoperable CSS" format for declaring
-import and export dependencies between CSS and other languages. ICSS enables
-CSS Module support, and is enabled automatically when `modules` are enabled. It
-can also be enabled independently to allow other loaders to handle processing CSS modules.
-
-**webpack.config.js**
-
-```js
-module.exports = {
-  module: {
-    rules: [
-      {
-        test: /\.css$/i,
-        loader: 'css-loader',
-        options: {
-          icss: true,
-        },
-      },
-    ],
-  },
-};
-```
-
 ### `sourceMap`
 
 Type: `Boolean`

src/index.js

@@ -17,6 +17,7 @@ import {
   shouldUseModulesPlugins,
   shouldUseImportPlugin,
   shouldUseURLPlugin,
+  shouldUseIcssPlugin,
   getPreRequester,
   getExportCode,
   getFilter,
@@ -51,9 +52,7 @@ export default async function loader(content, map, meta) {
   const replacements = [];
   const exports = [];
 
-  const needUseModulesPlugins = shouldUseModulesPlugins(options);
-
-  if (needUseModulesPlugins) {
+  if (shouldUseModulesPlugins(options)) {
     plugins.push(...getModulesPlugins(options, this));
   }
 
@@ -112,7 +111,7 @@ export default async function loader(content, map, meta) {
   const icssPluginImports = [];
   const icssPluginApi = [];
 
-  if (needUseModulesPlugins || options.icss) {
+  if (shouldUseIcssPlugin(options)) {
     const icssResolver = this.getResolve({
       conditionNames: ['style'],
       extensions: [],

src/options.json

@@ -36,6 +36,10 @@
           "type": "object",
           "additionalProperties": false,
           "properties": {
+            "compileType": {
+              "description": "Controls the extent to which css-loader will process module code (https://github.com/webpack-contrib/css-loader#type)",
+              "enum": ["module", "icss"]
+            },
             "auto": {
               "description": "Allows auto enable CSS modules based on filename (https://github.com/webpack-contrib/css-loader#auto).",
               "anyOf": [

src/utils.js

@@ -125,6 +125,7 @@ function getModulesOptions(rawOptions, loaderContext) {
   }
 
   let modulesOptions = {
+    compileType: rawOptions.icss ? 'icss' : 'module',
     auto: true,
     mode: 'local',
     exportGlobals: false,
@@ -201,12 +202,22 @@ function getModulesOptions(rawOptions, loaderContext) {
 }
 
 function normalizeOptions(rawOptions, loaderContext) {
+  if (rawOptions.icss) {
+    loaderContext.emitWarning(
+      new Error(
+        'The "icss" option is deprecated, use "modules.compileType: "icss"" instead'
+      )
+    );
+  }
+
   const modulesOptions = getModulesOptions(rawOptions, loaderContext);
+
   return {
     url: typeof rawOptions.url === 'undefined' ? true : rawOptions.url,
     import: typeof rawOptions.import === 'undefined' ? true : rawOptions.import,
     modules: modulesOptions,
-    icss: modulesOptions ? true : rawOptions.icss,
+    // TODO remove in the next major release
+    icss: typeof rawOptions.icss === 'undefined' ? false : rawOptions.icss,
     sourceMap:
       typeof rawOptions.sourceMap === 'boolean'
         ? rawOptions.sourceMap
@@ -242,7 +253,11 @@ function shouldUseURLPlugin(options) {
 }
 
 function shouldUseModulesPlugins(options) {
-  return Boolean(options.modules);
+  return options.modules.compileType === 'module';
+}
+
+function shouldUseIcssPlugin(options) {
+  return options.icss === true || Boolean(options.modules);
 }
 
 function getModulesPlugins(options, loaderContext) {
@@ -545,6 +560,7 @@ export {
   shouldUseModulesPlugins,
   shouldUseImportPlugin,
   shouldUseURLPlugin,
+  shouldUseIcssPlugin,
   normalizeUrl,
   requestify,
   getFilter,