From ad6afa3438127d951bb21c6914b1ce3eb6fa23b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Tue, 12 Mar 2019 10:23:36 +0100 Subject: [PATCH] Teach build and start commands to use Webpack default if none is provided (#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 * Simplify pushing to array Co-Authored-By: nosolosw * Fix externals docs * Use webpack instead of Webpack * Add Changelog entry --- packages/scripts/CHANGELOG.md | 6 +++++ packages/scripts/README.md | 42 ++++++++++++++++++++++++++++--- packages/scripts/scripts/build.js | 32 ++++++----------------- packages/scripts/scripts/start.js | 28 ++++++--------------- packages/scripts/utils/config.js | 18 +++++++++++-- packages/scripts/utils/index.js | 2 ++ 6 files changed, 78 insertions(+), 50 deletions(-) diff --git a/packages/scripts/CHANGELOG.md b/packages/scripts/CHANGELOG.md index c9373b3025f38f..b5455d3d98c8b9 100644 --- a/packages/scripts/CHANGELOG.md +++ b/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 diff --git a/packages/scripts/README.md b/packages/scripts/README.md index cc3f3b2b04a7c7..3ed6065b67532a 100644 --- a/packages/scripts/README.md +++ b/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`). +

Code is Poetry.

diff --git a/packages/scripts/scripts/build.js b/packages/scripts/scripts/build.js index ea2c7d303f2fa0..567a2405f2f1da 100644 --- a/packages/scripts/scripts/build.js +++ b/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 ); diff --git a/packages/scripts/scripts/start.js b/packages/scripts/scripts/start.js index db42c33ba447fb..d27fa3a5b0ec48 100644 --- a/packages/scripts/scripts/start.js +++ b/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 ); diff --git a/packages/scripts/utils/config.js b/packages/scripts/utils/config.js index 6be8ff91f0a4dd..0c5ed70c293ce2 100644 --- a/packages/scripts/utils/config.js +++ b/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, }; diff --git a/packages/scripts/utils/index.js b/packages/scripts/utils/index.js index b1a78d0d600c91..0837f7ab80996e 100644 --- a/packages/scripts/utils/index.js +++ b/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,