# Get started with wp-scripts

The [`@wordpress/scripts`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) package, commonly referred to as `wp-scripts`, is a set of configuration files and scripts that primarily aims to standardize and simplify the development process of WordPress projects that require a JavaScript build step.

A JavaScript build step refers to the process of transforming, bundling, and optimizing JavaScript source code and related assets into a format suitable for production environments. These build steps often take modern JavaScript (ESNext and JSX) and convert it to a version compatible with most browsers. They can also bundle multiple files into one, minify the code to reduce file size and perform various other tasks to optimize the code.

You will typically be working with ESNext and JSX when building for the Block Editor, and all examples in the Block Editor Handbook are written in these syntaxes. Learning how to set up a build step is essential. However, configuring the necessary tools like [webpack](https://webpack.js.org/), [Babel](https://babeljs.io/), and [ESLint](https://eslint.org/) can become complex. This is where `wp-scripts` comes in.

Here are a few things that `wp-scripts` can do:

- **Compilation:** Converts modern JavaScript (ESNext and JSX) into code compatible with most browsers, using Babel.
- **Bundling:** Uses webpack to combine multiple JavaScript files into a single bundle for better performance.
- **Code Linting:** Provides configurations for ESLint to help ensure code quality and conformity to coding standards.
- **Code Formatting:** Incorporates Prettier for automated code styling to maintain consistent code formatting across projects.
- **Sass Compilation:** Converts Sass (.scss or .sass) files to standard CSS.
- **Code Minification:** Reduces the size of the JavaScript code for production to ensure faster page loads.

The package abstracts away much of the initial setup, configuration, and boilerplate code associated with JavaScript development for modern WordPress. You can then focus on building blocks and Block Editor extensions.

## Quick start

<div class="callout callout-tip">

If you use [`@wordpress/create-block`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/) package to scaffold the structure of files needed to create and register a block, you’ll also get a modern JavaScript build setup (using `wp-scripts`) with no configuration required, so you don’t need to worry about installing `wp-scripts` or enqueuing assets. Refer to [Get started with `create-block`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/) for more details.

</div>

### Installation

Ensure you have Node.js and `npm` installed on your computer. Review the [Node.js development environment](https://developer.wordpress.org/block-editor/getting-started/devenv/nodejs-development-environment/) guide if not.

Then, create a project folder and ensure it contains a `package.json` file, a `build` folder, and an `src` folder. The `src` folder should also include an `index.js` file.

If you have not created a `package.json` file before, navigate to the project folder in the terminal and run the `npm init` command. An interactive prompt will walk you through the steps. Configure as you like, but when it asks for the “entry point”, enter `build/index.js`.

Of course, there are many ways to set up a project using `wp-scripts`, but this is the recommended approach used throughout the Block Editor Handbook.

Finally, install the `wp-scripts` package as a development dependency by running the command:

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

Once the installation is complete, your project folder should look like this:

``` bash
example-project-folder/
├── build/
├── node_modules/ (autogenerated)
├── src/
│   └── index.js
├── package-lock.json (autogenerated)
└── package.json
```

### Basic usage

Once installed, you can run the predefined scripts provided with `wp-scripts` by referencing them in the scripts section of your `package.json` file. Here’s an example:

``` json
{
    "scripts": {
        "start": "wp-scripts start",
        "build": "wp-scripts build"
    }
}
```

These scripts can then be run using the command `npm run {script name}`.

### The build process with `wp-scripts`

The two scripts you will use most often are `start` and `build` since they handle the build step. See the [package documentation](https://developer.wordpress.org/block-editor/packages/packages-scripts/) for all options.

When working on your project, use the `npm run start` command. This will start a development server and automatically rebuild the project whenever any change is detected. Note that the compiled code in `build/index.js` will not be optimized.

When you are ready to deploy your project, use the `npm run build` command. This optimizes your code and makes it production-ready.

After the build finishes, you will see the compiled JavaScript file created at `build/index.js`.

A `build/index.asset.php` file will also be created in the build process, which contains an array of dependencies and a version number (for cache busting). Please, note that to register a block without this `wp-scripts` build process you’ll need to manually create `*.asset.php` dependencies files (see [example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-no-build-e621a6)).

### Enqueuing assets

If you register a block via `register_block_type` the scripts defined in `block.json` will be automatically enqueued (see [example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-ca6eda))

To manually enqueue files in the editor, in any other context, you can refer to the [Enqueueing assets in the Editor](https://developer.wordpress.org/block-editor/how-to-guides/enqueueing-assets-in-the-editor/) guide for more information, but here’s a typical implementation.

``` php
/**
 * Enqueue Editor assets.
 */
function example_project_enqueue_editor_assets() {
    $asset_file = include( plugin_dir_path( __FILE__ ) . 'build/index.asset.php');

    wp_enqueue_script(
        'example-editor-scripts',
        plugins_url( 'build/index.js', __FILE__ ),
        $asset_file['dependencies'],
        $asset_file['version']
    );
}
add_action( 'enqueue_block_editor_assets', 'example_project_enqueue_editor_assets' );
```

Here’s [an example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/data-basics-59c8f8) of manually enqueuing files in the editor.

## Next steps

While `start` and `build` will be the two most used scripts, several other useful tools come with `wp-scripts` that are worth exploring. Here’s a look at a few.

### Maintaining code quality

To help developers improve the quality of their code, `wp-scripts` comes pre-configured with tools like ESLint and Prettier. ESLint ensures your JavaScript adheres to best practices and the [WordPress coding standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/), while Prettier automatically formats your code. The available scripts include:

``` json
{
    "scripts": {
        "format": "wp-scripts format",
        "lint:css": "wp-scripts lint-style",
        "lint:js": "wp-scripts lint-js",
    }
}
```

Regularly linting and formatting your code ensures it’s functional, clear, and maintainable for yourself and other developers.

### Running tests

`wp-scripts test-unit-js` runs your project’s installed [Vitest](https://vitest.dev/) for unit tests. For a new test setup, install Vitest 5 and Vite 8 as development dependencies:

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

`wp-scripts` also provides [Playwright](https://playwright.dev/) for end-to-end tests. Add these commands to `package.json`:

``` json
{
    "scripts": {
        "test:e2e": "wp-scripts test-e2e",
        "test:unit": "wp-scripts test-unit-js"
    }
}
```

Unit tests check individual functions or components. End-to-end tests check the application through user interactions.

For Vitest configuration and examples, including DOM and browser tests, see the [consumer migration guide](https://github.com/WordPress/gutenberg/blob/HEAD/packages/scripts/docs/vitest-migration.md). Existing Jest projects can use `wp-scripts test-unit-jest` and follow [Keep an existing Jest suite](https://github.com/WordPress/gutenberg/blob/HEAD/packages/scripts/docs/vitest-migration.md#keep-an-existing-jest-suite) for the required dependencies and configuration.

### Advanced configurations

While `wp-scripts` provides a solid default configuration, there might be cases where you need more specialized setups. The good news is `wp-scripts` is highly adaptable. For example, you can extend and override the default webpack configuration, allowing you to add loaders and plugins or modify almost any part of the build process. This flexibility ensures that as your project grows or its requirements change, `wp-scripts` can be tailored to your evolving needs.

See the `wp-scripts` [package documentation](https://developer.wordpress.org/block-editor/packages/packages-scripts/) for all configuration options.

## Additional resources

- [@wordpress/scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) (Official documentation)
- [How webpack and WordPress packages interact](https://developer.wordpress.org/news/2023/04/how-webpack-and-wordpress-packages-interact/) (WordPress Developer Blog)