Get Started with wp-scripts

The @wordpress/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.

If you use @wordpress/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.

What wp-scripts Can Do

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.

Node.js Requirement: This package requires Node.js version with long-term support status (Active LTS or Maintenance LTS). It is not compatible with older versions.

Quick Start

Installation

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

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:

{
  "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

The two scripts you will use most often are start and build since they handle the build step.

Development Mode

When working on your project, use the npm run start command:

npm run start

yarn start

pnpm start

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.

Production Mode

When you are ready to deploy your project, use the npm run build command:

npm run build

yarn build

pnpm build

This optimizes your code and makes it production-ready.

Build Output

After the build finishes, you will see:

build/index.js - The compiled JavaScript file
build/index.asset.php - Contains an array of dependencies and a version number (for cache busting)

The *.asset.php file is essential for properly enqueuing your scripts with WordPress. Without the wp-scripts build process, you’ll need to manually create these dependency files.

Available Scripts

Here’s a comprehensive example demonstrating most of the capabilities included:

{
  "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"
  }
}

Build Options

The build and start commands support various options:

# Custom entry points and output directory
npm run build -- entry-one.js entry-two.js --output-path=custom

# Copy all PHP files from src to build
npm run build -- --webpack-copy-php

# Custom source directory
npm run build -- --source-path=custom-directory

# Enable webpack bundle analyzer
npm run build -- --webpack-bundle-analyzer

# Generate blocks manifest for performance
npm run build -- --blocks-manifest

Start Options

The start command has additional development-specific options:

# Enable Fast Refresh (requires SCRIPT_DEBUG and Gutenberg plugin)
npm run start -- --hot

# Start without watching for changes
npm run start -- --no-watch

# Custom webpack devtool
npm run start -- --webpack-devtool=source-map

Maintaining Code Quality

To help developers improve the quality of their code, wp-scripts comes pre-configured with tools like ESLint and Prettier:

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

# Format code with Prettier
npm run format

# Lint JavaScript
npm run lint:js

# Lint CSS/SCSS
npm run lint:css

yarn format
yarn lint:js
yarn lint:css

pnpm format
pnpm lint:js
pnpm lint:css

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

Running Tests

Beyond just writing code, verifying its functionality is crucial. wp-scripts includes Jest, a JavaScript testing framework, and both end-to-end and unit testing scripts:

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

# Run unit tests
npm run test:unit

# Run E2E tests
npm run test:e2e

# Run unit tests in watch mode
npm run test:unit -- --watch

yarn test:unit
yarn test:e2e
yarn test:unit --watch

pnpm test:unit
pnpm test:e2e
pnpm test:unit --watch

Enqueuing Assets

If you register a block via register_block_type the scripts defined in block.json will be automatically enqueued. To manually enqueue files in the editor, in any other context, here’s a typical implementation:

/**
 * 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' );

Refer to the Enqueueing assets in the Editor guide for more information.

Entry Points

Listing Entry Points

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

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

The default location for the source files is the project’s root. 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

A convenient alternative for blocks is using automatic entry point detection. The source code directory (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. Example block.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:

wp-scripts build

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

You can import CSS, SCSS, and SASS files directly in your JavaScript:

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

When you run the build:

index.css - All imported CSS files are bundled into one chunk named after the entry point (editor only)
style-index.css - Imported style.css file(s) get bundled into one file meant for both front-end and editor

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.

Using Assets

Fonts and Images

It is possible to reference font (woff, woff2, eot, ttf, otf) and image (bmp, png, jpg, jpeg, gif, webp) files from 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;
}

SVG Files

You can import SVG files as React components:

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

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

Advanced Configuration

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.

Default Webpack Config

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

Entry: Detected by scanning block.json files in the src directory. Fallback: src/index.js
Output: build/[name].js
Loaders: babel-loader, @svgr/webpack, url-loader, css-loader, postcss-loader, sass-loader
Plugins: CopyWebpackPlugin, MiniCssExtractPlugin, DependencyExtractionWebpackPlugin

Provide Your Own Webpack Config

You can provide your own webpack config when:

The command receives a --config argument: 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

Extending the Webpack Config

To extend the provided webpack config, you can create your own webpack.config.js file:

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

You should keep using the wp-scripts commands (start and build). Do not use webpack directly.
Future versions may change bundled plugins and default configs. Check the CHANGELOG before upgrading.

Additional Resources

@wordpress/scripts Package Documentation
How webpack and WordPress packages interact (WordPress Developer Blog)
Working with JavaScript for the Block Editor

Get Started

Development Environment

Core Concepts

Block Development

Data & State

Guides

Get Started with wp-scripts

What wp-scripts Can Do

Quick Start

Installation

Basic Usage

The Build Process

Development Mode

Production Mode

Build Output

Available Scripts

Build Options

Start Options

Maintaining Code Quality

Running Tests

Enqueuing Assets

Entry Points

Listing Entry Points

Automatic block.json Detection

Fallback Entry Point

Importing Styles in JavaScript

Using Assets

Fonts and Images

SVG Files

Advanced Configuration

Default Webpack Config

Provide Your Own Webpack Config

Extending the Webpack Config

Additional Resources

​What wp-scripts Can Do

​Quick Start

​Installation

​Basic Usage

​The Build Process

​Development Mode

​Production Mode

​Build Output

​Available Scripts

​Build Options

​Start Options

​Maintaining Code Quality

​Running Tests

​Enqueuing Assets

​Entry Points

​Listing Entry Points

​Automatic block.json Detection

​Fallback Entry Point

​Importing Styles in JavaScript

​Using Assets

​Fonts and Images

​SVG Files

​Advanced Configuration

​Default Webpack Config

​Provide Your Own Webpack Config

​Extending the Webpack Config

​Additional Resources

What wp-scripts Can Do

Quick Start

Installation

Basic Usage

The Build Process

Development Mode

Production Mode

Build Output

Available Scripts

Build Options

Start Options

Maintaining Code Quality

Running Tests

Enqueuing Assets

Entry Points

Listing Entry Points

Automatic block.json Detection

Fallback Entry Point

Importing Styles in JavaScript

Using Assets

Fonts and Images

SVG Files

Advanced Configuration

Default Webpack Config

Provide Your Own Webpack Config

Extending the Webpack Config

Additional Resources