Documentation: Document the build process (Webpack)

[aduth]

Our build process, specifically the Webpack build, implements a fair bit of "magic" in order to define globals on the wp namespace, and to update import references to leverage these globals. We should document how this process works to educate those who might be interested in interfacing, modifying, or extending those behaviors.

https://github.com/WordPress/gutenberg/blob/master/webpack.config.js

Open questions:

• What should specifically be documented?
• Where should documentation be added?

cc @adamsilverstein @BE-Webdesign

[buzztone]

Our experience is that understanding and using JS build tools is the biggest initial barrier to getting WordPress Devs (with experience in PHP & jQuery) working with React in WordPress.

They need to get our build tools working on their local dev environment before starting to learn how we are writing our React based WordPress plugin. It's a big step for them & we've written a lot of very specific detailed documentation to help them through this process.

I'm also myself still working hard to understand the Gutenberg JS build tools (especially webpack but also babel). I've followed the package.json & webpack.config.js files in Gutenberg for some time. I've often struggled to find explanations for much of what I see there. These files also got increasingly complex over time & I've not found explanations for most of the changes.

It would be great if others like me could use the Gutenberg JS build tools as a starting or reference point for our projects. We currently use an ejected version of create-react-app but are increasingly referring to and adding parts from the Gutenberg build process which help us deal better with using React within WordPress.

Documentation of this area would hopefully allow me to understand:

• how the Gutenberg build process works
• why each package/option etc. is used
• when things are changed why they are changed.

[aduth]

I've followed the package.json & webpack.config.js files in Gutenberg for some time. I've often struggled to find explanations for much of what I see there. These files also got increasingly complex over time & I've not found explanations for most of the changes.

Highlighting this as it makes for a good argument that inline code documentation (i.e. comments) could, in some instances, serve better than a single separate document in order to reduce the "distance" between the code itself and the explanation of what it's intending to implement.

[krisgale-zz]

The converse of that^ is that there are no good, straightforward recipes/cookbooks available.

[gziolo]

We should make sure we document how one can take advantage of global variables to do some advanced work:

• GUTENBERG_BUNDLE_ANALYZER
• GUTENBERG_DEVTOOL
• GUTENBERG_LIVE_RELOAD_PORT

[gziolo]

We have some great progress on this one now that we abstracted webpack behind @wordpress/scripts package. We have documented the following:

• wp-scripts build command - https://github.com/WordPress/gutenberg/blob/master/packages/scripts/README.md#build
• wp-scripts start command - https://github.com/WordPress/gutenberg/blob/master/packages/scripts/README.md#start
• details about webpack config - https://github.com/WordPress/gutenberg/blob/master/packages/scripts/README.md#webpack-config
• there is tutorial how to setup your own project - https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/tutorials/javascript/js-build-setup.md

[gziolo]

We should make sure we document how one can take advantage of global variables to do some advanced work:

• GUTENBERG_BUNDLE_ANALYZER
• GUTENBERG_DEVTOOL
• GUTENBERG_LIVE_RELOAD_PORT

I created a follow-up issue for this part: #14492.