css-loader 6.1.0 → 6.5.0

package/README.md

@@ -54,69 +54,19 @@ module.exports = {
 
 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\|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                                                                                                    |
+|                 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`
 
@@ -745,13 +695,14 @@ For more information on options see:
 
 Supported template strings:
 
-- [name] the basename of the resource
-- [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.
+- `[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:
 
@@ -1031,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`
@@ -1060,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`.
@@ -1110,6 +1066,58 @@ module.exports = {
 };
 ```
 
+###### `Function`
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        loader: "css-loader",
+        options: {
+          modules: {
+            exportLocalsConvention: function (name) {
+              return name.replace(/-/g, "_");
+            },
+          },
+        },
+      },
+    ],
+  },
+};
+```
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        loader: "css-loader",
+        options: {
+          modules: {
+            exportLocalsConvention: function (name) {
+              return [
+                name.replace(/-/g, "_"),
+                // dashesCamelCase
+                name.replace(/-+(\w)/g, (match, firstLetter) =>
+                  firstLetter.toUpperCase()
+                ),
+              ];
+            },
+          },
+        },
+      },
+    ],
+  },
+};
+```
+
 ##### `exportOnlyLocals`
 
 Type: `Boolean`
@@ -1233,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
@@ -1253,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",
@@ -1434,6 +1639,31 @@ 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 `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.
@@ -1451,8 +1681,8 @@ module.exports = {
       // --------
       // SCSS ALL EXCEPT MODULES
       {
-        test: /\.scss$/,
-        exclude: /\.module\.scss$/,
+        test: /\.scss$/i,
+        exclude: /\.module\.scss$/i,
         use: [
           {
             loader: "style-loader",
@@ -1474,7 +1704,7 @@ module.exports = {
       // --------
       // SCSS MODULES
       {
-        test: /\.module\.scss$/,
+        test: /\.module\.scss$/i,
         use: [
           {
             loader: "style-loader",

package/dist/index.js

@@ -49,24 +49,23 @@ async function loader(content, map, meta) {
 
   const importPluginImports = [];
   const importPluginApi = [];
+  let isSupportAbsoluteURL = false; // TODO enable by default in the next major release
+
+  if (this._compilation && this._compilation.options && this._compilation.options.experiments && this._compilation.options.experiments.buildHttp) {
+    isSupportAbsoluteURL = true;
+  }
+
+  const isSupportDataURL = options.esModule && Boolean("fsStartTime" in this._compiler);
 
   if ((0, _utils.shouldUseImportPlugin)(options)) {
-    const resolver = this.getResolve({
-      dependencyType: "css",
-      conditionNames: ["style"],
-      mainFields: ["css", "style", "main", "..."],
-      mainFiles: ["index", "..."],
-      extensions: [".css", "..."],
-      preferRelative: true
-    });
     plugins.push((0, _plugins.importParser)({
+      isSupportAbsoluteURL: false,
+      isSupportDataURL: false,
+      isCSSStyleSheet: options.exportType === "css-style-sheet",
+      loaderContext: this,
       imports: importPluginImports,
       api: importPluginApi,
-      context: this.context,
-      rootContext: this.rootContext,
-      resourcePath: this.resourcePath,
-      filter: (0, _utils.getFilter)(options.import.filter, this.resourcePath),
-      resolver,
+      filter: options.import.filter,
       urlHandler: url => (0, _utils.stringifyRequest)(this, (0, _utils.combineRequests)((0, _utils.getPreRequester)(this)(options.importLoaders), url))
     }));
   }
@@ -75,22 +74,21 @@ async function loader(content, map, meta) {
 
   if ((0, _utils.shouldUseURLPlugin)(options)) {
     const needToResolveURL = !options.esModule;
-    const isSupportDataURLInNewURL = options.esModule && Boolean("fsStartTime" in this._compiler);
     plugins.push((0, _plugins.urlParser)({
+      isSupportAbsoluteURL,
+      isSupportDataURL,
       imports: urlPluginImports,
       replacements,
       context: this.context,
       rootContext: this.rootContext,
       filter: (0, _utils.getFilter)(options.url.filter, this.resourcePath),
-      needToResolveURL,
       resolver: needToResolveURL ? this.getResolve({
         mainFiles: [],
         extensions: []
       }) : // eslint-disable-next-line no-undefined
       undefined,
-      urlHandler: url => (0, _utils.stringifyRequest)(this, url),
-      // Support data urls as input in new URL added in webpack@5.38.0
-      isSupportDataURLInNewURL
+      urlHandler: url => (0, _utils.stringifyRequest)(this, url) // Support data urls as input in new URL added in webpack@5.38.0
+
     }));
   }
 
@@ -99,22 +97,12 @@ async function loader(content, map, meta) {
   const needToUseIcssPlugin = (0, _utils.shouldUseIcssPlugin)(options);
 
   if (needToUseIcssPlugin) {
-    const icssResolver = this.getResolve({
-      dependencyType: "icss",
-      conditionNames: ["style"],
-      extensions: ["..."],
-      mainFields: ["css", "style", "main", "..."],
-      mainFiles: ["index", "..."],
-      preferRelative: true
-    });
     plugins.push((0, _plugins.icssParser)({
+      loaderContext: this,
       imports: icssPluginImports,
       api: icssPluginApi,
       replacements,
       exports,
-      context: this.context,
-      rootContext: this.rootContext,
-      resolver: icssResolver,
       urlHandler: url => (0, _utils.stringifyRequest)(this, (0, _utils.combineRequests)((0, _utils.getPreRequester)(this)(options.importLoaders), url))
     }));
   } // Reuse CSS AST (PostCSS AST e.g 'postcss-loader') to avoid reparsing
@@ -172,15 +160,27 @@ async function loader(content, map, meta) {
 
     if (options.sourceMap) {
       imports.unshift({
-        type: "api_sourcemap_import",
         importName: "___CSS_LOADER_API_SOURCEMAP_IMPORT___",
-        url: (0, _utils.stringifyRequest)(this, require.resolve("./runtime/cssWithMappingToString"))
+        url: (0, _utils.stringifyRequest)(this, require.resolve("./runtime/sourceMaps"))
+      });
+    } else {
+      imports.unshift({
+        importName: "___CSS_LOADER_API_NO_SOURCEMAP_IMPORT___",
+        url: (0, _utils.stringifyRequest)(this, require.resolve("./runtime/noSourceMaps"))
       });
     }
   }
 
   const importCode = (0, _utils.getImportCode)(imports, options);
-  const moduleCode = (0, _utils.getModuleCode)(result, api, replacements, options, this);
+  let moduleCode;
+
+  try {
+    moduleCode = (0, _utils.getModuleCode)(result, api, replacements, options, this);
+  } catch (error) {
+    callback(error);
+    return;
+  }
+
   const exportCode = (0, _utils.getExportCode)(exports, replacements, needToUseIcssPlugin, options);
   callback(null, `${importCode}${moduleCode}${exportCode}`);
 }

package/dist/options.json

@@ -145,12 +145,19 @@
             "exportLocalsConvention": {
               "description": "Style of exported classnames.",
               "link": "https://github.com/webpack-contrib/css-loader#localsconvention",
-              "enum": [
-                "asIs",
-                "camelCase",
-                "camelCaseOnly",
-                "dashes",
-                "dashesOnly"
+              "anyOf": [
+                {
+                  "enum": [
+                    "asIs",
+                    "camelCase",
+                    "camelCaseOnly",
+                    "dashes",
+                    "dashesOnly"
+                  ]
+                },
+                {
+                  "instanceof": "Function"
+                }
               ]
             },
             "exportOnlyLocals": {
@@ -186,6 +193,11 @@
       "description": "Use the ES modules syntax.",
       "link": "https://github.com/webpack-contrib/css-loader#esmodule",
       "type": "boolean"
+    },
+    "exportType": {
+      "description": "Allows exporting styles as array with modules, string or constructable stylesheet (i.e. `CSSStyleSheet`).",
+      "link": "https://github.com/webpack-contrib/css-loader#exporttype",
+      "enum": ["array", "string", "css-style-sheet"]
     }
   },
   "type": "object"

package/dist/plugins/index.js

@@ -3,16 +3,16 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-Object.defineProperty(exports, "importParser", {
+Object.defineProperty(exports, "icssParser", {
   enumerable: true,
   get: function () {
-    return _postcssImportParser.default;
+    return _postcssIcssParser.default;
   }
 });
-Object.defineProperty(exports, "icssParser", {
+Object.defineProperty(exports, "importParser", {
   enumerable: true,
   get: function () {
-    return _postcssIcssParser.default;
+    return _postcssImportParser.default;
   }
 });
 Object.defineProperty(exports, "urlParser", {

package/dist/plugins/postcss-icss-parser.js

@@ -20,7 +20,18 @@ const plugin = (options = {}) => {
         icssExports
       } = (0, _icssUtils.extractICSS)(root);
       const imports = new Map();
-      const tasks = []; // eslint-disable-next-line guard-for-in
+      const tasks = [];
+      const {
+        loaderContext
+      } = options;
+      const resolver = loaderContext.getResolve({
+        dependencyType: "icss",
+        conditionNames: ["style"],
+        extensions: ["..."],
+        mainFields: ["css", "style", "main", "..."],
+        mainFiles: ["index", "..."],
+        preferRelative: true
+      }); // eslint-disable-next-line guard-for-in
 
       for (const url in icssImports) {
         const tokens = icssImports[url];
@@ -39,14 +50,10 @@ const plugin = (options = {}) => {
           prefix = queryParts.join("!");
         }
 
-        const request = (0, _utils.requestify)((0, _utils.normalizeUrl)(normalizedUrl, true), options.rootContext);
+        const request = (0, _utils.requestify)((0, _utils.normalizeUrl)(normalizedUrl, true), loaderContext.rootContext);
 
         const doResolve = async () => {
-          const {
-            resolver,
-            context
-          } = options;
-          const resolvedUrl = await (0, _utils.resolveRequests)(resolver, context, [...new Set([normalizedUrl, request])]);
+          const resolvedUrl = await (0, _utils.resolveRequests)(resolver, loaderContext.context, [...new Set([normalizedUrl, request])]);
 
           if (!resolvedUrl) {
             return;