Add Webpack config docs (https://github.com/woocommerce/woocommerce-blocks/pull/3043)

* Add Webpack config docs

* Typo

* Add note that aliases make refactors easier

* Rewrite 'Relevant files' section of the build system docs

plugins/woocommerce-blocks/docs/contributors/README.md

@@ -10,4 +10,5 @@ This folder contains documentation for developers and contributors looking to ge
 | [JavaScript Testing](javascript-testing.md)                      | This doc explains how to run automated JavaScript tests.                            |
 | [Component Testing & Development (with Storybook)](storybook.md) | This doc explains how to use Storybook to test and develop components in isolation. |
 | [Block Script Assets](block-assets.md)                           | This doc explains how Block Script Assets are loaded and used.                      |
+| [JS build system](js-build-system.md)                            | This doc explains how JavaScript files are built.                                   |
 | [CSS build system](css-build-system.md)                          | This doc explains how CSS is built.                                                 |

plugins/woocommerce-blocks/docs/contributors/css-build-system.md

@@ -10,11 +10,13 @@ CSS files are built with Webpack, which gathers all SCSS files in the app and pr
 
 ## Legacy builds
 
-When building WC Blocks, a special build targeting old versions of WordPress is generated. Some blocks might not be available in that legacy build. For example, All Products and Filter blocks not being available on WP 5.2.
+In the past, when building WC Blocks, special builds targeting old versions of WordPress were generated. Those builds were named 'legacy builds' and might have a smaller set of blocks available. For example, All Products and Filter blocks were not available on WP 5.2.
 
-Legacy builds use their own CSS files with the suffix `-legacy`, this allows saving some bytes because non-legacy block styles are not included.
+Currently, those builds are no longer generated since WC Blocks doesn't support WP 5.2 anymore, but the built system is still in place in case we need legacy builds in the future.
 
-> Note: All components' styles are included in legacy CSS files no matter if they are only used by non-legacy blocks. See [#2818](https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/2818) for more details.
+Legacy builds used their own CSS files with the suffix `-legacy`, this allowed saving some bytes because non-legacy block styles were not included.
+
+> Note: All components' styles were included in legacy CSS files no matter if they were only used by non-legacy blocks. See [#2818](https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/2818) for more details.
 
 ## Right-to-left
 
@@ -24,6 +26,6 @@ All files described above are generated in a LTR version and a RTL version. The
 
 Webpack config is split between several files, some relevant ones for the CSS build system are:
 
--   [`webpack.config.js`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/webpack.config.js): file that exports the configs.
--   [`bin/webpack-configs.js`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/bin/webpack-configs.js): definition of the different configs used by Webpack.
--   [`bin/webpack-entries.js`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/bin/webpack-entries.js): entries used by Webpack definitions.
+-   [`webpack.config.js`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/webpack.config.js): Top level webpack config. Includes support for legacy and main build.
+    -   [`bin/webpack-configs.js`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/bin/webpack-configs.js): Code for generating each build config. This most closely resembles a classic webpack config - if you're looking for something, start here.
+        -   [`bin/webpack-entries.js`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/bin/webpack-entries.js): Code for generating [webpack `entry` definitions](https://webpack.js.org/concepts/entry-points/) and mapping source files to entry points. If you're adding a new block or module to the build, start here.

plugins/woocommerce-blocks/docs/contributors/js-build-system.md

@@ -0,0 +1,57 @@
+# JS build system
+
+WooCommerce Blocks uses Webpack to build the files that will be consumed by browsers. There are several different Webpack configs in order to build files for different contexts of the plugin. They can all be found in [`webpack.config.js`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/webpack.config.js#L148-L160), but this is a quick summary:
+
+-   `CoreConfig`: config for shared libraries like settings, blocks data or some HOCs and context.
+-   `MainConfig`: config that builds the JS files used by blocks in the editor and is responsible for registering the blocks in Gutenberg.
+-   `FrontendConfig`: config that builds the JS files used by blocks in the store frontend.
+-   `PaymentsConfig`: config that builds the JS files used by payment methods in the Cart and Checkout blocks.
+-   `StylingConfig`: config that builds CSS files. You can read more about it in the page [CSS build system](css-build-system.md).
+
+Details on each config can be found in [`webpack-configs.js`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/bin/webpack-configs.js). Entry points are declared in [`webpack-entries.js`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/bin/webpack-entries.js).
+
+## Environment variables
+
+Different builds are generated depending on the variable `NODE_ENV`. It can have two values: `production` or `development`. Production builds include tree-shaking, minification and other performance enhancements, while development builds are focused on development and include source maps. You can read more about [environment variables](https://webpack.js.org/guides/environment-variables/) in Webpack docs.
+
+## Babel
+
+Almost all our code is transpiled by Babel, this allows us to use the latest JavaScript technologies without having to worry about browser support. However, it's always a good practice to test the plugin in old browsers like IE11 to ensure nothing is broken.
+
+Some of the Babel plugins we use can be found in [`webpack-configs.js`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/bin/webpack-configs.js).
+
+## External scripts
+
+Several scripts are loaded as externals. That means that they are imported in WC Blocks as any other package, but instead of being bundled in our built files, they are loaded from an external file. We use [`@wordpress/dependency-extraction-webpack-plugin`](https://developer.wordpress.org/block-editor/packages/packages-dependency-extraction-webpack-plugin/) to automatize dependency extraction for common WP scripts.
+
+## Aliases
+
+There are several aliases for internal imports which make importing files across the file tree easier. Instead of having to write a long relative path, they allow writing an alias:
+
+```diff
+-import { useStoreCartCoupons } from '../../../../base/hooks';
++import { useStoreCartCoupons } from '@woocommerce/base-hooks';
+```
+
+Aliases also ease refactors because imports no longer depend on the exact location of the file.
+
+All available aliases can be found in [`webpack-helpers.js`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/bin/webpack-helpers.js#L26-L84).
+
+## Styling
+
+CSS builds follow a separate path from JS builds, more details can be found in the [CSS build system](css-build-system.md).
+
+## Legacy builds
+
+In the past, when building WC Blocks, special builds targeting old versions of WordPress were generated. Those builds were named 'legacy builds' and might have a smaller set of blocks available. For example, All Products and Filter blocks were not available on WP 5.2.
+
+There were legacy builds of the `MainConfig`, `FrontendConfig` and `StylingConfig`. Currently, those builds are no longer generated since WC Blocks doesn't support WP 5.2 anymore, but the built system is still in place in case legacy builds are needed in the future.
+
+## Relevant files
+
+Webpack config is split between several files:
+
+-   [`webpack.config.js`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/webpack.config.js): Top level webpack config. Includes support for legacy and main build.
+    -   [`bin/webpack-configs.js`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/bin/webpack-configs.js): Code for generating each build config. This most closely resembles a classic webpack config - if you're looking for something, start here.
+        -   [`bin/webpack-entries.js`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/bin/webpack-entries.js): Code for generating [webpack `entry` definitions](https://webpack.js.org/concepts/entry-points/) and mapping source files to entry points. If you're adding a new block or module to the build, start here.
+    -   [`bin/webpack-helpers.js`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/main/bin/webpack-helpers.js): Includes utils to load external code at run time, e.g. some dependencies from Woo and WordPress core.

plugins/woocommerce-blocks/webpack.config.js

@@ -53,8 +53,7 @@ const FrontendConfig = {
 };
 
 /**
- * This is a temporary config for building the payment methods integration script until it can be
- * moved into the payment extension(s).
+ * Config for building the payment methods integration scripts.
  */
 const PaymentsConfig = {
 	...sharedConfig,