Skip to main content
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

1
Ensure Node.js is Installed
2
Ensure you have Node.js and npm installed on your computer. Review the Node.js development environment guide if not.
3
Create Project Structure
4
Create a project folder and ensure it contains:
5
  • A package.json file
  • A build folder
  • An src folder with an index.js file
    • 6
    If you have not created a package.json file before, navigate to the project folder in the terminal and run:
    7
    npm init
    8
    An interactive prompt will walk you through the steps. When it asks for the “entry point”, enter build/index.js.
    9
    Install wp-scripts
    10
    Install the wp-scripts package as a development dependency:
    11
    npm
    npm install @wordpress/scripts --save-dev
    yarn
    yarn add @wordpress/scripts --dev
    pnpm
    pnpm add @wordpress/scripts --save-dev
    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
    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
    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
    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

    ​
    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

    Build docs developers (and LLMs) love

    Get started for freeTalk to us