feat: add support for the ?inline query to load assets as data URL

Author: webdiscus

CHANGELOG.md

@@ -1,4 +1,22 @@
-# Change log
+# Changelog
+
+## 4.12.0 (2025-01-12)
+
+- feat(release): add support for the `?inline` query to load assets as data URL
+- test: add tests for `?inline` query
+- docs: update readme for new feature
+
+## 4.12.0-beta.1 (2025-01-07)
+
+- feat: add support for the `?inline` query to load assets as data URL in HTML, CSS and JS.
+  By using the `?inline` query, the following configuration can now be omitted:
+  ```js
+  {
+    // since v4.12 is not need anymore
+    resourceQuery: /inline/,
+    type: 'asset/inline',
+  },
+  ```
 
 ## 4.12.0-beta.0 (2025-01-06)
 

README.md

@@ -556,8 +556,8 @@ See [boilerplate](https://github.com/webdiscus/webpack-html-scss-boilerplate)
    - [How to inline CSS in HTML](#recipe-inline-css)
    - [How to inline JS in HTML](#recipe-inline-js)
    - [How to inline SVG, PNG images in HTML](#recipe-inline-image)
+   - [How to import SVG in JS w/o `svg-url-loader`](#recipe-import-svg) (as filename or as data URL)
    - [How to inline all resources into single HTML file](#recipe-inline-all-assets-to-html)
-   - [How to import SVG in JS w/o `svg-url-loader`](#recipe-import-svg) (as filename, as data URL, as raw content)
    - [How to resolve source assets in an attribute containing JSON value](#recipe-resolve-attr-json)
    - [How to resolve source image in the `style` attribute](#recipe-resolve-attr-style-url)
    - [How to resolve source image in the `href` attribute](#recipe-resolve-attr-href-a-image) (`<a href="image.jpg">`)
@@ -1019,7 +1019,7 @@ class MyPlugin {
 
     const { pluginName } = this;
     const { webpack } = compiler; // instance of the Webpack
-    const fs = compiler.inputFileSystem.fileSystem; // instance of the Webpack FyleSystem
+    const fs = compiler.inputFileSystem.fileSystem; // instance of the Webpack FileSystem
 
     // start your plugin from the webpack compilation hook
     compiler.hooks.compilation.tap(pluginName, (compilation) => {
@@ -5579,7 +5579,7 @@ The generated HTML contains inline JS already compiled via Webpack:
 
 You can inline the images in two ways:
 
-- force inline image using `?inline` query
+- force inline image using `?inline` query (works in HTML, CSS, [JS](#recipe-import-svg))
 - auto inline by image size
 
 Add to Webpack config the rule:
@@ -5589,25 +5589,18 @@ module: {
   rules: [
     {
       test: /\.(png|jpe?g|svg|webp|ico)$/i,
-      oneOf: [
-        // inline image using `?inline` query
-        {
-          resourceQuery: /inline/,
-          type: 'asset/inline',
-        },
-        // auto inline by image size
-        {
-          type: 'asset',
-          parser: {
-            dataUrlCondition: {
-              maxSize: 1024,
-            },
-          },
-          generator: {
-            filename: 'assets/img/[name].[hash:8][ext]',
+      // auto inline by image size
+      {
+        type: 'asset',
+        parser: {
+          dataUrlCondition: {
+            maxSize: 1024,
           },
         },
-      ],
+        generator: {
+          filename: 'assets/img/[name].[hash:8][ext]',
+        },
+      },
     },
   ],
 }
@@ -5619,63 +5612,6 @@ The plugin automatically inlines images smaller then `maxSize`.
 
 #### [↑ back to contents](#contents)
 
-<a id="recipe-inline-all-assets-to-html" name="recipe-inline-all-assets-to-html"></a>
-
-## How to inline all resources into single HTML file
-
-The bundler plugin can generate a single HTML file included all embedded dependencies
-such as JS, CSS, fonts, images (PNG, SVG, etc..).
-
-The fonts and images used in CSS will be inlined into CSS.
-The generated CSS including inlined images will be inlined into HTML.
-
-Just use the following config:
-
-```js
-const path = require('path');
-const HtmlBundlerPlugin = require('html-bundler-webpack-plugin');
-
-module.exports = {
-  mode: 'production',
-  output: {
-    path: path.join(__dirname, 'dist/'),
-  },
-  plugins: [
-    new HtmlBundlerPlugin({
-      entry: {
-        index: './src/views/index.html',
-      },
-      css: {
-        inline: true, // inline CSS into HTML
-      },
-      js: {
-        inline: true, // inline JS into HTML
-      },
-    }),
-  ],
-  module: {
-    rules: [
-      {
-        test: /\.(css|sass|scss)$/,
-        use: ['css-loader', 'sass-loader'],
-      },
-      // inline all assets: images, svg, fonts
-      {
-        test: /\.(png|jpe?g|webp|svg|woff2?)$/i,
-        type: 'asset/inline',
-      },
-    ],
-  },
-  performance: false, // disable warning max size
-};
-```
-
-[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/edit/inline-all-assets-to-html?file=README.md)
-
----
-
-#### [↑ back to contents](#contents)
-
 <a id="recipe-import-svg" name="recipe-import-svg"></a>
 
 ## How to import SVG in JS
@@ -5685,15 +5621,17 @@ If you use it yet, remove this legacy loader from your configuration.
 Since Webpack 5, you can use the native Webpack [Asset Modules](https://webpack.js.org/guides/asset-modules/),
 which are supported by the Bundler Plugin.
 
-> [!NOTE]
-> This requires a couple of extra lines of configuration, 
-> but is faster since it doesn't use extra handlers like `svg-url-loader`.
+#### Replacement of svg-url-loader options
 
-### Use cases
+- [encoding](https://github.com/bhovhannes/svg-url-loader#encoding) - Use the `?inline` or `?inline=base64` query.
+- [prefix]() - Use the [output filename](https://webpack.js.org/guides/asset-modules/#custom-output-filename) option.
+- [limit](https://github.com/bhovhannes/svg-url-loader#limit) - Use the [Rule.parser.dataUrlCondition](https://webpack.js.org/configuration/module/#ruleparserdataurlcondition) option.
+- [iesafe](https://github.com/bhovhannes/svg-url-loader#iesafe) - The same as by `limit` using `Rule.parser.dataUrlCondition.maxSize = 4096`.
+- [stripdeclarations](https://github.com/bhovhannes/svg-url-loader#stripdeclarations) - we wan't manipulate the SVG content, may be useful to read by [svgo](https://github.com/svg/svgo/issues/836).\
+  Anyway [In XML 1.1, the declaration is mandatory](https://stackoverflow.com/a/7007781/1696030), therefore this option is senseless.
 
-#### Import SVG file in JS as output filename.
 
-Using default configuration of module rules with `asset/resource` module type, the imported SVG file will contain a output filename.
+To handle SVG files define the module configuration:
 
 ```js
 module: {
@@ -5709,75 +5647,51 @@ module: {
 }
 ```
 
-The imported `file` contains the hashed output filename.
+### Import SVG file as output filename.
+
+Using the module configuration as `asset/resource`, the imported SVG file will contain a output filename.
+
 
 ```js
 import file from './image.svg';
 
 console.log(file); // img/image.416b7e1d.svg
 ```
 
-#### Import SVG file in JS as data URL.
+### Import SVG file as data URL.
 
-To import SVG file as the data URL, use the `asset/inline` module type.
-If you import an SVG file in different ways, you can define a URL query for each module type.
+The Bundler Plugin supports the `?inline` URL query to force load SVG file as a data URL.
 
-For example, use the `?dataurl` query to import a SVG file as data URL:
+> [!NOTE]
+> The `inline` query works independent of used module type.
 
-```js
-module: {
-  rules: [
-    {
-      test: /\.svg/i,
-      resourceQuery: /dataurl/, // <= you can define any query as you like
-      type: 'asset/inline',
-    },
-  ],
-}
-```
+The `inline` query parameter supports values of encoding:
+- `utf8` - import SVG as UTF-8 data URL (defaults, can be omitted)
+- `base64` - import SVG as base64-encoded data URL
 
-By importing an SVG file using the `?dataurl` query, Webpack generates a base64-encoded data URL.
+For example, import SVG as UTF-8 data URL:
 
 ```js
-import file from './image.svg?dataurl'; // <= the `dataurl` query must be defined in Webpack
-
-console.log(file); // data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDo...vc3ZnPgo=
-```
-
-#### Import SVG file in JS as source code.
-
-To import the source code of the SVG file, use the `asset/source` module type.
-If you import an SVG file in different ways, define a URL query for each module type.
+import file from './image.svg?inline';
 
-For example, use the `?raw` query to import the source code of the SVG file:
-
-```js
-module: {
-  rules: [
-    {
-      test: /\.svg/i,
-      resourceQuery: /raw/, // <= you can define any query as you like
-      type: 'asset/source',
-    },
-  ],
-}
+console.log(file); // data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2...%3C%2Fsvg%3E
 ```
 
-By importing an SVG file using the `?raw` query, you will get source code.
+To import SVG as base64-encoded data URL, use the `?inline=base64` query.
 
 ```js
-import file from './image.svg?raw'; // <= the `raw` query must be defined in Webpack
+import file from './image.svg?inline=base64';
 
-console.log(file); // <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 96 960 960">...</svg>
+console.log(file); // data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDo...vc3ZnPgo=
 ```
 
-### Import SVG in JS with different ways
+### Manual import SVG in JS with different ways
 
 For example, you need:
  
 - by default, the output filename will be generated 
-- using `?dataurl` query, the base64-encoded data URL will be generated
-- using `?raw` query, the source code of the SVG file will be loaded 
+- using the `?dataurl` custom query, the base64-encoded data URL will be generated
+- using the `?raw` custom query, the source code of the SVG file will be loaded 
 
 
 Combine all your use cases in the Webpack configuration with `oneOf`:
@@ -5786,14 +5700,14 @@ Combine all your use cases in the Webpack configuration with `oneOf`:
 module: {
   rules: [
     {
-      test: /\.svg/i, // note: don't add `$` to the end of the RegEx
+      test: /\.svg/i,
       oneOf: [
-        // import SVG in JS as data URL using `?dataurl` query
+        // import SVG in JS as data URL using the `?dataurl` custom query
         {
           resourceQuery: /dataurl/,
           type: 'asset/inline',
         },
-        // import SVG in JS as raw content using `?raw` query
+        // import SVG in JS as raw content using `?raw` custom query
         {
           resourceQuery: /raw/,
           type: 'asset/source',
@@ -5804,6 +5718,12 @@ module: {
           type: 'asset/resource',
           generator: {
             filename: 'img/[name].[hash:8][ext]',
+            dataUrl: {
+              // encoding values:
+              // 'base64' - generates base64-encoded data URL (Webpack defaults)
+              // false    - generates UTF-8 data URL, use it only for SVG
+              encoding: false,
+            },
           },
         },
       ],
@@ -5830,6 +5750,63 @@ See the [test case](https://github.com/webdiscus/html-bundler-webpack-plugin/tre
 
 #### [↑ back to contents](#contents)
 
+<a id="recipe-inline-all-assets-to-html" name="recipe-inline-all-assets-to-html"></a>
+
+## How to inline all resources into single HTML file
+
+The bundler plugin can generate a single HTML file included all embedded dependencies
+such as JS, CSS, fonts, images (PNG, SVG, etc..).
+
+The fonts and images used in CSS will be inlined into CSS.
+The generated CSS including inlined images will be inlined into HTML.
+
+Just use the following config:
+
+```js
+const path = require('path');
+const HtmlBundlerPlugin = require('html-bundler-webpack-plugin');
+
+module.exports = {
+  mode: 'production',
+  output: {
+    path: path.join(__dirname, 'dist/'),
+  },
+  plugins: [
+    new HtmlBundlerPlugin({
+      entry: {
+        index: './src/views/index.html',
+      },
+      css: {
+        inline: true, // inline CSS into HTML
+      },
+      js: {
+        inline: true, // inline JS into HTML
+      },
+    }),
+  ],
+  module: {
+    rules: [
+      {
+        test: /\.(css|sass|scss)$/,
+        use: ['css-loader', 'sass-loader'],
+      },
+      // inline all assets: images, svg, fonts
+      {
+        test: /\.(png|jpe?g|webp|svg|woff2?)$/i,
+        type: 'asset/inline',
+      },
+    ],
+  },
+  performance: false, // disable warning max size
+};
+```
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/edit/inline-all-assets-to-html?file=README.md)
+
+---
+
+#### [↑ back to contents](#contents)
+
 <a id="recipe-resolve-attr-json" name="recipe-resolve-attr-json"></a>
 
 ## How to resolve source assets in an attribute containing JSON value

package.json

@@ -1,6 +1,6 @@
 {
   "name": "html-bundler-webpack-plugin",
-  "version": "4.12.0-beta.0",
+  "version": "4.12.0",
   "description": "Generates complete single-page or multi-page website from source assets. Build-in support for Markdown, Eta, EJS, Handlebars, Nunjucks, Pug. Alternative to html-webpack-plugin.",
   "keywords": [
     "html",