Một ví dụ cài đặt wp-scripts build (ok)

https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/

{
    "scripts": {
        "build": "wp-scripts build",
        "check-engines": "wp-scripts check-engines",
        "check-licenses": "wp-scripts check-licenses",
        "format": "wp-scripts format",
        "lint:css": "wp-scripts lint-style",
        "lint:js": "wp-scripts lint-js",
        "lint:md:docs": "wp-scripts lint-md-docs",
        "lint:md:js": "wp-scripts lint-md-js",
        "lint:pkg-json": "wp-scripts lint-pkg-json",
        "packages-update": "wp-scripts packages-update",
        "start": "wp-scripts start",
        "test:e2e": "wp-scripts test-e2e",
        "test:unit": "wp-scripts test-unit-js"
    }
}

@wordpress/scripts Editarrow-up-right

This is a collection of reusable scripts tailored for WordPress development. For convenience, every tool provided in this package comes with an integrated recommended configuration.

When working seamlessly, sophisticated command-line interfaces help to turn work with a project into a more pleasant experience. However, it’s a misleading assumption that developers can easily pick the proper tools in the first place and then ensure that they play along with each other, including all their extensions. Besides, it’s still not enough because developers are left on their own to keep all configurations and dependent tools up to date. This problem multiplies when they support more than one project which shares the same setup.

Fortunately, there is a pattern that can simplify maintainers life – reusable scripts. The idea boils down to moving all the necessary configurations and scripts to one single tool dependency. In most cases, it should be possible to accomplish all tasks using the default settings, but some customization is allowed, too. With all that in place, updating all projects should become a very straightforward task.

This package is inspired by react-scriptsarrow-up-right and kcd-scriptsarrow-up-right.

You only need to install one npm module:

1

npm install @wordpress/scripts --save-dev

Note: This package requires Node.js 12.13.0 or later, and npm 6.9.0 or later. It is not compatible with older versions.

Top ↑arrow-up-right

This package offers a command-line interface and exposes a binary called wp-scripts so you can call it directly with npx – an npm package runner. However, this module is designed to be configured using the scripts section in the package.json file of your project. This comprehensive example demonstrates the most of the capabilities included.

Example:

1234567891011121314151617

{ "scripts": { "build": "wp-scripts build", "check-engines": "wp-scripts check-engines", "check-licenses": "wp-scripts check-licenses", "format": "wp-scripts format", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "lint:md:docs": "wp-scripts lint-md-docs", "lint:md:js": "wp-scripts lint-md-js", "lint:pkg-json": "wp-scripts lint-pkg-json", "packages-update": "wp-scripts packages-update", "start": "wp-scripts start", "test:e2e": "wp-scripts test-e2e", "test:unit": "wp-scripts test-unit-js" }}

Expand full source codearrow-up-right

It might also be a good idea to get familiar with the JavaScript Build Setup tutorialarrow-up-right for setting up a development environment to use ESNext syntax. It gives a very in-depth explanation of how to use the buildarrow-up-right and startarrow-up-right scripts.

Top ↑arrow-up-right

To update an existing project to a new version of @wordpress/scripts, open the changelogarrow-up-right, find the version you’re currently on (check package.json in the top-level directory of your project), and apply the migration instructions for the newer versions.

In most cases bumping the @wordpress/scripts version in package.json and running npm install in the root folder of your project should be enough, but it’s good to check the changelogarrow-up-right for potential breaking changes. There is also packages-update script included in this package that aims to automate the process of updating WordPress dependencies in your projects.

We commit to keeping the breaking changes minimal so you can upgrade @wordpress/scripts as seamless as possible.

Top ↑arrow-up-right

Transforms your code according the configuration provided so it’s ready for production and optimized for the best performance. The entry point for your project’s code should be located in src/index.js. The output generated will be written to build/index.js. This script exits after producing a single build. For incremental builds, better suited for development, see the startarrow-up-right script.

Example:

123456

{ "scripts": { "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.

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 #Advanced information

This script uses webpackarrow-up-right 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 Usagearrow-up-right section.

Top ↑arrow-up-right

Checks if the current node, npm (or yarn) versions match the given semantic versionarrow-up-right ranges. If the given version is not satisfied, information about installing the needed version is printed and the program exits with an error code.

Example:

12345

{ "scripts": { "check-engines": "wp-scripts check-engines" }}

This is how you execute the script with presented setup:

  • npm run check-engines – checks installed version of node and npm.

Top ↑arrow-up-right

Advanced information #Advanced information

It uses check-node-versionarrow-up-right behind the scenes with the recommended configuration provided. The default requirements are set to the same Node.js and npm versions as listed in the installationarrow-up-right section for this package. You can specify your own ranges as described in check-node-version docsarrow-up-right. Learn more in the Advanced Usagearrow-up-right section.

Top ↑arrow-up-right

Validates that all dependencies of a project are compatible with the project’s own license.

Example:

12345

{ "scripts": { "check-licenses": "wp-scripts check-licenses --prod --gpl2 --ignore=abab" }}

Flags:

  • --prod (or --production): When present, validates only dependencies and not devDependencies

  • --dev (or --development): When present, validates only devDependencies and not dependencies

  • --ignore=a,b,c: A comma-separated set of package names to ignore for validation. This is intended to be used primarily in cases where a dependency’s license field is malformed. It’s assumed that any ignored package argument would be manually vetted for compatibility by the project owner.

Top ↑arrow-up-right

It helps to enforce coding style guidelines for your files (JavaScript, YAML) by formatting source code in a consistent way.

Example:

123456

{ "scripts": { "format": "wp-scripts format", "format:src": "wp-scripts format ./src" }}

This is how you execute the script with presented setup:

  • npm run format – formats files in the entire project’s directories.

  • npm run format:src – formats files in the project’s src subfolder’s directories.

When you run commands similar to the npm run format:src example above, you can provide a file, a directory, or glob syntax or any combination of them.

By default, files located in build, node_modules, and vendor folders are ignored. You can customize the list of ignored files and directories by adding them to a .prettierignore file in your project.

Top ↑arrow-up-right

Helps enforce coding style guidelines for your JavaScript files.

Example:

123456

{ "scripts": { "lint:js": "wp-scripts lint-js", "lint:js:src": "wp-scripts lint-js ./src" }}

This is how you execute the script with presented setup:

  • npm run lint:js – lints JavaScript files in the entire project’s directories.

  • npm run lint:js:src – lints JavaScript files in the project’s src subfolder’s directories.

When you run commands similar to the npm run lint:js:src example above, you can provide a file, a directory, or glob syntax or any combination of them. See more examplesarrow-up-right.

By default, files located in build, node_modules, and vendor folders are ignored.

Top ↑arrow-up-right

Advanced information #Advanced information

It uses eslintarrow-up-right with the set of recommended rules defined in @wordpress/eslint-pluginarrow-up-right npm package. You can override default rules with your own as described in eslint docsarrow-up-right. Learn more in the Advanced Usagearrow-up-right section.

Top ↑arrow-up-right

Helps enforce standards for your package.json files.

Example:

123456

{ "scripts": { "lint:pkg-json": "wp-scripts lint-pkg-json", "lint:pkg-json:src": "wp-scripts lint-pkg-json ./src" }}

This is how you execute those scripts using the presented setup:

  • npm run lint:pkg-json – lints package.json file in the entire project’s directories.

  • npm run lint:pkg-json:src – lints package.json file in the project’s src subfolder’s directories.

When you run commands similar to the npm run lint:pkg-json:src example above, you can provide one or multiple directories to scan as well. See more examplesarrow-up-right.

By default, files located in build, node_modules, and vendor folders are ignored.

Top ↑arrow-up-right

Advanced information #Advanced information

It uses npm-package-json-lintarrow-up-right with the set of recommended rules defined in @wordpress/npm-package-json-lint-configarrow-up-right npm package. You can override default rules with your own as described in npm-package-json-lint wikiarrow-up-right. Learn more in the Advanced Usagearrow-up-right section.

Top ↑arrow-up-right

Uses markdownlint to lint the markup of markdown files to enforce standards.

Example:

12345

{ "scripts": { "lint:md:docs": "wp-scripts lint-md-docs" }}

This is how you execute the script with presented setup:

  • npm run lint:md:docs – lints markdown files in the entire project’s directories.

By default, files located in build, node_modules, and vendor folders are ignored.

Top ↑arrow-up-right

Advanced information #Advanced information

It uses markdownlintarrow-up-right with the .markdownlint.jsonarrow-up-right configuration. This configuration tunes the linting rules to match WordPress standard, you can override with your own config, see markdownlint-cliarrow-up-right for command-line parameters.

Top ↑arrow-up-right

Uses ESLint to lint the source included in markdown files to enforce standards for JS code.

Example:

12345

{ "scripts": { "lint:md:js": "wp-scripts lint-md-js" }}

This is how you execute the script with presented setup:

  • npm run lint:md:js – lints markdown files in the entire project’s directories.

By default, files located in build, node_modules, and vendor folders are ignored.

Top ↑arrow-up-right

Advanced information #Advanced information

It uses eslint-plugin-markdownarrow-up-right with the .eslintrc-md.jsarrow-up-right configuration. This configuration tunes down the linting rules since documentation often includes just snippets of code. It is recommended to use the markdown linting as a check, but not necessarily a blocker since it might report more false errors.

Top ↑arrow-up-right

Helps enforce coding style guidelines for your style files.

Example:

123456

{ "scripts": { "lint:style": "wp-scripts lint-style", "lint:css:src": "wp-scripts lint-style 'src/**/*.css'" }}

This is how you execute the script with presented setup:

  • npm run lint:style – lints CSS and SCSS files in the entire project’s directories.

  • npm run lint:css:src – lints only CSS files in the project’s src subfolder’s directories.

When you run commands similar to the npm run lint:css:src example above, be sure to include the quotation marks around file globs. This ensures that you can use the powers of globbyarrow-up-right (like the ** globstar) regardless of your shell. See more examplesarrow-up-right.

By default, files located in build, node_modules, and vendor folders are ignored.

Top ↑arrow-up-right

Advanced information #Advanced information

It uses stylelintarrow-up-right with the @wordpress/stylelint-configarrow-up-right configuration per the WordPress CSS Coding Standardsarrow-up-right. You can override them with your own rules as described in stylelint user guidearrow-up-right. Learn more in the Advanced Usagearrow-up-right section.

Top ↑arrow-up-right

Updates the WordPress packages used in the project to their latest version.

Example:

123456

{ "scripts": { "packages-update": "wp-scripts packages-update", "postpackages-update": "npm run build" }}

Top ↑arrow-up-right

Advanced information #Advanced information

The command checks which packages whose name starts with @wordpress/ are used in the project by reading the package.json file, and then executes npm install @wordpress/package1@latest @wordpress/package2@latest ... --save to change the package versions to the latest one.

Top ↑arrow-up-right

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. The entry point for your project’s code should be located in src/index.js. The output generated will be written to build/index.js. For single builds, better suited for production, see the buildarrow-up-right script.

Example:

123456

{ "scripts": { "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.

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.

Top ↑arrow-up-right

Advanced information #Advanced information

This script uses webpackarrow-up-right 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 Usagearrow-up-right section.

Top ↑arrow-up-right

Launches the End-To-End (E2E) test runner. Writing tests can be done using the Jest APIarrow-up-right in combination with the Puppeteer APIarrow-up-right:

Jestarrow-up-right is a delightful JavaScript Testing Framework with a focus on simplicity.

Puppeteerarrow-up-right is a Node library which provides a high-level API to control Chrome or Chromium over the DevTools Protocolarrow-up-right. Puppeteer runs headlessarrow-up-right by default, but can be configured to run full (non-headless) Chrome or Chromium.

Example:

1234567

{ "scripts": { "test:e2e": "wp-scripts test-e2e", "test:e2e:help": "wp-scripts test-e2e --help", "test:e2e:debug": "wp-scripts --inspect-brk test-e2e --puppeteer-devtools" }}

This is how you execute those scripts using the presented setup:

  • npm run test:e2e – runs all e2e tests.

  • npm run test:e2e:help – prints all available options to configure e2e test runner.

  • npm run test-e2e -- --puppeteer-interactive – runs all e2e tests interactively.

  • npm run test-e2e FILE_NAME -- --puppeteer-interactive – runs one test file interactively.

  • npm run test-e2e:watch -- --puppeteer-interactive – runs all tests interactively and watch for changes.

  • npm run test-e2e:debug – runs all tests interactively and enables debugging testsarrow-up-right.

Jest will look for test files with any of the following popular naming conventions:

  • Files with .js (or .ts) suffix at any level of depth in spec folders.

  • Files with .spec.js (or .spec.ts) suffix.

This script automatically detects the best config to start Puppeteer but sometimes you may need to specify custom options:

  • You can add a jest-puppeteer.config.js at the root of the project or define a custom path using JEST_PUPPETEER_CONFIG environment variable. Check jest-puppeteerarrow-up-right for more details.

We enforce that all tests run serially in the current process using –runInBandarrow-up-right Jest CLI option to avoid conflicts between tests caused by the fact that they share the same WordPress instance.

Top ↑arrow-up-right

Advanced information #Advanced information

It uses Jestarrow-up-right behind the scenes and you are able to use all of its CLI optionsarrow-up-right. You can also run ./node_modules/.bin/wp-scripts test:e2e --help or npm run test:e2e:help (as mentioned above) to view all of the available options. Learn more in the Advanced Usagearrow-up-right section.

Should there be any situation where you want to provide your own Jest config, you can do so.

  • the command receives a --config argument. Example: wp-scripts test-e2e --config my-jest-config.js.

  • there is a file called jest-e2e.config.js, jest-e2e.config.json, jest.config.js, or jest.config.json in the top-level directory of your package (at the same level than your package.json).

  • a jest object can be provided in the package.json file with the test configuration.

Top ↑arrow-up-right

Alias: test-unit-jest

Launches the unit test runner. Writing tests can be done using the Jest APIarrow-up-right.

Example:

12345678

{ "scripts": { "test:unit": "wp-scripts test-unit-js", "test:unit:help": "wp-scripts test-unit-js --help", "test:unit:watch": "wp-scripts test-unit-js --watch", "test:unit:debug": "wp-scripts --inspect-brk test-unit-js --runInBand --no-cache" }}

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.

  • npm run test:unit:debug – runs all unit tests in debug modearrow-up-right.

Jest will look for test files with any of the following popular naming conventions:

  • Files with .js (or .ts) suffix located at any level of depth in __tests__ folders.

  • Files with .js (or .ts) suffix directly located in test folders.

  • Files with .test.js (or .test.ts) suffix.

Top ↑arrow-up-right

Advanced information #Advanced information

It uses Jestarrow-up-right behind the scenes and you are able to use all of its CLI optionsarrow-up-right. You can also run ./node_modules/.bin/wp-scripts test:unit --help or npm run test:unit:help (as mentioned above) to view all of the available options. By default, it uses the set of recommended options defined in @wordpress/jest-preset-defaultarrow-up-right npm package. You can override them with your own options as described in Jest documentationarrow-up-right. Learn more in the Advanced Usagearrow-up-right section.

Should there be any situation where you want to provide your own Jest config, you can do so.

  • the command receives a --config argument. Example: wp-scripts test-unit --config my-jest-config.js.

  • there is a file called jest-unit.config.js, jest-unit.config.json, jest.config.js, or jest.config.json in the top-level directory of your package (at the same level than your package.json).

  • a jest object can be provided in the package.json file with the test configuration.

Top ↑arrow-up-right

wp-scripts supports the full array of Node.js CLI optionsarrow-up-right. They can be passed after the wp-scripts command and before the script name.

1

wp-scripts [NODE_OPTIONS] script

Top ↑arrow-up-right

One common use-case for passing Node.js options is debugging your tests.

Tests can be debugged by any inspector clientarrow-up-right that supports the Chrome DevTools Protocolarrow-up-right.

Follow the instructions for debugging Node.js with your favorite supported browser or IDE. When the instructions say to use node --inspect script.js or node --inspect-brk script.js, simply use wp-scripts --inspect script or wp-scripts --inspect-brk script instead.

Google Chrome and Visual Studio Code are used as examples below.

Top ↑arrow-up-right

Debugging in Google Chrome #Debugging in Google Chrome

Place debugger; statements in any test and run wp-scripts --inspect-brk test-unit-js --runInBand --no-cache (or npm run test:unit:debug from above).

Then open about:inspect in Google Chrome and select inspect on your process.

A breakpoint will be set at the first line of the script (this is done to give you time to open the developer tools and to prevent Jest from executing before you have time to do so). Click the resume button in the upper right panel of the dev tools to continue execution. When Jest executes the test that contains the debugger statement, execution will pause and you can examine the current scope and call stack.

Top ↑arrow-up-right

Debugging in Visual Studio Code #Debugging in Visual Studio Code

Debugging npm scripts is supported out of the box for Visual Studio Code as of version 1.23arrow-up-right and can be used to debug Jest unit tests.

Make sure wp-scripts --inspect-brk test-unit-js --runInBand --no-cache is saved as test:unit:debug in your package.json file to run tests in Visual Studio Code.

When debugging, set a breakpoint in your tests by clicking on a line in the editor’s left margin by the line numbers.

Then open npm scripts in the explorer or run Explorer: Focus on NPM Scripts View in the command palette to see the npm scripts. To start the tests, click the debug icon next to test:unit:debug.

The tests will start running, and execution will pause on your selected line so you can inspect the current scope and call stack within the editor.

See Debugging in Visual Studio Codearrow-up-right for more details on using the Visual Studio Code debugger.

Top ↑arrow-up-right

Debugging e2e tests #Debugging e2e tests

Since e2e tests run both in the node context and the (usually headless) browser context, not all lines of code can have breakpoints set within the inspector client—only the node context is debugged in the inspector client.

The code executed in the node context includes all of the test files excluding code within page.evaluate functions. The page.evaluate functions and the rest of your app code is executed within the browser context.

Test code (node context) can be debugged normally using the instructions above.

To also debug the browser context, run wp-scripts --inspect-brk test-e2e --puppeteer-devtools. The --puppeteer-devtools option (or the PUPPETEER_DEVTOOLS="true" environment variable when used with PUPPETEER_HEADLESS="false") will disable headless mode and launch the browser with the devtools already open. Breakpoints can then be set in the browser context using these devtools.

For more e2e debugging tips check out the Puppeteer debugging docsarrow-up-right.

Top ↑arrow-up-right

In general, this package should be used with the set of recommended config files. While it’s possible to override every single config file provided, if you have to do it, it means that your use case is far more complicated than anticipated. If that happens, it would be better to avoid using the whole abstraction layer and set up your project with full control over tooling used.

Top ↑arrow-up-right

The build and start commands use webpackarrow-up-right 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.

Top ↑arrow-up-right

Default webpack config #Default webpack config

@wordpress/scripts bundles the default webpack config used as a base by the WordPress editor. These are the defaults:

Top ↑arrow-up-right

Using CSS #Using CSS

Example:

123456

// index.scss$body-color: red; .wp-block-my-block { color: $body-color;}

1234

/* style.css */.wp-block-my-block { background-color: black;}

123

// index.jsimport './index.scss';import './style.css';

When you run the build using the default command wp-scripts build (also applies to start) in addition to the JavaScript file index.js generated in the build folder, you should see two more files:

  1. index.css – all imported CSS files are bundled into one chunk named after the entry point, which defaults to index.js, and thus the file created becomes index.css. This is for styles used only in the editor.

  2. style-index.css – imported style.css file(s) (applies to SASS and SCSS extensions) get bundled into one style-index.css file that is meant to be used both on the front-end and in the editor.

You can also have multiple entry points as described in the docs for the script:

1

wp-scripts start entry-one.js entry-two.js --output-path=custom

If you do so, then CSS files generated will follow the names of the entry points: entry-one.css and entry-two.css.

Avoid using style keyword in an entry point name, this might break your build process.

You can also bundle CSS modules by prefixing .module to the extension, e.g. style.module.scss. Otherwise, these files are handled like all other style.scss. They will also be extracted into style-index.css.

Top ↑arrow-up-right

Using fonts and images #Using fonts and images

It is possible to reference font (woff, woff2, eot, ttf and otf) and image (bmp, png, jpg, jpeg and gif) files from CSS that is controlled by webpack as explained in the previous section.

Example:

123456789

/* style.css */@font-face { font-family: Gilbert; src: url( ../assets/gilbert-color.otf );}.wp-block-my-block { background-color: url( ../assets/block-background.png ); font-family: Gilbert;}

Top ↑arrow-up-right

Using SVG #Using SVG

Example:

12345678

import starUrl, { ReactComponent as Star } from './star.svg'; const App = () => ( <div> <img src={ starUrl } alt="star" /> <Star /> </div>);

Top ↑arrow-up-right

Provide your own webpack config #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 project (at the same level as package.json).

Extending the webpack config

To extend the provided webpack config, or replace subsections within the provided webpack config, you can provide your own webpack.config.js file, require the provided webpack.config.js file, and use the spread operatorarrow-up-right to import all of or part of the provided configuration.

In the example below, a webpack.config.js file is added to the root folder extending the provided webpack config to include custom logic to parse module’s source and convert it to a JavaScript object using tomlarrow-up-right. It may be useful to import toml or other non-JSON files as JSON, without specific loaders:

12345678910111213141516171819

const toml = require( 'toml' );const defaultConfig = require( '@wordpress/scripts/config/webpack.config' ); module.exports = { ...defaultConfig, module: { ...defaultConfig.module, rules: [ ...defaultConfig.module.rules, { test: /.toml/, type: 'json', parser: { parse: toml.parse, }, }, ], },};

Expand full source codearrow-up-right

If you follow this approach, please, be aware that future versions of this package may change what webpack and Babel plugins we bundle, default configs, etc. Should those changes be necessary, they will be registered in the package’s CHANGELOGarrow-up-right, so make sure to read it before upgrading.

Last updated