Scripts: Document and simplify changing file entry and output of build scripts

packages/scripts/CHANGELOG.md

@@ -1,3 +1,9 @@
+## Master
+
+### New Features
+
+- The `build` and `start` commands supports simplified syntax for multiple entry points: `wp-scripts build entry-one.js entry-two.js` ([15982](https://github.com/WordPress/gutenberg/pull/15982)).
+
 ## 3.3.0 (2019-06-12)
 
 ### New Features

packages/scripts/README.md

@@ -49,14 +49,16 @@ _Example:_
 ```json
 {
 	"scripts": {
-		"build": "wp-scripts build"
+		"build": "wp-scripts build",
+		"build:custom": "wp-scripts build entry-one.js entry-two.js --output-path=custom"
 	}
 }
 ```
 
 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.
 
 #### Advanced information
 
@@ -198,14 +200,16 @@ _Example:_
 ```json
 {
 	"scripts": {
-		"start": "wp-scripts start"
+		"start": "wp-scripts start",
+		"start:custom": "wp-scripts start entry-one.js entry-two.js --output-path=custom"
 	}
 }
 ```
 
 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.
 
 #### Advanced information
 

packages/scripts/utils/cli.js

@@ -27,7 +27,9 @@ const getArgFromCLI = ( arg ) => {
 
 const hasArgInCLI = ( arg ) => getArgFromCLI( arg ) !== undefined;
 
-const hasFileArgInCLI = () => minimist( getArgsFromCLI() )._.length > 0;
+const getFileArgsFromCLI = () => minimist( getArgsFromCLI() )._;
+
+const hasFileArgInCLI = () => getFileArgsFromCLI().length > 0;
 
 const handleSignal = ( signal ) => {
 	if ( signal === 'SIGKILL' ) {
@@ -83,6 +85,7 @@ const spawnScript = ( scriptName, args = [] ) => {
 module.exports = {
 	getArgFromCLI,
 	getArgsFromCLI,
+	getFileArgsFromCLI,
 	hasArgInCLI,
 	hasFileArgInCLI,
 	spawnScript,

packages/scripts/utils/config.js

@@ -1,7 +1,12 @@
+/**
+ * External dependencies
+ */
+const { basename } = require( 'path' );
+
 /**
  * Internal dependencies
  */
-const { hasArgInCLI, getArgsFromCLI } = require( './cli' );
+const { getArgsFromCLI, getFileArgsFromCLI, hasArgInCLI, hasFileArgInCLI } = require( './cli' );
 const { fromConfigRoot, hasProjectFile } = require( './file' );
 const { hasPackageProp } = require( './package' );
 
@@ -22,12 +27,57 @@ const hasWebpackConfig = () => hasArgInCLI( '--config' ) ||
 	hasProjectFile( 'webpack.config.js' ) ||
 	hasProjectFile( 'webpack.config.babel.js' );
 
+/**
+ * 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 = [] ) => {
-	const webpackArgs = getArgsFromCLI();
+	let webpackArgs = getArgsFromCLI();
+
+	const hasWebpackOutputOption = hasArgInCLI( '-o' ) || hasArgInCLI( '--output' );
+	if ( hasFileArgInCLI() && ! hasWebpackOutputOption ) {
+		/**
+		 * Converts a path to the entry format supported by webpack, e.g.:
+		 * `./entry-one.js` -> `entry-one=./entry-one.js`
+		 * `entry-two.js` -> `entry-two=./entry-two.js`
+		 *
+		 * @param {string} path The path provided.
+		 *
+		 * @return {string} The entry format supported by webpack.
+		 */
+		const pathToEntry = ( path ) => {
+			const entry = basename( path, '.js' );
+
+			if ( ! path.startsWith( './' ) ) {
+				path = './' + path;
+			}
+
+			return [ entry, path ].join( '=' );
+		};
+
+		// The following handles the support for multiple entry points in webpack, e.g.:
+		// `wp-scripts build one.js custom=./two.js` -> `webpack one=./one.js custom=./two.js`
+		webpackArgs = webpackArgs.map( ( cliArg ) => {
+			if ( getFileArgsFromCLI().includes( cliArg ) && ! cliArg.includes( '=' ) ) {
+				return pathToEntry( cliArg );
+			}
+
+			return cliArg;
+		} );
+	}
+
 	if ( ! hasWebpackConfig() ) {
 		webpackArgs.push( '--config', fromConfigRoot( 'webpack.config.js' ) );
 	}
+
 	webpackArgs.push( ...additionalArgs );
+
 	return webpackArgs;
 };
 

packages/scripts/utils/index.js

@@ -4,6 +4,7 @@
 const {
 	getArgFromCLI,
 	getArgsFromCLI,
+	getFileArgsFromCLI,
 	hasArgInCLI,
 	hasFileArgInCLI,
 	spawnScript,
@@ -29,6 +30,7 @@ module.exports = {
 	fromConfigRoot,
 	getArgFromCLI,
 	getArgsFromCLI,
+	getFileArgsFromCLI,
 	getWebpackArgs,
 	hasBabelConfig,
 	hasArgInCLI,