From 3ddf4dd929d894d7b771b52df2d0e7dffc8a8083 Mon Sep 17 00:00:00 2001 From: kmanijak Date: Fri, 30 Dec 2022 14:17:42 +0100 Subject: [PATCH] Update the docs with more details about external dependencies and wordpress-components alias (https://github.com/woocommerce/woocommerce-blocks/pull/8052) --- .../contributing/javascript-build-system.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/plugins/woocommerce-blocks/docs/contributors/contributing/javascript-build-system.md b/plugins/woocommerce-blocks/docs/contributors/contributing/javascript-build-system.md index 9b0298ad36c..d91e0d71ed0 100644 --- a/plugins/woocommerce-blocks/docs/contributors/contributing/javascript-build-system.md +++ b/plugins/woocommerce-blocks/docs/contributors/contributing/javascript-build-system.md @@ -15,6 +15,7 @@ WooCommerce Blocks uses Webpack to build the files that will be consumed by brow - `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. +- `ExtensionsConfig`: config that builds extension integrations. - `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/trunk/bin/webpack-configs.js). Entry points are declared in [`webpack-entries.js`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/trunk/bin/webpack-entries.js). @@ -31,7 +32,22 @@ Some of the Babel plugins we use can be found in [`webpack-configs.js`](https:// ## 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. +Several scripts are loaded as externals. That means that they can be imported in WooCommerce Blocks as any other package, but instead of being bundled in our built files, they are loaded from an external file provided by WordPress (or Gutenberg, if enabled). + +[`@wordpress/dependency-extraction-webpack-plugin`](https://developer.wordpress.org/block-editor/packages/packages-dependency-extraction-webpack-plugin/) is used to automatize dependency extraction for common WP scripts. + +In practice, that means the dependency version is: + +- deterministic when running WooCommerce Blocks in isolation (e.g. unit tests). In this case, the dependency will have a version as stated in `package.json`, +- non-deterministic when run in the WordPress ecosystem. Depending on the WordPress or Gutenberg version the user has installed, the version of external dependencies may also vary. + +[`@wordpress/dependency-extraction-webpack-plugin`](https://developer.wordpress.org/block-editor/packages/packages-dependency-extraction-webpack-plugin/) script is applied to each of the build processes: Core, Main, Frontend, Payments, Extensions. + +### `wordpress-components` alias + +`@wordpress/components` is one of the dependencies that gets externalized by the plugin. You can see the external `components.min.js` file being loaded on the Editor pages containing blocks that depend on the `@wordpress/components`, while the code is not bundled within WooCommerce Blocks files. + +For optimization purposes, there's a `wordpress-components` alias created, which is used in the frontend code. Thanks to that, the dependency omits the Dependency Extraction Plugin and behaves like any other dependency: it's tree-shaken and only the necessary code is bundled with the block. That allows us to avoid loading the whole `@wordpress/components` on the frontend pages. ## Aliases