Scripts: Add official flags for build and start scripts

package.json

@@ -184,7 +184,7 @@
 		"worker-farm": "1.7.0"
 	},
 	"scripts": {
-		"analyze-bundles": "cross-env WP_BUNDLE_ANALYZER=1 npm run build",
+		"analyze-bundles": "npm run build -- --webpack-bundle-analyzer",
 		"prebuild": "npm run check-engines",
 		"clean:packages": "rimraf \"./packages/*/@(build|build-module|build-style)\"",
 		"clean:package-types": "tsc --build --clean",

packages/scripts/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+### New Feature
+
+- New `--webpack-no-externals` flag added to `build` and `start` scripts. It disables scripts' assets generation, and omits the list of default externals ([#22310](https://github.com/WordPress/gutenberg/pull/22310)).
+- New `--webpack-bundle-analyzer` flag added to `build` and `start` scripts. It enables visualization for the size of webpack output files with an interactive zoomable treemap ([#22310](https://github.com/WordPress/gutenberg/pull/22310)).
+- New `--webpack--devtool` flag added to `start` script. It controls how source maps are generated. See options at https://webpack.js.org/configuration/devtool/#devtool ([#22310](https://github.com/WordPress/gutenberg/pull/22310)).
+
 ### Enhancements
 
 - Bundle analysis in `build` script now runs with module concatenation disabled. This represents the size of individual modules more accurately, at the cost of not providing an exact byte-for-byte match to the final size in the production chunk.

packages/scripts/README.md

@@ -76,6 +76,10 @@ This is how you execute the script with presented setup:
 * `npm run build` - builds the code for production.
 * `npm run build:custom` - builds the code for production with two entry points and a custom output folder. Paths for custom entry points are relative to the project root.
 
+This script automatically use the optimized config but sometimes you may want to specify some custom options:
+* `--webpack-no-externals` – disables scripts' assets generation, and omits the list of default externals.
+* `--webpack-bundle-analyzer` – enables visualization for the size of webpack output files with an interactive zoomable treemap.
+
 #### Advanced information
 
 This script uses [webpack](https://webpack.js.org/) behind the scenes. It’ll look for a webpack config in the top-level directory of your package and will use it if it finds one. If none is found, it’ll use the default config provided by `@wordpress/scripts` packages. Learn more in the [Advanced Usage](#advanced-usage) section.
@@ -369,6 +373,11 @@ This is how you execute the script with presented setup:
 * `npm start` - starts the build for development.
 * `npm run start:custom` - starts the build for development which contains two entry points and a custom output folder. Paths for custom entry points are relative to the project root.
 
+This script automatically use the optimized config but sometimes you may want to specify some custom options:
+* `--webpack-no-externals` – disables scripts' assets generation, and omits the list of default externals.
+* `--webpack-bundle-analyzer` – enables visualization for the size of webpack output files with an interactive zoomable treemap.
+* `--webpack--devtool` – controls how source maps are generated. See options at https://webpack.js.org/configuration/devtool/#devtool.
+
 #### Advanced information
 
 This script uses [webpack](https://webpack.js.org/) behind the scenes. It’ll look for a webpack config in the top-level directory of your package and will use it if it finds one. If none is found, it’ll use the default config provided by `@wordpress/scripts` packages. Learn more in the [Advanced Usage](#advanced-usage) section.

packages/scripts/config/webpack.config.js

@@ -84,7 +84,10 @@ const config = {
 			new LiveReloadPlugin( {
 				port: process.env.WP_LIVE_RELOAD_PORT || 35729,
 			} ),
-		new DependencyExtractionWebpackPlugin( { injectPolyfill: true } ),
+		// WP_NO_EXTERNALS global variable controls whether scripts' assets get
+		// generated, and the default externals set.
+		process.env.WP_NO_EXTERNALS &&
+			new DependencyExtractionWebpackPlugin( { injectPolyfill: true } ),
 	].filter( Boolean ),
 	stats: {
 		children: false,

packages/scripts/scripts/build.js

@@ -7,9 +7,18 @@ const { sync: resolveBin } = require( 'resolve-bin' );
 /**
  * Internal dependencies
  */
-const { getWebpackArgs } = require( '../utils' );
+const { getWebpackArgs, hasArgInCLI } = require( '../utils' );
 
 process.env.NODE_ENV = process.env.NODE_ENV || 'production';
+
+if ( hasArgInCLI( '--webpack-no-externals' ) ) {
+	process.env.WP_NO_EXTERNALS = true;
+}
+
+if ( hasArgInCLI( '--webpack-bundle-analyzer' ) ) {
+	process.env.WP_BUNDLE_ANALYZER = true;
+}
+
 const { status } = spawn( resolveBin( 'webpack' ), getWebpackArgs(), {
 	stdio: 'inherit',
 } );

packages/scripts/scripts/start.js

@@ -7,11 +7,23 @@ const { sync: resolveBin } = require( 'resolve-bin' );
 /**
  * Internal dependencies
  */
-const { getWebpackArgs } = require( '../utils' );
+const { getArgFromCLI, getWebpackArgs, hasArgInCLI } = require( '../utils' );
+
+if ( hasArgInCLI( '--webpack-no-externals' ) ) {
+	process.env.WP_NO_EXTERNALS = true;
+}
+
+if ( hasArgInCLI( '--webpack-bundle-analyzer' ) ) {
+	process.env.WP_BUNDLE_ANALYZER = true;
+}
+
+if ( hasArgInCLI( '--webpack--devtool' ) ) {
+	process.env.WP_DEVTOOL = getArgFromCLI( '--webpack--devtool' );
+}
 
 const { status } = spawn(
 	resolveBin( 'webpack' ),
-	getWebpackArgs( [ '--watch' ] ),
+	getWebpackArgs().push( '--watch' ),
 	{
 		stdio: 'inherit',
 	}

packages/scripts/utils/config.js

@@ -48,16 +48,14 @@ const hasWebpackConfig = () =>
 
 /**
  * Converts CLI arguments to the format which webpack understands.
- * It allows to optionally pass some additional webpack CLI arguments.
  *
  * @see https://webpack.js.org/api/cli/#usage-with-config-file
  *
- * @param {?Array} additionalArgs The list of additional CLI arguments.
- *
  * @return {Array} The list of CLI arguments to pass to webpack CLI.
  */
-const getWebpackArgs = ( additionalArgs = [] ) => {
-	let webpackArgs = getArgsFromCLI();
+const getWebpackArgs = () => {
+	// Gets all args from CLI without those prefixed with `--webpack`.
+	let webpackArgs = getArgsFromCLI( [ '--webpack' ] );
 
 	const hasWebpackOutputOption =
 		hasArgInCLI( '-o' ) || hasArgInCLI( '--output' );
@@ -99,8 +97,6 @@ const getWebpackArgs = ( additionalArgs = [] ) => {
 		webpackArgs.push( '--config', fromConfigRoot( 'webpack.config.js' ) );
 	}
 
-	webpackArgs.push( ...additionalArgs );
-
 	return webpackArgs;
 };