# @wordpress/scripts

> Collection of reusable scripts for WordPress development.

Latest version **37.1.0** (published 2026-11-04) · GPL-2.0-or-later license · 0 weekly downloads

## Install

```sh
npm install @wordpress/scripts
pnpm add @wordpress/scripts
yarn add @wordpress/scripts
bun add @wordpress/scripts
```

Provides the command `wp-scripts`.

## Health

**Score 60/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score; popular repo.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 37.1.0 |
| Published | 2026-11-04 |
| First published | 2018-01-23 |
| Weekly downloads | 0 |
| License | GPL-2.0-or-later |
| TypeScript types | none |
| Module format | CommonJS |
| Node | ^22.22.2 \|\| ^24.15.0 \|\| >=26.0.0 |
| Dependencies | 49 |
| Unpacked size | 173.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 11780 |
| Author | The WordPress Contributors |
| Maintainers | garypendergast, adamsilverstein, gziolo, ntwb, riad, noisysocks, kadamwhite, gutenbergplugin, jorgefilipecosta, ellatrix, iandunn206, whyisjake, ockham, sirreal, nosolosw, wpisabel, ntsekouras, nerrad, desrosj, talldanwp, peterwilsoncc, ryanwelcher, mamaduka, aduth, johnbillion |
| Keywords | wordpress, gutenberg, scripts |

## Links

- npm: https://www.npmjs.com/package/@wordpress/scripts
- Repository: https://github.com/WordPress/gutenberg
- Homepage: https://github.com/WordPress/gutenberg/tree/HEAD/packages/scripts/README.md
- Issues: https://github.com/WordPress/gutenberg/issues
- npm.io page: https://npm.io/package/@wordpress/scripts

## Dependencies (49)

- [sass](https://npm.io/package/sass.md) ^1.54.0
- [chalk](https://npm.io/package/chalk.md) ^4.1.1
- [eslint](https://npm.io/package/eslint.md) ^10.0.0
- [rtlcss](https://npm.io/package/rtlcss.md) ^4.3.0
- [adm-zip](https://npm.io/package/adm-zip.md) ^0.6.1
- [cssnano](https://npm.io/package/cssnano.md) ^6.0.1
- [postcss](https://npm.io/package/postcss.md) ^8.4.38
- [webpack](https://npm.io/package/webpack.md) ^5.111.0
- [dir-glob](https://npm.io/package/dir-glob.md) ^3.0.1
- [json2php](https://npm.io/package/json2php.md) ^0.0.9
- [minimist](https://npm.io/package/minimist.md) ^1.2.0
- [prettier](https://npm.io/package/prettier.md) npm:wp-prettier@^3.9.6
- [fast-glob](https://npm.io/package/fast-glob.md) ^3.2.7
- [stylelint](https://npm.io/package/stylelint.md) ^17.14.1
- [css-loader](https://npm.io/package/css-loader.md) ^6.2.0
- [url-loader](https://npm.io/package/url-loader.md) ^4.1.1
- [@babel/core](https://npm.io/package/@babel/core.md) ^7.25.7
- [cross-spawn](https://npm.io/package/cross-spawn.md) ^7.0.6
- [read-pkg-up](https://npm.io/package/read-pkg-up.md) ^7.0.1
- [resolve-bin](https://npm.io/package/resolve-bin.md) ^1.0.1
- [sass-loader](https://npm.io/package/sass-loader.md) ^16.0.3
- [webpack-cli](https://npm.io/package/webpack-cli.md) ^5.1.4
- [babel-loader](https://npm.io/package/babel-loader.md) ^9.2.1
- [browserslist](https://npm.io/package/browserslist.md) ^4.28.7
- [npm-packlist](https://npm.io/package/npm-packlist.md) ^3.0.0
- [schema-utils](https://npm.io/package/schema-utils.md) ^4.2.0
- [@svgr/webpack](https://npm.io/package/@svgr/webpack.md) ^8.0.1
- [react-refresh](https://npm.io/package/react-refresh.md) ^0.14.0
- [postcss-loader](https://npm.io/package/postcss-loader.md) ^6.2.1
- [stylelint-scss](https://npm.io/package/stylelint-scss.md) ^7.2.0
- [markdownlint-cli](https://npm.io/package/markdownlint-cli.md) ^0.49.1
- [source-map-loader](https://npm.io/package/source-map-loader.md) ^3.0.0
- [check-node-version](https://npm.io/package/check-node-version.md) ^4.1.0
- [webpack-dev-server](https://npm.io/package/webpack-dev-server.md) ^6.0.0
- [copy-webpack-plugin](https://npm.io/package/copy-webpack-plugin.md) ^10.2.0
- [npm-package-json-lint](https://npm.io/package/npm-package-json-lint.md) ^6.4.0
- [terser-webpack-plugin](https://npm.io/package/terser-webpack-plugin.md) ^5.3.10
- [mini-css-extract-plugin](https://npm.io/package/mini-css-extract-plugin.md) ^2.9.2
- [webpack-bundle-analyzer](https://npm.io/package/webpack-bundle-analyzer.md) ^4.9.1
- [@wordpress/eslint-plugin](https://npm.io/package/@wordpress/eslint-plugin.md) ^28.1.0
- [@wordpress/prettier-config](https://npm.io/package/@wordpress/prettier-config.md) ^5.1.0
- [@wordpress/stylelint-config](https://npm.io/package/@wordpress/stylelint-config.md) ^27.1.0
- [@wordpress/browserslist-config](https://npm.io/package/@wordpress/browserslist-config.md) ^7.1.0
- [@wordpress/babel-preset-default](https://npm.io/package/@wordpress/babel-preset-default.md) ^10.1.0
- [@wordpress/postcss-plugins-preset](https://npm.io/package/@wordpress/postcss-plugins-preset.md) ^6.1.0
- [@pmmmwh/react-refresh-webpack-plugin](https://npm.io/package/@pmmmwh/react-refresh-webpack-plugin.md) ^0.6.3
- [@wordpress/e2e-test-utils-playwright](https://npm.io/package/@wordpress/e2e-test-utils-playwright.md) ^3.2.0
- [@wordpress/npm-package-json-lint-config](https://npm.io/package/@wordpress/npm-package-json-lint-config.md) ^6.1.0
- [@wordpress/dependency-extraction-webpack-plugin](https://npm.io/package/@wordpress/dependency-extraction-webpack-plugin.md) ^7.1.0

## Recent versions

- 37.1.0 (latest) — 2026-11-04
- 36.0.1-next.v.202609171837.0 (next) — 2026-09-17
- 31.5.1 (wp-7.0) — 2026-06-30
- 30.26.2 (wp-6.9) — 2025-11-07
- 30.12.1 (wp-6.8) — 2025-03-10
- 30.0.6 (wp-6.7) — 2024-10-21
- 28.0.2 (wp-6.6) — 2024-07-09
- 27.2.6 (wp-6.5) — 2024-05-02
- 26.13.13 (wp-6.4) — 2023-11-13
- 26.6.5 (wp-6.3) — 2023-10-12
- 25.3.6 (wp-6.2) — 2023-10-12
- 24.1.2 (wp-6.1) — 2022-09-20
- 22.4.2 (wp-6.0) — 2022-04-26
- 19.2.4 (patch) — 2022-01-18
- 16.1.5 (wp-5.8) — 2021-09-01
- … 332 more at https://npm.io/package/@wordpress/scripts/versions

## README

# Scripts

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-scripts](https://www.npmjs.com/package/react-scripts) and [kcd-scripts](https://www.npmjs.com/package/kcd-scripts)._

## Installation

You only need to install one npm module:

```bash
npm install @wordpress/scripts --save-dev
```

**Note**: This package requires Node.js version with long-term support status (check [Active LTS or Maintenance LTS releases](https://nodejs.org/en/about/previous-releases)). It is not compatible with older versions.

## Setup

This package offers a command-line interface and exposes a binary called `wp-scripts` so you can call it directly with `npm exec --no -- wp-scripts`. 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:_

```json
{
	"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:pkg-json": "wp-scripts lint-pkg-json",
		"packages-update": "wp-scripts packages-update",
		"plugin-zip": "wp-scripts plugin-zip",
		"start": "wp-scripts start",
		"test:e2e": "wp-scripts test-e2e",
		"test:unit": "wp-scripts test-unit-js"
	}
}
```

It might also be a good idea to get familiar with [Working with JavaScript for the Block Editor](/docs/getting-started/fundamentals/javascript-in-the-block-editor.md) for setting up a development environment to use ESNext syntax. It gives a very in-depth explanation of how to use the [build](#build) and [start](#start) scripts.

## Updating to New Release

To update an existing project to a new version of `@wordpress/scripts`, open the [changelog](/packages/scripts/CHANGELOG.md), 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 [changelog](/packages/scripts/CHANGELOG.md) 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.

## Available Scripts

### `build`

Transforms your code according the configuration provided so it’s ready for production and optimized for the best performance.

_This script exits after producing a single build. For incremental builds, better suited for development, see the [start](#start) script._

#### Usage

_Example:_

```json
{
	"scripts": {
		"build": "wp-scripts build",
		"build:custom": "wp-scripts build entry-one.js entry-two.js --output-path=custom",
		"build:copy-php": "wp-scripts build --webpack-copy-php",
		"build:custom-directory": "wp-scripts build --source-path=custom-directory"
	}
}
```

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 directory. Paths for custom entry points are relative to the project root.
- `npm run build:copy-php` - builds the code for production and opts into copying all PHP files from the `src` directory and its subfolders to the output directory. By default, only PHP files listed in the `render` and `variations` fields in the detected `block.json` files get copied.
- `npm run build:custom-directory` - builds the code for production using the `custom-directory` as the source code directory.

This script automatically use the optimized config but sometimes you may want to specify some custom options:

- `--webpack-bundle-analyzer` – enables visualization for the size of webpack output files with an interactive zoomable treemap.
- `--webpack-copy-php` – enables copying all PHP files from the source directory ( default is `src` ) and its subfolders to the output directory.
- `--webpack-no-externals` – disables scripts’ assets generation, and omits the list of default externals.
- `--blocks-manifest` – generates a PHP file containing block metadata from all `block.json` files in the project. This is useful for enhancing performance when registering multiple block types, as it allows you to use `wp_register_block_metadata_collection()` and `wp_register_block_types_from_metadata_collection()` in WordPress.
- `--source-path` – allows customization of the source directory. The default is the project root `.` when [entry points are listed](#listing-entry-points) in the command, or `src` otherwise.
- `--output-path` – allows customization of the output directory. The default is the `build` folder.

Experimental support for the block.json `viewScriptModule` field is available via the
`--experimental-modules` option. With this option enabled, script and module fields will all be
compiled. The `viewScriptModule` field is analogous to the `viewScript` field, but will compile a module
and should be registered in WordPress using the Modules API.

Learn more about [using build scripts](#using-build-scripts) to optimize the development experience based on your specific needs.

#### Advanced information

This script uses [webpack](https://webpack.js.org/) 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 Usage](#advanced-usage) section.

### `build-blocks-manifest`

This script generates a PHP file containing block metadata from all `block.json` files in the project. This is useful for enhancing performance when registering multiple block types, as it allows you to use `wp_register_block_metadata_collection()` and `wp_register_block_types_from_metadata_collection()` in WordPress.

Usage: `wp-scripts build-blocks-manifest [options]`

Options:

- `--input`: Specify the input directory (default: 'build')
- `--output`: Specify the output file path (default: 'build/blocks-manifest.php')

Example:

```bash
wp-scripts build-blocks-manifest --input=src --output=dist/blocks-manifest.php
```

This command will scan the specified input directory for `block.json` files,
compile their metadata into a single PHP file, and output it to the specified
location. You can then use this file with
`wp_register_block_metadata_collection()` in your plugin:

```php
wp_register_block_metadata_collection(
    plugin_dir_path( __FILE__ ) . 'dist',
    plugin_dir_path( __FILE__ ) . 'dist/blocks-manifest.php'
);
```

Using this approach can improve performance when registering multiple block
types, especially for plugins with several custom blocks. Note that this
feature is only available in WordPress 6.7 and later versions.

Alternatively, you can use `wp_register_block_types_from_metadata_collection()`
to have all block types from your plugin automatically registered in the same
function call. This way you no longer need to call `register_block_type()` for
every block type in your plugin.

```php
wp_register_block_types_from_metadata_collection(
    plugin_dir_path( __FILE__ ) . 'dist',
    plugin_dir_path( __FILE__ ) . 'dist/blocks-manifest.php'
);
```

Note that this feature is only available in WordPress 6.8 and later versions.

### `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.

_Example:_

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

This is how you execute the script with presented setup:

- `npm run check-engines` - checks installed versions of the tools listed in the `engines` field of your project's `package.json`, falling back to the `node` version required by this package.

#### Advanced information

It uses [check-node-version](https://www.npmjs.com/package/check-node-version) behind the scenes with the recommended configuration provided. When your project has no `engines` field, it checks the Node.js version required by this package. You can specify your own ranges as described in [check-node-version docs](https://www.npmjs.com/package/check-node-version). Learn more in the [Advanced Usage](#advanced-usage) section.

### `check-licenses`

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

_Example:_

```json
{
	"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`
- `--gpl2`: Validates against [GPLv2 license compatibility](https://www.gnu.org/licenses/license-list.en.html)
- `--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.

### `format`

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

_Example:_

```json
{
	"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.

### `lint-js`

Helps enforce coding style guidelines for your JavaScript and TypeScript files.

_Example:_

```json
{
	"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 and TypeScript files in the entire project’s directories.
- `npm run lint:js:src` - lints JavaScript and TypeScript 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 examples](https://eslint.org/docs/user-guide/command-line-interface).

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

#### Advanced information

It uses [ESLint](https://eslint.org/) with the set of recommended rules defined in [@wordpress/eslint-plugin](https://www.npmjs.com/package/@wordpress/eslint-plugin) npm package. It detects flat config files (`eslint.config.*`) first, falling back to legacy `.eslintrc.*` files if present. You can override default rules with your own as described in the [ESLint configuration docs](https://eslint.org/docs/latest/use/configure/). Learn more in the [Advanced Usage](#advanced-usage) section.

**Breaking changes in ESLint v10:**

- The default config path has changed from `config/.eslintrc.js` to `config/eslint.config.cjs`. If you were extending the default config, update your import path.
- The `--ignore-path` CLI flag was removed along with the eslintrc system. Use `ignores` arrays in your flat config instead.
- Legacy `.eslintrc.*` fallback detection is deprecated and will be removed in a future version. Migrate to `eslint.config.*` files.

### `lint-pkg-json`

Helps enforce standards for your `package.json` files.

_Example:_

```json
{
	"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 examples](https://github.com/tclindner/npm-package-json-lint/blob/HEAD/README.md#examples).

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

#### Advanced information

It uses [npm-package-json-lint](https://www.npmjs.com/package/npm-package-json-lint) with the set of recommended rules defined in [@wordpress/npm-package-json-lint-config](https://www.npmjs.com/package/@wordpress/npm-package-json-lint-config) npm package. You can override default rules with your own as described in [npm-package-json-lint wiki](https://github.com/tclindner/npm-package-json-lint/wiki). Learn more in the [Advanced Usage](#advanced-usage) section.

### `lint-md-docs`

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

_Example:_

```json
{
	"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.

#### Advanced information

It uses [markdownlint](https://github.com/DavidAnson/markdownlint) with the [.markdownlint.json](/packages/scripts/config/.markdownlint.json) configuration. This configuration tunes the linting rules to match WordPress standard, you can override with your own config, see [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli/) for command-line parameters.

### `lint-style`

Helps enforce coding style guidelines for your style files.

_Example:_

```json
{
	"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, PCSS, 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 [globby](https://github.com/sindresorhus/globby) (like the `**` globstar) regardless of your shell. See [more examples](https://github.com/stylelint/stylelint/blob/HEAD/docs/user-guide/cli.md#examples).

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

#### Advanced information

It uses [stylelint](https://github.com/stylelint/stylelint) with the [@wordpress/stylelint-config](https://www.npmjs.com/package/@wordpress/stylelint-config) configuration per the [WordPress CSS Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/css/). You can override them with your own rules as described in [stylelint user guide](https://stylelint.io/user-guide/configure). Learn more in the [Advanced Usage](#advanced-usage) section.

### `packages-update`

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

_Example:_

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

This script provides the following custom options:

- `--dist-tag` – allows specifying a custom dist-tag when updating npm packages. Defaults to `latest`. This is especially useful when using [`@wordpress/dependency-extraction-webpack-plugin`](https://www.npmjs.com/package/@wordpress/dependency-extraction-webpack-plugin). It lets installing the npm dependencies at versions used by the given WordPress major version for local testing, etc. Example: `wp-scripts packages-update --dist-tag=wp-6.0`.

#### Advanced information

The command detects project dependencies that have name starting with `@wordpress/` by scanning the `package.json` file. By default, it executes `npm install @wordpress/package1@latest @wordpress/package2@latest ... --save` to change the package versions to the latest one. You can chose a different dist-tag than `latest` by using the `--dist-tag` option when running the command.

### `plugin-zip`

Creates a zip file for a WordPress plugin.

_Example:_

```json
{
	"scripts": {
		"plugin-zip": "wp-scripts plugin-zip"
	}
}
```

By default, it uses [Plugin Handbook best practices](https://developer.wordpress.org/plugins/plugin-basics/best-practices/#file-organization) to discover files.

#### Advanced information

In the case where the plugin author wants to customize the files included in the zip file, they can provide the `files` field in the `package.json` file as documented in the [`npm-packlist`](https://www.npmjs.com/package/npm-packlist) package, example:

```json
{
	"files": [ "dir" ]
}
```

It reuses the same logic as `npm pack` command to create an npm package tarball.

This is how you create a custom root folder inside the zip file.

- When updating a plugin, WordPress expects a folder in the root of the zip file which matches the plugin name. So be aware that this may affect the plugin update process.
- `--root-folder` - Add a custom root folder to the zip file.
- `npm run plugin-zip` - By default, unzipping your plugin’s zip file will result in a folder with the same name as your plugin.
- `npm run plugin-zip --root-folder='custom-directory'` - Your plugin’s zip file will be unzipped into a folder named `custom-directory`.
- `npm run plugin-zip --no-root-folder` - This will create a zip file that has no folder inside, your plugin files will be unzipped directly into the target directory.

### `start`

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.

_For single builds, better suited for production, see the [build](#build) script._

#### Usage

_Example:_

```json
{
	"scripts": {
		"start": "wp-scripts start",
		"start:hot": "wp-scripts start --hot",
		"start:custom": "wp-scripts start entry-one.js entry-two.js --output-path=custom",
		"start:copy-php": "wp-scripts start --webpack-copy-php",
		"start:custom-directory": "wp-scripts start --source-path=custom-directory"
	}
}
```

This is how you execute the script with presented setup:

- `npm start` - starts the build for development.
- `npm run start:hot` - starts the build for development with "Fast Refresh". The page will automatically reload if you make changes to the files.
- `npm run start:custom` - starts the build for development which contains two entry points and a custom output directory. Paths for custom entry points are relative to the project root.
- `npm run start:copy-php` - starts the build for development and opts into copying all PHP files from the `src` directory and its subfolders to the output directory. By default, only PHP files listed in the `render` and `variations` fields in the detected `block.json` files get copied.
- `npm run start:custom-directory` - builds the code for production using the `custom-directory` as the source code directory.

This script automatically use the optimized config but sometimes you may want to specify some custom options:

- `--hot` – enables "Fast Refresh". The page will automatically reload if you make changes to the code. _For now, it requires that WordPress has the [`SCRIPT_DEBUG`](https://developer.wordpress.org/advanced-administration/debug/debug-wordpress/#script_debug) flag enabled and the [Gutenberg](https://wordpress.org/plugins/gutenberg/) plugin installed._
- `--no-watch` – Starts the build for development without starting the watcher.
- `--webpack-bundle-analyzer` – enables visualization for the size of webpack output files with an interactive zoomable treemap.
- `--webpack-copy-php` – enables copying all PHP files from the source directory ( default is `src` ) and its subfolders to the output directory.
- `--webpack-devtool` – controls how source maps are generated. See options at https://webpack.js.org/configuration/devtool/#devtool.
- `--webpack-no-externals` – disables scripts’ assets generation, and omits the list of default externals.
- `--blocks-manifest` – generates a PHP file containing block metadata from all `block.json` files in the project. This is useful for enhancing performance when registering multiple block types, as it allows you to use `wp_register_block_metadata_collection()` and `wp_register_block_types_from_metadata_collection()` in WordPress.
- `--source-path` – allows customization of the source directory. The default is the project root `.` when [entry points are listed](#listing-entry-points) in the command, or `src` otherwise.
- `--output-path` – allows customization of the output directory. The default is the `build` folder.

Experimental support for the block.json `viewScriptModule` field is available via the
`--experimental-modules` option. With this option enabled, script and module fields will all be
compiled. The `viewScriptModule` field is analogous to the `viewScript` field, but will compile a module
and should be registered in WordPress using the Modules API.

Learn more about [using build scripts](#using-build-scripts) to optimize the development experience based on your specific needs.

#### Advanced information

This script uses [webpack](https://webpack.js.org/) 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 Usage](#advanced-usage) section.

### `test-unit-js`

Runs the consumer's installed [Vitest](https://vitest.dev/) once. Install the test runner in the project that owns the tests.

For a new test setup, install Vitest 5 and Vite 8:

```sh
npm install --save-dev vitest@^5 vite@^8
```

If your project already uses Vite 7 or 8, keep it and install only `vitest@^5`.

```json
{
	"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 test-unit-js --inspect-brk --no-file-parallelism",
		"test:unit:update": "wp-scripts test-unit-js --update"
	}
}
```

The default environment is Node. Vitest APIs must be imported explicitly. Vitest discovers `*.test.*` and `*.spec.*` files. A file named `test/index.js` needs renaming or an explicit `test.include` pattern in the consumer config.

Vitest discovers `vitest.config.*`, then `vite.config.*`, in the current working directory. A Vitest config takes precedence over a Vite config; it does not merge the two automatically. Use `--config path/to/config.mjs` to select another file. ESM and TypeScript configs use Vite's config loader. Jest config files and the `jest` field in `package.json` do not configure this command.

`@wordpress/scripts` supplies no Vitest preset, shared setup, DOM environment, React transform, aliases, console assertions, or CSS mocks. See the [consumer migration guide](https://github.com/WordPress/gutenberg/blob/HEAD/packages/scripts/docs/vitest-migration.md) for tested Node, jsdom, and Browser Mode examples, dependencies, and support ranges.

### `test-unit-jest`

Maintenance-only adapter for a project-installed Jest 30. It forwards Jest CLI arguments and preserves its exit status, with `NODE_ENV` and `BABEL_ENV` set to `test`. Vitest remains the default through `test-unit-js`. There is no scheduled removal of this adapter.

```sh
npm install --save-dev jest@30.5.0
```

Use `wp-scripts test-unit-jest` in your npm test command. Jest discovers your project's configuration; pass `--config` for custom filenames such as `jest-unit.config.js`. Scripts no longer bundles Jest, jsdom, the WordPress Jest preset, its Babel transformer, or its GitHub Actions reporter.

Existing suites can keep using the published WordPress Jest packages. Maintenance covers this adapter and the documented legacy setup. New testing features target Vitest.

The default `wp-scripts lint-js` config also switches to Vitest. The [Jest upgrade checklist](https://github.com/WordPress/gutenberg/blob/HEAD/packages/scripts/docs/vitest-migration.md#keep-an-existing-jest-suite) covers test commands, dependencies, Jest configuration, and a complete ESLint configuration. You can keep your Jest tests without installing Vitest or Vite.

### `test-e2e`

_Alias_: `test-playwright`

Launches the End-To-End (E2E) test runner, powered by [Playwright](https://playwright.dev/). It provides a high-level API to control a headless browser. `test-playwright` remains available as an alias that runs the same command.

Refer to the [Getting Started guide](https://playwright.dev/docs/writing-tests) to learn how to write tests.

_Example:_

```json
{
	"scripts": {
		"test:e2e": "wp-scripts test-e2e",
		"test:e2e:help": "wp-scripts test-e2e --help",
		"test:e2e:debug": "wp-scripts test-e2e --debug"
	}
}
```

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

- `npm run test:e2e` - runs all tests.
- `npm run test:e2e:help` - prints all available options to configure the test runner.
- `npm run test:e2e:debug` - runs all tests interactively with the Playwright inspector.
- `npm run test:e2e FILE_NAME` - runs a specific test file.
- `npm run test:e2e -- --watch` - runs all tests interactively with watch mode and enhanced debugging.

By default, Playwright looks for JavaScript or TypeScript files with `.test` or `.spec` suffix in the project root-level `/specs` folder, for example `/specs/login-screen.wrong-credentials.spec.ts`.

This script automatically detects the best config to start Playwright, but sometimes you may need to specify custom options.
To do so, you can add a file called `playwright.config.ts` or `playwright.config.js` in the top-level directory of your package (at the same level as your `package.json`).

#### Test Environment

The tests run against the site at the `WP_BASE_URL` environment variable. When it is not set and [`@wordpress/env`](https://www.npmjs.com/package/@wordpress/env) is installed, they run against the `wp-env` environment configured in the current directory: its tests environment if the config enables one, and otherwise its development environment. As with `wp-env start`, the port comes from `.wp-env.json` merged with `.wp-env.override.json` and any `WP_ENV_*` environment variables, so each project can have its own ports. Without either, the tests run against `http://localhost:8889`.

If you start the environment for the tests from a custom config file with `wp-env --config`, pass the same file with `--wp-env-config=<path>`. Its path is resolved relative to the current directory, as with `wp-env --config`, and its override file is merged in too, for example `.wp-env.test.override.json` for `.wp-env.test.json`:

```json
{
	"scripts": {
		"env:test": "wp-env --config .wp-env.test.json",
		"test:e2e": "wp-scripts test-e2e --wp-env-config=.wp-env.test.json"
	}
}
```

#### Failed Test Artifacts

When tests fail, snapshots will be taken of the page and stored in the `artifacts/` directory at the root of your project. These snapshots may help debug failed tests during development or when running tests in a CI environment.

The `artifacts/` directory can be customized by setting the `WP_ARTIFACTS_PATH` environment variable to the relative path of the desired directory within your project’s root. For example: to change the default directory from `artifacts/` to `my/custom/artifacts`, you could use `WP_ARTIFACTS_PATH=my/custom/artifacts npm run test:e2e`.

#### Advanced information

You are able to use all of Playwright’s [CLI options](https://playwright.dev/docs/test-cli#reference). You can also run `./node_modules/.bin/wp-scripts test-e2e --help` or `npm run test:e2e:help` (as mentioned above) to view all the available options. Learn more in the [Advanced Usage](#advanced-usage) section.

## Passing Node.js options

`wp-scripts` supports the full array of [Node.js CLI options](https://nodejs.org/api/cli.html). They can be passed after the `wp-scripts` command and before the script name.

```sh
wp-scripts [NODE_OPTIONS] script
```

### Debugging tests

For Vitest tests, pass `--inspect-brk --no-file-parallelism` after `test-unit-js`. Vitest then opens the inspector in the test worker. Passing `--inspect-brk` before the command inspects the wrapper process instead.

Tests can be debugged by any [inspector client](https://nodejs.org/en/docs/guides/debugging-getting-started/#inspector-clients) that supports the [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/).

For unit tests, keep the inspector flags after `test-unit-js` so they reach the Vitest worker. See the [consumer migration guide](https://github.com/WordPress/gutenberg/blob/HEAD/packages/scripts/docs/vitest-migration.md) for the complete command setup.

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

#### Debugging in Google Chrome

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

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

The test worker pauses before execution so you can attach the debugger. Resume execution in the developer tools. When Vitest reaches a `debugger;` statement, execution pauses again so you can inspect the scope and call stack.

#### Debugging in Visual Studio Code

Debugging npm scripts is supported out of the box for Visual Studio Code as of [version 1.23](https://code.visualstudio.com/blogs/2018/07/12/introducing-logpoints-and-auto-attach#_npm-scripts-and-debugging) and can be used to debug Vitest unit tests.

Make sure `wp-scripts test-unit-js --inspect-brk --no-file-parallelism` 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 Code](https://code.visualstudio.com/Docs/editor/debugging) for more details on using the Visual Studio Code debugger.

## Using build scripts

The `build` and `start` commands use [webpack](https://webpack.js.org/) behind the scenes. webpack is used to bundle and optimize code for web applications, enabling developers to manage dependencies efficiently, enhance performance, and simplify the development workflow.

### Listing entry points

The simplest way to list JavaScript entry points is to pass them as arguments for the command.

_Example:_

```bash
wp-scripts build entry-one.js entry-two.js
```

The default location for the source files is the project’s root. In effect, the command above will look for `entry-one.js` and `entry-two.js` in the project’s root and output the generated files into the `build` directory.

### Automatic block.json detection and the source code directory

A convenient alternative for blocks is using automatic entry point detection. In that case, the source code directory (the default is `./src`) and its subdirectories are scanned for the existence of `block.json` files. If one or more are found, the JavaScript files listed in metadata are treated as entry points and will be output into corresponding folders in the `build` directory. The script fields in `block.json` should pass relative paths to `block.json` in the same folder.

_Example:_

```json
{
	"editorScript": "file:index.js",
	"script": "file:script.js",
	"viewScript": "file:view.js"
}
```

This allows for the creation of multiple blocks that use a single build process triggered with a simple command:

```bash
wp-scripts build
```

The source directory can be customized using the `--source-path` flag and the output directory with the `--output-path` flag.

### Fallback entry point

The fallback entry point is `src/index.js` (other supported extensions: `.jsx`, `.ts`, and `.tsx`) in case there is no `block.json` file found. In that scenario, the output generated will be written to `build/index.js`.

### Importing styles in JavaScript

_Example:_

```scss
// index.scss
$body-color: red;

.wp-block-my-block {
	color: $body-color;
}
```

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

```js
// index.js
import './index.pcss';
import './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 PCSS, 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.

For example, when the project has two entry points:

```bash
wp-scripts build entry-one.js entry-two.js
```

In that case, the CSS generated based on import statements in the JavaScript code will follow the names of the entry points: `entry-one.css` and `entry-two.css`.

_Important:_ 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`.

### Using fonts and images

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

_Example:_

```css
/* 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;
}
```

### Using SVG

_Example:_

```js
import starUrl, { ReactComponent as Star } from './star.svg';

const App = () => (
	<div>
		<img src={ starUrl } alt="star" />
		<Star />
	</div>
);
```

## Advanced Usage

This package should generally be used with the set of recommended config files. While it’s possible to override every config file provided, if you have to do it, 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 the tooling used.

### 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): the entry points for your project get detected by scanning all script fields in `block.json` files located in the `src` directory. The fallback entry point is `src/index.js` (other supported extensions: `.jsx`, `.ts`, and `.tsx`) in case there is no `block.json` file found.
- [Output](https://webpack.js.org/configuration/output): `build/[name].js`, for example: `build/index.js`, or `build/my-block/index.js`.
- [Loaders](https://webpack.js.org/loaders/):
    - [`babel-loader`](https://webpack.js.org/loaders/babel-loader/) allows transpiling JavaScript and TypeScript files using Babel and webpack.
    - [`@svgr/webpack`](https://www.npmjs.com/package/@svgr/webpack) and [`url-loader`](https://webpack.js.org/loaders/url-loader/) makes it possible to handle SVG files in JavaScript code.
    - [`css-loader`](https://webpack.js.org/loaders/css-loader/) chained with [`postcss-loader`](https://webpack.js.org/loaders/postcss-loader/) and [sass-loader](https://webpack.js.org/loaders/sass-loader/) let webpack process CSS, SASS or SCSS files referenced in JavaScript files.
- [Plugins](https://webpack.js.org/configuration/plugins) (among others):
    - [`CopyWebpackPlugin`](https://webpack.js.org/plugins/copy-webpack-plugin/) copies all `block.json` files discovered in the `src` directory to the build directory.
    - [`MiniCssExtractPlugin`](https://webpack.js.org/plugins/mini-css-extract-plugin/) extracts CSS into separate files. It creates a CSS file per JavaScript entry point which contains CSS.
    - [`@wordpress/dependency-extraction-webpack-plugin`](/packages/dependency-extraction-webpack-plugin/README.md) is used with the default configuration to ensure that WordPress provided scripts are not included in the built bundle.

### 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` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) 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 [`toml`](https://www.npmjs.com/package/toml). It may be useful to import toml or other non-JSON files as JSON, without specific loaders:

```javascript
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,
				},
			},
		],
	},
};
```

If you follow this approach, please, be aware that:

- You should keep using the `wp-scripts` commands (`start` and `build`). Do not use `webpack` directly.
- 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 CHANGELOG](/packages/scripts/CHANGELOG.md), so make sure to read it before upgrading.

## Contributing to this package

This is an individual package that’s part of the Gutenberg project. The project is organized as a monorepo. It’s made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project’s main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).

<br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

---
_Source: https://npm.io/package/@wordpress/scripts · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._