diff --git a/src/content/configuration/module.mdx b/src/content/configuration/module.mdx index 5c2be131b249..e28b610fcd87 100644 --- a/src/content/configuration/module.mdx +++ b/src/content/configuration/module.mdx @@ -249,13 +249,19 @@ module.exports = { } ``` -If `Rule.type` is an `asset` then `Rules.parser` option may be an object or function that describes a condition whether to encode file contents to Base64 or emit it as a separate file into the output directory. +If `Rule.type` is an `asset` then `Rules.parser` option may be an object or a function that describes a condition whether to encode file contents to Base64 or emit it as a separate file into the output directory. -If `Rule.type` is an `asset` or `asset/inline` then `Rule.generator` option may be an object that describes an encoding of the module source or a function that encodes a module source by a custom algorithm. +If `Rule.type` is an `asset` or `asset/inline` then `Rule.generator` option may be an object that describes the encoding of the module source or a function that encodes module's source by a custom algorithm. -For more info - see [Asset Modules](/guides/asset-modules/) +See [Asset Modules guide](/guides/asset-modules/) for additional information and use cases. -## `Rule.parse.dataUrlCondition` as an object +## `Rule.parser.dataUrlCondition` + +`object = { maxSize number = 8096 }` `function (source, { filename, module }) => boolean` + +If a module source size is less than `maxSize` then module will be injected into the bundle as a Base64-encoded string, otherwise module file will be emitted into the output directory. + +__webpack.config.js__ ```js module.exports = { @@ -266,7 +272,7 @@ module.exports = { //... parser: { dataUrlCondition: { - maxSize: 8096 + maxSize: 4 * 1024 } } } @@ -275,19 +281,39 @@ module.exports = { } ``` -## `dataUrlCondition.minSize` +When a function is given, returning `true` tells webpack to inject the module into the bundle as Base64-encoded string, otherwise module file will be emitted into the output directory. -`number` +__webpack.config.js__ -If a module source size is less than `maxSize` then module will be injected into the bundle as a Base64-encoded string, otherwise module file will be emitted into the output directory. +```js +module.exports = { + //... + module: { + rules: [ + { + //... + parser: { + dataUrlCondition: (source, { filename, module })) => { + const content = source.toString(); + return content.includes('some marker'); + } + } + } + ] + } +} +``` -## `Rule.parse.dataUrlCondition` as a function +## `Rule.generator.dataUrl` -`function(source, { filename, module }) => boolean` +`object = { encoding string = 'base64' | false, mimetype string = undefined | false }` `function (content, { filename, module }) => string` -If the function returns true, then module will be injected into the bundle as base64-encoded string, otherwise module file will be emitted into the output directory. +When `Rule.generator.dataUrl` is used as an object, you can configure two properties: -## `Rule.generator.dataUrl` as an object +- encoding: When set to `'base64'`, module source will be encoded using Base64 algorithm. Setting `encoding` to false will disable encoding. +- mimetype: A mimetype for data URI. Resolves from module resource extension by default. + +__webpack.config.js__ ```js module.exports = { @@ -298,7 +324,7 @@ module.exports = { //... generator: { encoding: 'base64', - mimetype: '' + mimetype: 'mimetype/png' } } ] @@ -306,47 +332,28 @@ module.exports = { } ``` -## `dataUrl.encoding` - -`'base' | false` - -- `base64` - encode a module source with Base64 algorithm -- `false` - don't encode a module source - -## `dataUrl.mimetype` - -`string` - -A mimetype for data-url. Resolves from module resource extension by default - -## `Rule.generator.dataUrl` as a function +When used a a function, it executes for every module and must return a data URI string. -`function(source, { filename, module }) => string` - -A function that executes for a module and should return a data-url string - -__webpack.config.js__ - -``` js +```js module.exports = { - experiments: { - asset: true - }, + //... module: { rules: [ { - test: /\.txt/, - type: 'asset', - parser: { - dataUrlCondition(source, { filename, module }) { - content = content.toString(); - return content.includes('some marker'); + //... + generator: { + dataUrl: content => { + const svgToMiniDataURI = require('mini-svg-data-uri'); + if (typeof content !== 'string') { + content = content.toString(); + } + return svgToMiniDataURI(content); } } } ] } -}; +} ``` ## `Rule.resource` @@ -444,7 +451,7 @@ module.exports = { }; ``` -> See [Asset Modules](/guides/asset-modules/) for more about `asset*` type +> See [Asset Modules guide](/guides/asset-modules/) for more about `asset*` type. ## `Rule.use` diff --git a/src/content/guides/asset-modules.md b/src/content/guides/asset-modules.md index 0b8df738c238..3246d89bccf8 100644 --- a/src/content/guides/asset-modules.md +++ b/src/content/guides/asset-modules.md @@ -1,10 +1,12 @@ --- title: Asset Modules +sort: 24 contributors: - smelukov + - EugeneHlushko --- -Asset Modules is a type of modules that allows to use assets files (fonts, icons, etc) without configuring additional loaders. +Asset Modules is a type of module that allows to use asset files (fonts, icons, etc) without configuring additional loaders. Prior to webpack 5 it was common to use: @@ -19,7 +21,7 @@ Asset Modules type replaces all of these loaders by adding 4 new module types: - `asset/source` exports the source code of the asset. Previously achievable by using `raw-loader`. - `asset` automatically chooses between exporting a data URI and emitting a separate file. Previously achievable by using `url-loader` with asset size limit. -W> This is an experimental feature. Enable Asset Modules by setting `experiments.asset: true` in [experiments](/configuration/experiments/) option of your webpack configuration +W> This is an experimental feature. Enable Asset Modules by setting `experiments.asset: true` in [experiments](/configuration/experiments/) option of your webpack configuration. __webpack.config.js__ @@ -67,11 +69,9 @@ module.exports = { __src/index.js__ -``` js +```js import mainImage from './images/main.png'; -// ... - img.src = mainImage; // '/dist/151cfcfa1bd74779aadb.png' ``` @@ -81,11 +81,11 @@ All `.png` files will be emitted to the output directory and their paths will be By default, `asset/resource` modules are emitting with `[hash][ext]` filename into output directory. -You can modify this template by setting `output.assetModuleFilename` in your configuration: +You can modify this template by setting [`output.assetModuleFilename`](/configuration/output/#outputassetmodulefilename) in your webpack configuration: __webpack.config.js__ -``` diff +```diff const path = require('path'); module.exports = { @@ -141,12 +141,10 @@ module.exports = { __src/index.js__ -``` diff +```diff - import mainImage from './images/main.png'; + import metroMap from './images/matro.svg'; -// ... - - img.src = mainImage; // '/dist/151cfcfa1bd74779aadb.png' + block.style.background = `url(${metroMap}); // url(data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDo...vc3ZnPgo=) ``` @@ -161,7 +159,7 @@ If you want to use a custom encoding algorithm, you may specify a custom functio __webpack.config.js__ -``` diff +```diff const path = require('path'); + const svgToMiniDataURI = require('mini-svg-data-uri'); @@ -197,7 +195,7 @@ Now all `.svg` files will be encoded by `mini-svg-data-uri` package. __webpack.config.js__ -``` diff +```diff const path = require('path'); - const svgToMiniDataURI = require('mini-svg-data-uri'); @@ -231,18 +229,16 @@ module.exports = { __src/example.txt__ -``` text +```text Hello world ``` __src/index.js__ -``` diff +```diff - import metroMap from './images/matro.svg'; + import exampleText from './example.txt'; -// ... - - block.style.background = `url(${metroMap}); // url(data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDo...vc3ZnPgo=) + block.textContent = exampleText; // 'Hello world' ``` @@ -278,7 +274,7 @@ module.exports = { Now webpack will automatically choose between `resource` and `inline` by following a default condition: a file with size less than 8kb will be treated as a `inline` module type and `resource` module type otherwise. -You can change this condition by setting a `parser.dataUrlCondition.maxSize` option on the module rule of your webpack configuration: +You can change this condition by setting a [`Rule.parser.dataUrlCondition.maxSize`](/configuration/module/#ruleparserdataurlcondition) option on the module rule level of your webpack configuration: __webpack.config.js__ @@ -310,4 +306,4 @@ module.exports = { }; ``` -Also you can [specify a function](/configuration/module/#ruleparsedataurlcondition-as-a-function) to decide to inlining a module or not. +Also you can [specify a function](/configuration/module/#ruleparserdataurlcondition) to decide to inlining a module or not.