Teach build and start commands to use Webpack default if none is prov…

…ided (#13877)

* Use a default webpack config if none is provided

* Extract webpack utils from build command

* Update start command

* Add docs

* Add Webpack documentation

* Add example of how to overwrite the default plugins

* Do not export hasWebpackConfig

as it is not used anywhere else.

* Always pass webpack CLI args to command

* Update README

* Remove section on extending the default webpack config file

* Simplify array passing

Co-Authored-By: nosolosw <[email protected]>

* Simplify pushing to array

Co-Authored-By: nosolosw <[email protected]>

* Fix externals docs

* Use webpack instead of Webpack

* Add Changelog entry

packages/scripts/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 3.1.0 (unreleased)
+
+## New features
+
+- The `build` and `start` commands will use a default webpack config if none is provided.
+
 ## 3.0.0 (2019-03-06)
 
 ### Breaking Changes

packages/scripts/README.md

@@ -38,7 +38,7 @@ _Example:_
 
 ### `build`
 
-Builds the code to the designated `build` folder in the configuration file. It correctly bundles code in production mode and optimizes the build for the best performance. Your code is ready to be deployed. It uses [Webpack](https://webpack.js.org/) behind the scenes and you still need to provide your own config as described in the [documentation](https://webpack.js.org/concepts/configuration/).
+Transforms your code according the configuration provided so it's ready for production and optimized for the best performance. It uses [webpack](https://webpack.js.org/) behind the scenes. It'll lookup 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 bundled within `@wordpress/scripts` packages. Learn more in the "webpack config" section.
 
 _Example:_
 
@@ -51,8 +51,8 @@ _Example:_
 ```
 
 This is how you execute the script with presented setup:
-* `npm run build` - builds the code for production.
 
+* `npm run build` - builds the code for production.
 
 ### `check-engines`
 
@@ -69,6 +69,7 @@ _Example:_
 ```
 
 This is how you execute the script with presented setup:
+
 * `npm run check-engines` - checks installed version of `node` and `npm`.
 
 ### `check-licenses`
@@ -107,6 +108,7 @@ _Example:_
 ```
 
 This is how you execute the script with presented setup:
+
 * `npm run lint:js` - lints JavaScript files in the entire project's directories.
 
 ### `lint-pkg-json`
@@ -124,6 +126,7 @@ _Example:_
 ```
 
 This is how you execute those scripts using the presented setup:
+
 * `npm run lint:pkg-json` - lints `package.json` file in the project's root folder.
 
 ### `lint-style`
@@ -141,11 +144,12 @@ _Example:_
 ```
 
 This is how you execute the script with presented setup:
+
 * `npm run lint:css` - lints CSS files in the whole project's directory.
 
 ### `start`
 
-Builds the code for development to the designated `build` folder in the configuration file. The script will automatically rebuild if you make changes to the code. You will see the build errors in the console. It uses [Webpack](https://webpack.js.org/) behind the scenes and you still need to provide your own config as described in the [documentation](https://webpack.js.org/concepts/configuration/).
+Transforms your code according the configuration provided so it's ready for development. The script will automatically rebuild if you make changes to the code, and you will see the build errors in the console. It uses [webpack](https://webpack.js.org/) behind the scenes. It'll lookup 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 bundled within `@wordpress/scripts` packages. Learn more in the "webpack config" section.
 
 _Example:_
 
@@ -158,6 +162,7 @@ _Example:_
 ```
 
 This is how you execute the script with presented setup:
+
 * `npm start` - starts the build for development.
 
 ### `test-e2e`
@@ -180,6 +185,7 @@ _Example:_
 ```
 
 This is how you execute those scripts using the presented setup:
+
 * `npm run test:e2e` - runs all unit tests.
 * `npm run test:e2e:help` - prints all available options to configure unit tests runner.
 
@@ -207,8 +213,38 @@ _Example:_
 ```
 
 This is how you execute those scripts using the presented setup:
+
 * `npm run test:unit` - runs all unit tests.
 * `npm run test:unit:help` - prints all available options to configure unit tests runner.
 * `npm run test:unit:watch` - runs all unit tests in the watch mode.
 
+## webpack config
+
+The `build` and `start` commands use [webpack](https://webpack.js.org/) behind the scenes. webpack is a tool that helps you transform your code into something else. For example: it can take code written in ESNext and output ES5 compatible code that is minified for production.
+
+### Default webpack config
+
+`@wordpress/scripts` bundles the default webpack config used as a base by the WordPress editor. These are the defaults:
+
+* [Entry](https://webpack.js.org/configuration/entry-context/#entry): `src/index.js`
+* [Output](https://webpack.js.org/configuration/output): `build/index.js`
+* [Externals](https://webpack.js.org/configuration/externals). These are libraries that are to be found in the global scope:
+
+Package | Input syntax | Output
+--- | --- | ---
+React | `import x from React;` | `var x = window.React.x;`
+ReactDOM | `import x from ReactDOM;` | `var x = window.ReactDOM.x;`
+moment | `import x from moment;` | `var x = window.moment.x;`
+jQuery | `import x from jQuery;` | `var x = window.jQuery.x;`
+lodash | `import x from lodash;` | `var x = window.lodash.x;`
+lodash-es | `import x from lodash-es;` | `var x = window.lodash.x;`
+WordPress packages | `import x from '@wordpress/package-name` | `var x = window.wp.packageName.x`
+
+### Provide your own webpack config
+
+Should there be any situation where you want to provide your own webpack config, you can do so. The `build` and `start` commands will use your provided file when:
+
+* the command receives a `--config` argument. Example: `wp-scripts build --config my-own-webpack-config.js`.
+* there is a file called `webpack.config.js` or `webpack.config.babel.js` in the top-level directory of your package (at the same level than your `package.json`).
+
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

packages/scripts/scripts/build.js

@@ -7,28 +7,12 @@ const { sync: resolveBin } = require( 'resolve-bin' );
 /**
  * Internal dependencies
  */
-const {
-	getCliArgs,
-	hasCliArg,
-	hasProjectFile,
-} = require( '../utils' );
+const { getWebpackArgs } = require( '../utils' );
 
-const hasWebpackConfig = hasCliArg( '--config' ) ||
-	hasProjectFile( 'webpack.config.js' ) ||
-	hasProjectFile( 'webpack.config.babel.js' );
-
-if ( hasWebpackConfig ) {
-	// Sets environment to production.
-	process.env.NODE_ENV = 'production';
-
-	const { status } = spawn(
-		resolveBin( 'webpack' ),
-		getCliArgs(),
-		{ stdio: 'inherit' }
-	);
-	process.exit( status );
-} else {
-	// eslint-disable-next-line no-console
-	console.log( 'Webpack config file is missing.' );
-	process.exit( 1 );
-}
+process.env.NODE_ENV = 'production';
+const { status } = spawn(
+	resolveBin( 'webpack' ),
+	getWebpackArgs(),
+	{ stdio: 'inherit' }
+);
+process.exit( status );

packages/scripts/scripts/start.js

@@ -7,25 +7,11 @@ const { sync: resolveBin } = require( 'resolve-bin' );
 /**
  * Internal dependencies
  */
-const {
-	getCliArgs,
-	hasCliArg,
-	hasProjectFile,
-} = require( '../utils' );
+const { getWebpackArgs } = require( '../utils' );
 
-const hasWebpackConfig = hasCliArg( '--config' ) ||
-	hasProjectFile( 'webpack.config.js' ) ||
-	hasProjectFile( 'webpack.config.babel.js' );
-
-if ( hasWebpackConfig ) {
-	const { status } = spawn(
-		resolveBin( 'webpack' ),
-		[ '--watch', ...getCliArgs() ],
-		{ stdio: 'inherit' }
-	);
-	process.exit( status );
-} else {
-	// eslint-disable-next-line no-console
-	console.log( 'Webpack config file is missing.' );
-	process.exit( 1 );
-}
+const { status } = spawn(
+	resolveBin( 'webpack' ),
+	getWebpackArgs( [ '--watch' ] ),
+	{ stdio: 'inherit' }
+);
+process.exit( status );

packages/scripts/utils/config.js

@@ -1,8 +1,8 @@
 /**
  * Internal dependencies
  */
-const { hasCliArg } = require( './cli' );
-const { hasProjectFile } = require( './file' );
+const { hasCliArg, getCliArgs } = require( './cli' );
+const { fromConfigRoot, hasProjectFile } = require( './file' );
 const { hasPackageProp } = require( './package' );
 
 const hasBabelConfig = () =>
@@ -17,7 +17,21 @@ const hasJestConfig = () =>
 	hasProjectFile( 'jest.config.json' ) ||
 	hasPackageProp( 'jest' );
 
+const hasWebpackConfig = () => hasCliArg( '--config' ) ||
+	hasProjectFile( 'webpack.config.js' ) ||
+	hasProjectFile( 'webpack.config.babel.js' );
+
+const getWebpackArgs = ( additionalArgs = [] ) => {
+	const webpackArgs = getCliArgs();
+	if ( ! hasWebpackConfig() ) {
+		webpackArgs.push( '--config', fromConfigRoot( 'webpack.config.js' ) );
+	}
+	webpackArgs.push( ...additionalArgs );
+	return webpackArgs;
+};
+
 module.exports = {
+	getWebpackArgs,
 	hasBabelConfig,
 	hasJestConfig,
 };

packages/scripts/utils/index.js

@@ -8,6 +8,7 @@ const {
 	spawnScript,
 } = require( './cli' );
 const {
+	getWebpackArgs,
 	hasBabelConfig,
 	hasJestConfig,
 } = require( './config' );
@@ -27,6 +28,7 @@ module.exports = {
 	fromConfigRoot,
 	getCliArg,
 	getCliArgs,
+	getWebpackArgs,
 	hasBabelConfig,
 	hasCliArg,
 	hasJestConfig,