Webpack.js.org: splitChunks : none of the options is self-explanatory and documentation is cryptic

[webpack-bot]

I know this ticket might not conform with the issue creation policy but I will try to compile a list of questions here hoping that they can be addressed (I am willing to make PRs to improve the documentation)

1. optimization.runtimeChunk
I guess this makes sense if you have more than one entry points. In any other case, the appropriate value should be 'false' , correct?

2. optimization.occurrenceOrder
Does this option still exist? (not found in documentation using search)

3. optimization.namedChunks
Same as above.

4. maxInitialRequests
I had cases when a cacheGroup was not generating a file until I increased the default maxInitialRequests value to something like "10". I have no idea why that is.

(and most importantly)
5. test
I am migrating a setup with which we were using simple strings to target individual node_modules which we wanted in a separate generated file to split the end result of vendors in smaller files. Some of the test rules don't seem to be doing what I think they should - is there a way to debug this? Can I just use a simple string like "moment.js" or should I target the parent directory using a regexp : /[\\/]moment[\\/]/.

6. chunks
The documentation of the options "initial", "async" and "all" is just a repetition of the option word itself. Desperately looking for a tangible example.

---

This issue was moved from webpack/webpack#7203 by @montogeek. Original issue was by @gkatsanos.

[EugeneHlushko]

We are in progress with adding optimization section to the configuration section of the docs (which hopefully resolves couple of your questions). Please see #2112 #1968 and current state at https://webpack.js.org/configuration/optimization/

I know this isn't a life saver answer, just to give you the rough idea on whats going on with optimization section documentation. Everyone is welcome to contribute

[gkatsanos]

I appreciate the answer. I read on reddit that the release of 4.x with regards to documentation is something that "was not supposed to happen" so looking forward for the updated documentation so we can improve our configs incrementally.

[thw0rted]

The PR that got merged addresses some of the bullet points in the OP but not all of them. Re-open? (I'm particularly interested in more details on test.)

[EugeneHlushko]

Test's regexp can be both directory and file like any regexp, you provide what to match against, but how do you want to split chunks from your single file? That doesnt make much sense, can you please (@thw0rted) or anyone willing open a separate issue in a format of

[ ] things unclear with detail
[ ] things unclear with detail

and we will go through them together and update the docs where necessary. I will gladly try to help as much and if necessary we involve more people

[thw0rted]

The OP in this issue is pretty clear about what lacks detail. I can open a separate issue if it helps but I'll capture some thoughts here:

1. It would be helpful to have an example of when/why it would be appropriate to use separate runtimeChunk vs when the default behavior should be left alone.
2. The docs state that test can be a function but don't describe the call signature of that function or give an example. Linking to the schema of the passed (module?) objects would be very helpful, I had to reverse engineer it to figure it out and I'm still not sure I got it right.
3. The docs for chunk boil down to "these are the 3 strings you can use" but don't define the terms initial vs async, or link to a deeper explanation. They don't explain when you'd use one vs the other, and there is no example.

I think the complaint was made elsewhere that the docs kind of presuppose that you've spent time with the predecessor (CommonsChunk) and if you don't already understand how webpack handles chunks, dynamic loading, etc, you don't have the context you need to understand SplitChunks. Maybe some of the shortfalls I list above would be addressed to some extent with a few opening paragraphs describing how modules relate to chunks, types of chunks, splitting best practices, etc.

I've done some reading in the past but I still find the whole thing kind of confusing. Good per-argument docs and examples can get me to "it works" but a deeper background could help me actually understand what's going on.