docs: asset modules (#1254)

Author: alexander-akait

README.md

@@ -50,6 +50,8 @@ 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.
@@ -1134,6 +1136,30 @@ module.exports = {
 
 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
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        use: ["style-loader", "css-loader"],
+      },
+      {
+        test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)$/i,
+        // More information here https://webpack.js.org/guides/asset-modules/
+        type: "asset",
+      },
+    ],
+  },
+};
+```
+
+**For webpack v4:**
+
 **webpack.config.js**
 
 ```js
@@ -1187,8 +1213,6 @@ module.exports = {
               // 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 },
             },
           },
           {
@@ -1201,13 +1225,20 @@ module.exports = {
           },
         ],
       },
+      // 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,
+      //  },
+      // },
     ],
   },
 };

package.json

@@ -92,7 +92,7 @@
     "stylus": "^0.54.8",
     "stylus-loader": "^4.3.0",
     "url-loader": "^4.1.1",
-    "webpack": "^5.4.0"
+    "webpack": "^5.20.1"
   },
   "keywords": [
     "webpack",

test/__snapshots__/url-option.test.js.snap

@@ -306,8 +306,9 @@ a {
 .class.class.class {
   background: url('./img\
 (img.png');
-  background: url('./img\(img.png');
-  background: url('./img\
+  background: url('./img\
+(img.png');
+  background: url('./img\
 (img.png');
   background: url('./img\
 \
@@ -349,9 +350,11 @@ a {
   background: url(./img\'\28%29\ img.png);
 }
 
-.qqq {
-  background: url('!!../../helpers/url-loader.js?esModule=false!~package/img.png')
-}
+/* TODO need refactor tests after drop webpack@4 due inline syntax `!../../helpers/url-loader.js?esModule=false!~package/img.png` */
+/* We need to use `resourceQuery: /inline/` */
+/*.qqq {*/
+/*  background: url('!!../../helpers/url-loader.js?esModule=false!~package/img.png')*/
+/*}*/
 
 .class {
   /* Should be one import */

test/fixtures/url/url.css

@@ -1,6 +1,8 @@
 import fs from "fs";
 import path from "path";
 
+import webpack from "webpack";
+
 import {
   compile,
   getCompiler,
@@ -10,6 +12,8 @@ import {
   getWarnings,
 } from "./helpers/index";
 
+const isWebpack5 = webpack.version.startsWith(5);
+
 describe('"url" option', () => {
   it("should work when not specified", async () => {
     const compiler = getCompiler("./url/url.js");
@@ -140,6 +144,137 @@ describe('"url" option', () => {
     expect(getErrors(stats)).toMatchSnapshot("errors");
   });
 
+  it("should work with the 'asset' type of asset modules", async () => {
+    const compiler = getCompiler(
+      "./url/url.js",
+      {},
+      {
+        module: {
+          rules: [
+            {
+              test: /\.css$/i,
+              use: [
+                {
+                  loader: path.resolve(__dirname, "../src"),
+                  options: {},
+                },
+              ],
+            },
+            isWebpack5
+              ? {
+                  test: /\.(png|jpg|gif|svg|eot|ttf|woff|woff2)$/i,
+                  type: "asset",
+                  generator: {
+                    filename: "[name][ext]",
+                  },
+                }
+              : {
+                  test: /\.(png|jpg|gif|svg|eot|ttf|woff|woff2)$/i,
+                  loader: "url-loader",
+                  options: {
+                    limit: 8096,
+                    name: "[name].[ext]",
+                  },
+                },
+          ],
+        },
+      }
+    );
+    const stats = await compile(compiler);
+
+    expect(getModuleSource("./url/url.css", stats)).toMatchSnapshot("module");
+    expect(getExecutedCode("main.bundle.js", compiler, stats)).toMatchSnapshot(
+      "result"
+    );
+    expect(getWarnings(stats)).toMatchSnapshot("warnings");
+    expect(getErrors(stats)).toMatchSnapshot("errors");
+  });
+
+  it("should work with the 'asset/resource' type of asset modules", async () => {
+    const compiler = getCompiler(
+      "./url/url.js",
+      {},
+      {
+        module: {
+          rules: [
+            {
+              test: /\.css$/i,
+              use: [
+                {
+                  loader: path.resolve(__dirname, "../src"),
+                  options: {},
+                },
+              ],
+            },
+            isWebpack5
+              ? {
+                  test: /\.(png|jpg|gif|svg|eot|ttf|woff|woff2)$/i,
+                  type: "asset",
+                  generator: {
+                    filename: "[name][ext]",
+                  },
+                }
+              : {
+                  test: /\.(png|jpg|gif|svg|eot|ttf|woff|woff2)$/i,
+                  loader: "url-loader",
+                  options: {
+                    limit: 8096,
+                    name: "[name].[ext]",
+                  },
+                },
+          ],
+        },
+      }
+    );
+    const stats = await compile(compiler);
+
+    expect(getModuleSource("./url/url.css", stats)).toMatchSnapshot("module");
+    expect(getExecutedCode("main.bundle.js", compiler, stats)).toMatchSnapshot(
+      "result"
+    );
+    expect(getWarnings(stats)).toMatchSnapshot("warnings");
+    expect(getErrors(stats)).toMatchSnapshot("errors");
+  });
+
+  it("should work with the 'asset/inline' type of asset modules", async () => {
+    const compiler = getCompiler(
+      "./url/url.js",
+      {},
+      {
+        module: {
+          rules: [
+            {
+              test: /\.css$/i,
+              use: [
+                {
+                  loader: path.resolve(__dirname, "../src"),
+                  options: {},
+                },
+              ],
+            },
+            isWebpack5
+              ? {
+                  test: /\.(png|jpg|gif|svg|eot|ttf|woff|woff2)$/i,
+                  type: "asset/inline",
+                }
+              : {
+                  test: /\.(png|jpg|gif|svg|eot|ttf|woff|woff2)$/i,
+                  loader: "url-loader",
+                },
+          ],
+        },
+      }
+    );
+    const stats = await compile(compiler);
+
+    expect(getModuleSource("./url/url.css", stats)).toMatchSnapshot("module");
+    expect(getExecutedCode("main.bundle.js", compiler, stats)).toMatchSnapshot(
+      "result"
+    );
+    expect(getWarnings(stats)).toMatchSnapshot("warnings");
+    expect(getErrors(stats)).toMatchSnapshot("errors");
+  });
+
   it("should throw an error on unresolved import", async () => {
     const compiler = getCompiler("./url/url-unresolved.js");
     const stats = await compile(compiler);