Add a Webpacker v4 Upgrade Guide to docs

[connorshea]

This is based on my experience upgrading my Rails app to v4.0.0-rc.5, plus some content taken from #1755.

Credit to @justin808 for the original v4 upgrade guide this is based on.

[yvbeek]

@connorshea Great work! I think it would be good to mention javascript_packs_with_chunks_tag and stylesheet_packs_with_chunks_tag for people with a splitChunks configuration.

[connorshea]

@Zyphrax I don't fully understand that change unfortunately (I haven't really used the splitChunks config before), could you make a quick summary for me to include in the guide?

[yvbeek]

@connorshea SplitChunks is a Webpack feature that avoids duplicate code by combining shared dependencies and including them only once. If you have script A that uses (e.g.) React and you have script B that uses React, then normally Webpack will merge React into script A and again into script B.

With SplitChunks you can move the dependency (React) into a separate "chunk" and include it only once. A common configuration is to move all the node_modules dependencies into a vendors chunk. This will result in smaller js files and makes it easier for your browser to cache the relatively static vendor packages.

Maybe it is a good idea to include these lines from the Usage instructions:

If you are using the new Webpack 4 split chunks API, then consider using the javascript_packs_with_chunks_tag and stylesheet_packs_with_chunks_tag helpers, which create html tags for the packs and all the dependent chunks.

(I've added stylesheet_packs_with_chunks_tag to clarify what to use for stylesheets)

[connorshea]

@Zyphrax I've added a section on the change, does it look accurate to you? I've also added the config from #1755 (comment)

[yvbeek]

@connorshea Yeah that looks great. Maybe we should link the "splitChunks API" to https://webpack.js.org/plugins/split-chunks-plugin/ - that page provides some useful examples on how to use it.

[justin808]

Cursory look...LGTM.

[gauravtiwari]

@connorshea For split chunks, https://github.com/rails/webpacker/blob/c4cf2e99c2ae4dffdd2942c1d2282936b8aaf36e/docs/webpack.md#add-splitchunks-webpack-v4

We have an option in the environment to setup splitchunks (officially suggested - https://twitter.com/wSokra/status/969633336732905474) but obviously, it's customisable.

[arkhamRejek]

as an alternative to .browserlistrc file, I added it to the package that json like so.

can we add this in the read me as well for those of us who don't want more files in our project? or is that file absolutely necessary @gauravtiwari

[connorshea]

@gauravtiwari should I just copy-paste that section into this upgrade guide?

[gauravtiwari]

@arkhamRejek Sure, that's another option.

@connorshea Yes please, just mention that we support the basic implementation out of the box (above the section) however it's customisable if need to be.

Thanks :)

[connorshea]

@gauravtiwari you have access to my fork if you want to make that change and merge the PR ASAP, otherwise I can do it in about four hours :)

[connorshea]

Done, should be good to merge now :)

[yvbeek]

We probably should add a few lines about the pack namespaces (added in RC6) to the upgrade guide.

Namespaces for compiled packs in the public directory

• JavaScripts are stored under js
• Stylesheets are stored under css
• Other resources are stored under media

@connorshea Do you still have the fork for a quick addition like this?
Otherwise I'll add a pull request in the weekend.

[connorshea]

@Zyphrax you can feel free to handle it

[yvbeek]

See pull request: #1929