How to Migrate from @wordpress/scripts to @wordpress/build: Next-Gen WordPress Plugin Build Tooling

Migrate to @wordpress/build: WordPress Next-Generation Plugin Build Tooling

The WordPress Developer Blog published a detailed guide on @wordpress/build, the new official build tool for WordPress plugins that replaces the aging webpack and Babel pipeline in @wordpress/scripts. If you are building WordPress blocks or plugins, this migration is worth your attention.

What Is @wordpress/build?

@wordpress/build is a new esbuild-based build tool introduced alongside WordPress 7.0. It replaces the webpack plus Babel pipeline used by @wordpress/scripts with a significantly faster engine and adds automatic PHP registration file generation from your package.json. No more manually writing wp_register_script() calls.

Why Migrate?

  • Speed: esbuild is 10 to 100x faster than webpack for most plugin builds
  • Auto-generated PHP: Registration files are generated automatically, reducing boilerplate
  • Simpler config: Less configuration overhead compared to webpack
  • Official support: Backed by the WordPress core team as the future standard

Step 1: Install @wordpress/build

Remove @wordpress/scripts and install the new package:

npm uninstall @wordpress/scripts
npm install --save-dev @wordpress/build

Step 2: Update Your package.json Scripts

Replace your existing build scripts with the new equivalents:

{
  scripts: {
    build: wp-build,
    start: wp-build --watch
  }
}

Step 3: Configure Your Entry Points

Define your block entry points in package.json using the wpBlocks field. @wordpress/build reads this to know what to compile and what PHP registration files to generate:

{
  wpBlocks: {
    my-block: src/my-block/index.js
  }
}

Step 4: Remove Your webpack.config.js

If you had a custom webpack.config.js extending @wordpress/scripts, evaluate which customizations are still needed. Many common customizations are handled differently in esbuild. Review the official migration guide for specifics.

Step 5: Verify Auto-Generated PHP Files

After running npm run build, check your build directory. You should see auto-generated .asset.php files alongside your compiled JS and CSS. These replace the manual wp_register_script() and wp_register_style() calls you previously wrote by hand.

Step 6: Update Your PHP Enqueue Logic

Your PHP enqueue code should already work if you were using the .asset.php pattern from @wordpress/scripts. The generated file format is compatible:

$asset = include plugin_dir_path( __FILE__ ) . 'build/my-block/index.asset.php';
wp_register_script(
    'my-block-editor',
    plugins_url( 'build/my-block/index.js', __FILE__ ),
    $asset['dependencies'],
    $asset['version']
);

Key Differences to Watch Out For

  • No Babel transforms by default: esbuild handles modern JS natively, but some Babel plugins you relied on may not have esbuild equivalents
  • CSS handling: CSS imports work differently, review the docs for the new CSS pipeline
  • TypeScript: esbuild has native TypeScript support, but it strips types without type-checking. Run tsc –noEmit separately for type validation

Is @wordpress/scripts Going Away?

@wordpress/scripts is not being immediately deprecated, but @wordpress/build is the clear direction for new projects. The migration path is designed to be low-friction, and the WordPress core team recommends starting new plugins with @wordpress/build from day one.

Key Takeaway: The switch from webpack to esbuild is a meaningful developer experience upgrade. Faster builds, less config, and auto-generated PHP registration files make @wordpress/build a compelling upgrade for any active WordPress plugin or block project.

Hashtags: #WordPress #WordPressDev #GutenbergBlocks #WebDevelopment #JavaScript #esbuild #PluginDevelopment

Resources:

Search

Categories

Archives