Skip to content

docs(guides,config) asset module follow up #3382

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Dec 2, 2019
97 changes: 52 additions & 45 deletions src/content/configuration/module.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand All @@ -266,7 +272,7 @@ module.exports = {
//...
parser: {
dataUrlCondition: {
maxSize: 8096
maxSize: 4 * 1024
}
}
}
Expand All @@ -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 = {
Expand All @@ -298,55 +324,36 @@ module.exports = {
//...
generator: {
encoding: 'base64',
mimetype: ''
mimetype: 'mimetype/png'
}
}
]
}
}
```

## `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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When used a a function, it executes for every module and must return a data URI string.
When used as 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`
Expand Down Expand Up @@ -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`

Expand Down
32 changes: 14 additions & 18 deletions src/content/guides/asset-modules.md
Original file line number Diff line number Diff line change
@@ -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:

Expand All @@ -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__

Expand Down Expand Up @@ -67,11 +69,9 @@ module.exports = {

__src/index.js__

``` js
```js
import mainImage from './images/main.png';

// ...

img.src = mainImage; // '/dist/151cfcfa1bd74779aadb.png'
```

Expand All @@ -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 = {
Expand Down Expand Up @@ -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=)
```
Expand All @@ -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');

Expand Down Expand Up @@ -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');

Expand Down Expand Up @@ -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'
```
Expand Down Expand Up @@ -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__

Expand Down Expand Up @@ -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.