Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the documentation of wp scripts #14499

Closed
wants to merge 1 commit into from
Closed

Update the documentation of wp scripts #14499

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions packages/scripts/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,12 @@ This is how you execute the script with presented setup:

* `npm run build` - builds the code for production.

_Options_:

- `--WP_BUNDLE_ANALYZER` : This flag is used to enables utility that represents bundle content as convenient interactive zoomable treemap.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I understand it, these are interpreted by the wp scripts script as environment variables, not as options flags.

In other words, instead of:

wp scripts build --WP_BUNDLE_ANALYZER

I think the correct usage is...

WP_BUNDLE_ANALYZER=true wp scripts

Please correct me if I'm mistaken.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi! Thanks for comments!
I am not sure which way is correct to use --WP_BUNDLE_ANALYZER. But for the WP_LIVE_RELOAD_PORT, I have tried npm run build --WP_LIVE_RELOAD_PORT=12345 and npm run build WP_LIVE_RELOAD_PORT=12345. The first one works but the second one fails and the error message is

Insufficient number of arguments or no entry found. Alternatively, run 'webpack(-cli) --help' for usage info.

According to the documentation of Environment Variables and Environment Options in web pack, I think we can use the double hyphen to specify the variables including WP_BUNDLE_ANALYZER, WP_BUNDLE_ANALYZER and WP_DEVTOOL.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@aduth is correct, they should be rather provided before the command. Unless we replicate what @draganescu did for e2e tests and introduce new CLI args, convert them to env variables in node and filter them out before passing to webpack.

- `--WP_LIVE_RELOAD_PORT` : When present, the port on which live reload works when running watch mode will be changed. An example usage would be `npx wp-scripts build --WP_LIVE_RELOAD_PORT=1234`.
- `--WP_DEVTOOL` : A development tool is designated to control how source maps are generated. More information can be found [here](https://webpack.js.org/configuration/devtool/#devtool).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both WP_DEVTOOL and WP_LIVE_RELOAD_PORT get only applied in development mode - this means it works only with start script.


### `check-engines`

Checks if the current `node`, `npm` (or `yarn`) versions match the given [semantic version](https://semver.org/) ranges. If the given version is not satisfied, information about installing the needed version is printed and the program exits with an error code. It uses [check-node-version](https://www.npmjs.com/package/check-node-version) behind the scenes with the recommended configuration provided. You can specify your own ranges as described in [check-node-version docs](https://www.npmjs.com/package/check-node-version).
Expand Down Expand Up @@ -170,7 +176,7 @@ This is how you execute the script with presented setup:
Launches the End-To-End (E2E) test runner. It uses [Jest](https://jestjs.io/) behind the scenes and you are able to utilize all of its [CLI options](https://jestjs.io/docs/en/cli.html). You can also run `./node_modules/.bin/wp-scripts test:e2e --help` or `npm run test:e2e:help` (as presented below) to view all of the available options.

Writing tests can be done using Puppeteer API:

> [Puppeteer](https://pptr.dev/) is a Node library which provides a high-level API to control Chrome or Chromium over the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). Puppeteer runs [headless](https://developers.google.com/web/updates/2017/04/headless-chrome) by default, but can be configured to run full (non-headless) Chrome or Chromium.

_Example:_
Expand All @@ -196,7 +202,7 @@ We enforce that all tests run serially in the current process using [--runInBand

### `test-unit-js`

_Alias_: `test-unit-jest`
_Alias_: `test-unit-jest`

Launches the unit test runner. It uses [Jest](https://jestjs.io/) behind the scenes and you are able to utilize all of its [CLI options](https://jestjs.io/docs/en/cli.html). You can also run `./node_modules/.bin/wp-scripts test-unit-js --help` or `npm run test:unit:help` (as presented below) to view all of the available options. By default, it uses the set of recommended options defined in [@wordpress/jest-preset-default](https://www.npmjs.com/package/@wordpress/jest-preset-default) npm package. You can override them with your own options as described in [Jest documentation](https://jestjs.io/docs/en/configuration).

Expand Down
6 changes: 0 additions & 6 deletions packages/scripts/config/webpack.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,11 +96,7 @@ const config = {
],
},
plugins: [
// WP_BUNDLE_ANALYZER global variable enables utility that represents bundle content
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These inline comments should stay here.

// as convenient interactive zoomable treemap.
process.env.WP_BUNDLE_ANALYZER && new BundleAnalyzerPlugin(),
// WP_LIVE_RELOAD_PORT global variable changes port on which live reload works
// when running watch mode.
! isProduction && new LiveReloadPlugin( { port: process.env.WP_LIVE_RELOAD_PORT || 35729 } ),
].filter( Boolean ),
stats: {
Expand All @@ -109,8 +105,6 @@ const config = {
};

if ( ! isProduction ) {
// WP_DEVTOOL global variable controls how source maps are generated.
// See: https://webpack.js.org/configuration/devtool/#devtool.
config.devtool = process.env.WP_DEVTOOL || 'source-map';
}

Expand Down