Deprecation warning on CommonChunksPlugin. Add SplitChunksPlugin page #1863

jeremenichelli · 2018-02-27T23:48:47Z

Adding Tobias as a reviewer since I used his gist as a base for the SplitChunksPlugin page. I've also added a deprecation warning on CommonChunksPlugin one (not deleting it for now since developers and teams who can immediately migrate might need it).

…placeholder

This moves some of the content from `compiler.md` and brings it into the main node api documentation in order to allow `compiler.md` to become `compiler-hooks.md` which fits better in the context of plugins.

…le.md` This moves some of the `Tapable` discussion to the lead-in `plugins.md` to prevent doc duplication. Instead of redocumenting the `tapable` package, we should focus on improving the README and simply link to there throughout our docs. As I've mentioned before, we can also create a "Utilities" section for things other than "Loaders" and "Plugins" that we want to dynamically pull in.

These guides were full of todos and probably lead to more confusion than clarity. We can discuss more and add them back in once there's a clear flow for how to incorporate and document them.

This page now focuses specifically on the `hooks` as all the non-plugin related content was moved to `node.md`. I updated the hooks to the new syntax, added all undocumented hooks, reformatted each hook as a section to allow more breathing room, and clarified exactly which `tapable` hook is used for each section. Still need to get more info on some of the new hooks before we can ship this...

This page now uses the same section setup as `compiler-hooks.md` and is up to date with the latest hooks available in the webpack 4 alpha release.

Improve lead-in to give a little more context on what the parser does. Add the latest hooks and use the same layout as the other pages in the section.

montogeek · 2018-02-28T08:37:14Z

Great initial work!

jeremenichelli · 2018-02-28T19:22:11Z

@skipjack I want to bother you as less as possible, but tagging you here since it's a whole new page that would love to have a look from you.

skipjack

Looks great, don't worry about pinging me. Happy to come back and do reviews here and there.

skipjack · 2018-03-03T17:55:36Z

src/content/plugins/commons-chunk-plugin.md

-The `CommonsChunkPlugin` is an opt-in feature that creates a separate file (known as a chunk), consisting of common modules shared between multiple entry points. By separating common modules from bundles, the resulting chunked file can be loaded once initially, and stored in cache for later use. This results in pagespeed optimizations as the browser can quickly serve the shared code from cache, rather than being forced to load a larger bundle whenever a new page is visited.
+The `CommonsChunkPlugin` is an opt-in feature that creates a separate file (known as a chunk), consisting of common modules shared between multiple entry points.
+
+W> CommonsChunkPlugin has been deprecated in webpack v4 legato. If you want to know how chunks are treated in the newest version checkout [SplitChunksPlugin](/plugins/split-chunks-plugin/).


I would rephrase this slightly:

The CommonsChunkPlugin has been deprecated in webpack v4 legato.. To learn how chunks are treated in the latest version, check out the SplitChunksPlugin.

s/legato../legato.

skipjack · 2018-03-03T17:56:28Z

src/content/plugins/split-chunks-plugin.md

+
+Originally in webpack, chunks (and modules import inside them) were connected by a parent-child relationship in the internal webpack graph.
+
+This connection didn't allow to further optimizations and reluted into more coded downloaded.


s/reluted/resulted

s/more coded downloaded/more downloaded code

s/allow to/allow for/

mike1808 · 2018-03-04T16:09:18Z

src/content/plugins/split-chunks-plugin.md

+	cacheGroups: {
+		default: {
+			minChunks: 2,
+			priority: -20


comma is missing

robert-claypool · 2018-03-05T15:03:07Z

src/content/plugins/split-chunks-plugin.md

+splitChunks: {
+	cacheGroups: {
+		commons: {
+			test: /[\\/]node_modules[\\/]


Missing a slash-comma: test: /[\\/]node_modules[\\/]/,

blowery · 2018-03-06T14:34:12Z

src/content/plugins/split-chunks-plugin.md

+
+Out of the box `SplitChunksPlugin` should work great for most users.
+
+By default the plugin only affect on-demand chunks, because changing initial chunks would affect the script tags that the HTML file should include to run the project.


affect should be affects

@blowery I don't agree, affect is correct grammar

@audiolion, are you sure? I think if "plugin" were plural, then I agree "affect" should be used (ie "the plugins only affect on-demand chunks"), however given it's singular, "affects" seems more correct to me.

haha, I was reading the wrong "affect", initial chunks would affect(s) the script tags...

Lol, same happened to me. Thanks.

benthemonkey · 2018-03-06T19:34:17Z

src/content/plugins/split-chunks-plugin.md

+
+For these people that like to have more control over this functionality, webpack provides a set of options to better fit your needs.
+
+W> If you are manually changing the split configuration, measure the impact of the changes to see and make sure there's a real benefit. The defaults are choosen to fit best practices of web performance.


s/choosen/chosen
(change below my opinion, not related to grammar):
s/fit best practices of web performance/fit web performance best practices

benthemonkey · 2018-03-06T19:35:19Z

src/content/plugins/split-chunks-plugin.md

+
+### Configuring cache groups
+
+The defaults assigns all modules from `node_modules` to a cache group called `vendors` and all modules duplicated in at least 2 chunks to a change group `default`.


s/change group/cache group

benthemonkey · 2018-03-06T19:42:57Z

I notice these docs don't include any information about the enforce cache group setting. I've been playing around with that option and was hoping to learn more about it from these docs. It seems like it is useful for overriding the base settings for only one cache group. E.g.:

splitChunks: {
	chunks: "async",
	minSize: 30000,
	minChunks: 1,
	maxAsyncRequests: 5,
	maxInitialRequests: 3,
	name: true,
	cacheGroups: {
		default: {
			minChunks: 2,
			priority: -20
			reuseExistingChunk: true,
		},
		vendors: {
			test: /[\\/]node_modules[\\/]/,
			priority: -10
		},
		special: {
			test: myTestFunc,
			enforce: true
		}
	}
}

Please correct me if I am mistaken: The enforce allows the special cache group to ignore the minSize, minChunks, maxAsyncRequests and maxInitialRequests set in the overall splitChunks config and purely use test to decide what goes into the chunk. What I'm unclear on is how that fits in when used with reuseExistingChunk.

benthemonkey · 2018-03-06T19:46:48Z

src/content/plugins/split-chunks-plugin.md

+
+## `optimization.runtimeChunk`
+
+Setting `optimization.runtimeChunk` to `true` adds an additonal chunk to each entrypoint containing only the runtime.


include the different things that you can pass to runtimeChunk. It can be a boolean, 'single', 'multiple' or an object that has property name whose value can be either a string or a function of signature (entrypoint: Chunk) => string

e.g.

{ name: entrypoint => `runtime~${entrypoint.name}` }

Hey @sokra can you fill in some technical gap here? Should we add enforce details in this piece, I would need your help with it 😓

What is its default value? In this blog post it says it's true, but from trying it out it's not.

balanceiskey · 2018-03-06T20:01:58Z

src/content/plugins/split-chunks-plugin.md

+* Maximum number of parallel request when loading chunks on demand would be lower or equal to 5
+* Maximum number of parallel request at initial page load would be lower or equal to 3
+
+When trying to fullfill the last two conditions, bigger chunks are preferred.


fullfill -> fulfill

lencioni · 2018-03-07T21:48:13Z

src/content/plugins/split-chunks-plugin.md

+webpack will automatically split chunks based on these conditions:
+
+* New chunk can be shared OR modules are from the `node_modules` folder
+* New chunk would be bigger than 30kb (before min+gz)


kb -> KiB (here and elsewhere)

audiolion · 2018-03-08T12:33:22Z

src/content/plugins/split-chunks-plugin.md

+
+W> When assigning equal names to different split chunks they are merged together. This can be used to put all vendor modules into a single shared chunk, but it's not recommend since it can result in more code downloaded.
+
+The magic value `true` automatically chooses a name based on chunks and cache group key. Elsewise a string or function can be passed.


s/Elsewise/Otherwise

Elsewise usage in english

jeremenichelli · 2018-03-08T22:54:47Z

Thanks everyone for all your feedback. Working on updates and getting changes pushed soon.

audiolion · 2018-03-08T23:36:45Z

src/content/plugins/commons-chunk-plugin.md

+
+W> CommonsChunkPlugin has been deprecated in webpack v4 legato. If you want to know how chunks are treated in the newest version checkout [SplitChunksPlugin](/plugins/split-chunks-plugin/).
+
+By separating common modules from bundles, the resulting chunked file can be loaded once initially, and stored in cache for later use. This results in pagespeed optimizations as the browser can quickly serve the shared code from cache, rather than being forced to load a larger bundle whenever a new page is visited.

 ```javascript
 new webpack.optimize.CommonsChunkPlugin(options)


shouldn't this be removed? or replaced with:

optimization: { splitChunks: { name: 'all', }, }

This is the old CommonsChunkPlugin page. We are keeping the old documentaiton for teams that are already using it and haven't migrated to v4. We are adding a warning on top talking about the deprecation of it from now on.

sokra · 2018-03-09T07:38:24Z

src/content/plugins/split-chunks-plugin.md

+
+`cacheGroups` is an object where keys are the cache group names. All options from the ones listed above are possible: `chunks`, `minSize`, `minChunks`, `maxAsyncRequests`, `maxInitialRequests`, `name`.
+
+You can set `optimization.splitChunks.cacheGroups.default` to `false` to disable the default cache group.


Same for optimization.splitChunks.cacheGroups.vendors.

sokra · 2018-03-09T07:40:38Z

src/content/plugins/split-chunks-plugin.md

+
+Here are some examples and their effect:
+
+### Example 1


Add another example:

Enable the default optimizations for all chunks instead of only async chunks. This is the recommended configuration.

splitChunks: { chunks: "all" }

I've added a specific section for chunks: "all" so we highlight this configuration set as recommended, pushing in a bit.

sokra · 2018-03-09T07:43:57Z

src/content/plugins/split-chunks-plugin.md

+		}
+	}
+}
+```


By default this configuration will only create a commons chunk when the minimum size and maximum number of requests are valid. Adding enforce: true, will disable any not configured condition and enforce creating the chunk.

sokra · 2018-03-09T07:48:31Z

src/content/plugins/split-chunks-plugin.md

+
+You can set `optimization.splitChunks.cacheGroups.default` to `false` to disable the default cache group.
+
+The priority of the default groups are negative to allow any custom cache group to take higher priority (the default value is `0`).


The priority controls the order in which cache groups are executed. Higher priorities will execute before lower priorities.

edmorley · 2018-03-09T17:27:27Z

src/content/plugins/split-chunks-plugin.md

+    url: https://medium.com/webpack/webpack-4-code-splitting-chunk-graph-and-the-splitchunks-optimization-be739a861366
+---
+
+Originally in webpack, chunks (and modules import inside them) were connected by a parent-child relationship in the internal webpack graph.


s/modules import/modules imported/

edmorley · 2018-03-09T17:28:02Z

src/content/plugins/split-chunks-plugin.md

+
+Originally in webpack, chunks (and modules import inside them) were connected by a parent-child relationship in the internal webpack graph.
+
+This connection didn't allow to further optimizations and reluted into more coded downloaded.


s/allow to/allow for/

edmorley · 2018-03-09T17:28:25Z

src/content/plugins/split-chunks-plugin.md

+
+This connection didn't allow to further optimizations and reluted into more coded downloaded.
+
+webpack v4 removes the `CommonsChunkPlugin` in favor of `optimization.splitChunks` and `optimization.runtimeChunk` options. Here is how the new flow works.


s/favor of/favor of the/

edmorley · 2018-03-09T17:31:30Z

src/content/plugins/split-chunks-plugin.md

+
+Out of the box `SplitChunksPlugin` should work great for most users.
+
+By default the plugin only affect on-demand chunks, because changing initial chunks would affect the script tags that the HTML file should include to run the project.


@audiolion, are you sure? I think if "plugin" were plural, then I agree "affect" should be used (ie "the plugins only affect on-demand chunks"), however given it's singular, "affects" seems more correct to me.

edmorley · 2018-03-09T17:32:04Z

src/content/plugins/split-chunks-plugin.md

+* New chunk can be shared OR modules are from the `node_modules` folder
+* New chunk would be bigger than 30kb (before min+gz)
+* Maximum number of parallel request when loading chunks on demand would be lower or equal to 5
+* Maximum number of parallel request at initial page load would be lower or equal to 3


s/parallel request/parallel requests/ (x2)

edmorley · 2018-03-09T17:32:48Z

src/content/plugins/split-chunks-plugin.md

+
+## Configuration
+
+For these people that like to have more control over this functionality, webpack provides a set of options to better fit your needs.


s/For these people/For people/

lencioni · 2018-03-09T18:45:37Z

src/content/plugins/split-chunks-plugin.md

+
+### Select modules
+
+The `test` option controls which modules are selected by this cache group. Omitting it selects all modules. It can be a RegExp, string or function.


It would be nice if this section went more into details about the function version of this option, e.g. what the args to the function are, how to use them, and what the function should return.

FWIW, it looks like test fn is called with 2 args. module and chunks.

https://github.com/webpack/webpack/blob/66ff412f7e2409ee535c2dc79abf4068015b2e22/lib/optimize/SplitChunksPlugin.js#L188

I think module is an object that describes the chunk being considered for placement, and chunks seems to be an array of objects with metadata about each chunk. I'm not sure where these are documented or defined in code yet.

It seems that test functions should return a boolean.

Each chunk object seems to have these keys:

id ids debugId name entryModule _modules _groups files rendered hash renderedHash chunkReason extraAsync

Ah found it https://github.com/webpack/webpack/blob/fde018300aa52262c384e937c408d5dd97d62951/lib/Chunk.js#L46

Yes, I imagine that boolean decides if the current module goes to a chunk or not.

lencioni · 2018-03-12T22:44:16Z

src/content/plugins/split-chunks-plugin.md

+
+By default cache groups inherit options from `splitChunks.*`, but `test`, `priority` and `reuseExistingChunk` can only be configured on cache group level.
+
+`cacheGroups` is an object where keys are the cache group names. All options from the ones listed above are possible: `chunks`, `minSize`, `minChunks`, `maxAsyncRequests`, `maxInitialRequests`, `name`.


It looks like cacheGroups can also be a function? Should this be documented here? https://github.com/webpack/webpack/blob/66ff412f7e2409ee535c2dc79abf4068015b2e22/lib/optimize/SplitChunksPlugin.js#L132

ind1go · 2018-03-21T13:32:46Z

src/content/plugins/split-chunks-plugin.md

+
+Putting the content of `helpers` into each chunk will result into its code being downloaded twice. By using a separate chunk this will only happen once. We pay the cost of an additional request, which could be considered a tradeoff. That's why there is a minimum size of 30kb.
+
+T> With the new `optimizations.splitChunks.chunks: "all"` option the same would happend for initial chunks. Chunks can even be shared between entrypoints and on-demand loading.


s/optimizations/optimization/

jeremenichelli · 2018-03-26T00:11:38Z

Thanks everyone for the comments, I'm creating a new pull request since the next branch has been merged and rebase is completely broken from here in files that haven't been touched and I don't want to cause regression on content.

@sokra I will create an issue with some stuff that needs to be revisited or cover in the split chunks article. Thanks for the comments.

MagicDuck and others added 21 commits February 6, 2018 23:19

adding docs for new output.devtoolNamespace option and [namespace] …

dafbbb2

…placeholder

adding extra lines as indicated

f3c515c

docs(config): update hashFunction docs based on v4 (#1761)

8ccb3da

docs(api): reformat index page at 80 characters / line

7fa4fe0

docs(api): reformat node api docs and add more details on the compiler

388aa68

This moves some of the content from `compiler.md` and brings it into the main node api documentation in order to allow `compiler.md` to become `compiler-hooks.md` which fits better in the context of plugins.

docs(api): remove module-factories.md and template.md

d5c0a24

These guides were full of todos and probably lead to more confusion than clarity. We can discuss more and add them back in once there's a clear flow for how to incorporate and document them.

docs(api): reformat line length in plugins.md

38e33c2

docs(api): rewrite, rename, and resort the compilation.md page

ede8e02

This page now uses the same section setup as `compiler-hooks.md` and is up to date with the latest hooks available in the webpack 4 alpha release.

docs(api): fix sorting and start to reformat the last two plugin pages

e0f7a62

docs(api): begin rewrite of the resolver page

ebe7331

docs(config): fix header nesting in resolve.md

b066b44

docs(api): rename resolvers page for clarity and finish rewrite

93efa5d

docs(api): make minor corrections to plugin docs

1555e7c

docs(api): rewrite the parser documentation

7941097

Improve lead-in to give a little more context on what the parser does. Add the latest hooks and use the same layout as the other pages in the section.

docs(api): update some of the compiler hook descriptions

acf7b77

docs(plugins): add ProfilingPlugin documentation (#1830)

7b89b9f

docs(config): document info-verbosity option in watch.md (#1817)

4354b9a

Merge branch 'master' into next

b1d2779

Deprecation warning on CommonChunksPlugin. Add SplitChunksPlugin page

fe1e627

jeremenichelli requested a review from sokra February 27, 2018 23:48

jeremenichelli mentioned this pull request Feb 27, 2018

Config - Document splitChunks and minimize #1812

Closed

skipjack mentioned this pull request Feb 27, 2018

Release - Document v4 (Migration Guide and Feature Additions) #1706

Open

jeremenichelli added Documentation Plugins New Release labels Feb 28, 2018

jeremenichelli requested a review from skipjack February 28, 2018 19:21

jeremenichelli requested a review from TheLarkInn February 28, 2018 19:22

jeremenichelli changed the base branch from next to master February 28, 2018 19:38

jeremenichelli changed the base branch from master to next February 28, 2018 20:07

Reindent yaml frontmatter

17ead3d

skipjack requested changes Mar 3, 2018

View reviewed changes

mike1808 reviewed Mar 4, 2018

View reviewed changes

src/content/plugins/split-chunks-plugin.md Outdated

cacheGroups: {

default: {

minChunks: 2,

priority: -20

Copy link

mike1808 Mar 4, 2018

Choose a reason for hiding this comment

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

comma is missing

robert-claypool reviewed Mar 5, 2018

View reviewed changes

blowery reviewed Mar 6, 2018

View reviewed changes

benthemonkey reviewed Mar 6, 2018

View reviewed changes

balanceiskey reviewed Mar 6, 2018

View reviewed changes

lencioni reviewed Mar 7, 2018

View reviewed changes

audiolion reviewed Mar 8, 2018

View reviewed changes

Rephrasing and typos

5a35c14

audiolion reviewed Mar 8, 2018

View reviewed changes

sokra approved these changes Mar 9, 2018

View reviewed changes

edmorley reviewed Mar 9, 2018

View reviewed changes

lencioni reviewed Mar 9, 2018

View reviewed changes

lencioni reviewed Mar 12, 2018

View reviewed changes

dhruvdutt mentioned this pull request Mar 21, 2018

cli(init): webpack4 ready webpack/webpack-cli#356

Merged

ind1go reviewed Mar 21, 2018

View reviewed changes

fix: better highlight of chunks:all and gardening

1a65139

jeremenichelli changed the base branch from next to master March 25, 2018 23:59

jeremenichelli closed this Mar 26, 2018

jeremenichelli deleted the split-chunks-plugin branch March 26, 2018 00:11

jeremenichelli mentioned this pull request Mar 26, 2018

feat: add documentation for SplitChunksPlugin and deprecation warning… #1955

Merged


		Originally in webpack, chunks (and modules import inside them) were connected by a parent-child relationship in the internal webpack graph.

		This connection didn't allow to further optimizations and reluted into more coded downloaded.


		Out of the box `SplitChunksPlugin` should work great for most users.

		By default the plugin only affect on-demand chunks, because changing initial chunks would affect the script tags that the HTML file should include to run the project.


		For these people that like to have more control over this functionality, webpack provides a set of options to better fit your needs.

		W> If you are manually changing the split configuration, measure the impact of the changes to see and make sure there's a real benefit. The defaults are choosen to fit best practices of web performance.


		### Configuring cache groups

		The defaults assigns all modules from `node_modules` to a cache group called `vendors` and all modules duplicated in at least 2 chunks to a change group `default`.


		## `optimization.runtimeChunk`

		Setting `optimization.runtimeChunk` to `true` adds an additonal chunk to each entrypoint containing only the runtime.


		W> When assigning equal names to different split chunks they are merged together. This can be used to put all vendor modules into a single shared chunk, but it's not recommend since it can result in more code downloaded.

		The magic value `true` automatically chooses a name based on chunks and cache group key. Elsewise a string or function can be passed.


		`cacheGroups` is an object where keys are the cache group names. All options from the ones listed above are possible: `chunks`, `minSize`, `minChunks`, `maxAsyncRequests`, `maxInitialRequests`, `name`.

		You can set `optimization.splitChunks.cacheGroups.default` to `false` to disable the default cache group.


		You can set `optimization.splitChunks.cacheGroups.default` to `false` to disable the default cache group.

		The priority of the default groups are negative to allow any custom cache group to take higher priority (the default value is `0`).


		This connection didn't allow to further optimizations and reluted into more coded downloaded.

		webpack v4 removes the `CommonsChunkPlugin` in favor of `optimization.splitChunks` and `optimization.runtimeChunk` options. Here is how the new flow works.


		## Configuration

		For these people that like to have more control over this functionality, webpack provides a set of options to better fit your needs.


		### Select modules

		The `test` option controls which modules are selected by this cache group. Omitting it selects all modules. It can be a RegExp, string or function.


		By default cache groups inherit options from `splitChunks.*`, but `test`, `priority` and `reuseExistingChunk` can only be configured on cache group level.

		`cacheGroups` is an object where keys are the cache group names. All options from the ones listed above are possible: `chunks`, `minSize`, `minChunks`, `maxAsyncRequests`, `maxInitialRequests`, `name`.


		Putting the content of `helpers` into each chunk will result into its code being downloaded twice. By using a separate chunk this will only happen once. We pay the cost of an additional request, which could be considered a tradeoff. That's why there is a minimum size of 30kb.

		T> With the new `optimizations.splitChunks.chunks: "all"` option the same would happend for initial chunks. Chunks can even be shared between entrypoints and on-demand loading.

Deprecation warning on CommonChunksPlugin. Add SplitChunksPlugin page #1863

Deprecation warning on CommonChunksPlugin. Add SplitChunksPlugin page #1863

Conversation

jeremenichelli commented Feb 27, 2018 • edited Loading

montogeek commented Feb 28, 2018

jeremenichelli commented Feb 28, 2018

skipjack left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

benthemonkey commented Mar 6, 2018 • edited Loading

benthemonkey Mar 6, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jeremenichelli commented Mar 8, 2018

audiolion Mar 8, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lencioni Mar 12, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jeremenichelli commented Mar 26, 2018

jeremenichelli commented Feb 27, 2018 •

edited

Loading

benthemonkey commented Mar 6, 2018 •

edited

Loading

benthemonkey Mar 6, 2018 •

edited

Loading

audiolion Mar 8, 2018 •

edited

Loading

lencioni Mar 12, 2018 •

edited

Loading