Skip to content
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

docs(performance): Add performance config documentation #500

Merged
merged 2 commits into from
Dec 20, 2016
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion content/configuration/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -282,6 +282,19 @@ T> Notice that throughout the configuration we use Node's built-in [path module]
</details>
},

[performance](/configuration/performance): {
<details><summary>[hints](/configuration/performance#performance-hints): "warning", // enum </summary>
[hints](/configuration/performance#performance-hints): "error", // emit errors for perf hints
[hints](/configuration/performance#performance-hints): false, // turn off perf hints
</details>
[maxAssetSize](/configuration/performance#performance-maxassetsize): 200000, // int (in bytes),
[maxEntrypointSize](/configuration/performance#performance-maxentrypointsize): 400000, // int (in bytes)
[assetFilter](/configuration/performance#performance-assetfilter): function(assetFilename) {
// Function predicate that provides asset filenames
return assetName.endsWith('.css') || assetName.endsWith('.js');
}
},

<details><summary>[devtool](/configuration/devtool): "source-map", // enum </summary>
[devtool](/configuration/devtool): "inline-source-map", // inlines SourceMap into orginal file
[devtool](/configuration/devtool): "eval-source-map", // inlines SourceMap per module
Expand Down Expand Up @@ -338,7 +351,8 @@ T> Notice that throughout the configuration we use Node's built-in [path module]
// ...
],
// list of additional plugins



<details><summary>/* Advanced configuration (click to show) */</summary>

[resolveLoader](/configuration/resolve#resolveloader): { /* same as resolve */ }
Expand Down
97 changes: 97 additions & 0 deletions content/configuration/performance.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
---
title: Performance
sort: 14
contributors:
- thelarkinn
---

These options allows you to control how webpack notifies you of assets and entrypoints that exceed a specific file limit.
This feature was inspired by the idea of [webpack Performance Budgets](https://github.com/webpack/webpack/issues/3216).

## `performance`

`object`

Configure how performance hints are shown. For example if you have an asset that is over 250kb, webpack will emit a warning notifiying you of this.


## `performance.hints`

`boolean | "error" | "warning"`

Turns hints on/off. In addition, tells webpack to throw either an error or a warning when hints are found. This property is set to `"warning"` by default.

Given an asset is created that is over 250kb:

```js
performance: {
hints: false
}
```

No hint warnings or errors are shown.

```js
performance: {
hints: "warning"
}
```

A warning will be displayed notifying you of a large asset. We recommend something like this for development environments.
Copy link
Contributor

Choose a reason for hiding this comment

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

Let's say you are inlining assets during development, missing minification etc., wouldn't this yield warnings even if they aren't relevant? Isn't the best value in production build?

Copy link
Member Author

Choose a reason for hiding this comment

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

Yes, but also gives perspective to users as they are developing.

If a bundle grows from 200->350kb after a certain feature, I'd want to know specifically about it while developing so I can trace my steps back a few changes and investigate more into what is causing the bloat.

Copy link
Contributor

Choose a reason for hiding this comment

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

Alright. I guess it takes more experience with the feature for me to tell any better. Hitting the limits is very easy by inlining just a few images.

Copy link
Member Author

Choose a reason for hiding this comment

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

Developing the last thing I'd like is to be caught of guard after x hours of development to see errors because of size stuff I could maybe have caught in the act.

Again these are just hypothetical/estimates etc.

Copy link
Member Author

Choose a reason for hiding this comment

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

Yes true. Maybe that's where they could filter assets, etc.

I mean at the most these are recommendations but I 100% agree where you are coming from.

Copy link
Contributor

Choose a reason for hiding this comment

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

Would it make sense to have something like --json kind of flag for the perf data? Can you get it in JSON to track?

Copy link
Member Author

Choose a reason for hiding this comment

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

Aww that would actually be a really cool feature but the log might be built. I'm going to add that to the original issue.

Copy link
Member Author

Choose a reason for hiding this comment

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

Might be big*


```js
performance: {
hints: "error"
}
```

An error will be displayed notifying you of a large asset. We recommend using `hints: "error"` during production builds to help prevent deploying production bundles that are too large, impacting webpage performance.

## `performance.maxEntrypointSize`

`int`

An entrypoint represents all assets that would be utilized during initial load time for a specific entry. This option controls when webpack should emit performance hints based on the maximum entrypoint size. The default value is `250000` (bytes).

```js
performance: {
maxEntrypointSize: 400000
}
```

## `performance.maxAssetSize`

`int`

An asset is any emitted file from webpack. This option controls when webpack emits a performance hint based on individual asset size. The default value is `250000` (bytes).


```js
performance: {
maxAssetSize: 100000
}
```

## `performance.assetFilter`

`Function`

This property allows webpack to control what files are used to calculate performance hints. The default function is seen below:

```js
function(assetFilename) {
return !(/\.map$/.test(assetFilename))
};
```

You can override this property by passing your own function in:

```js
performance: {
assetFilter: function(assetFilename) {
return assetFilename.endsWith('.js');
}
}
```

The example above will only give you performance hints based on `.js` files.