Block Development Environment

The packages are released together from the Gutenberg monorepo; the Gutenberg plugin (24.2.0) is not needed to build blocks. @wordpress/scripts went from the 30.x line used with WordPress 6.9 to 37.0.0 within 2026, with the breaking changes listed in Corrections to older books and tutorials.

The Block Editor Handbook recommends the Node.js Active LTS release, installed with a version manager such as nvm so that each project can select the version it was built with. The current packages accept these ranges:

Node.js 22 has been a Maintenance LTS release since 2025-10-21 and Node.js 24 since 2026-10-20; Node.js 26 is scheduled to become Active LTS on 2026-10-28. Node.js 24 was used for this page and is the safer choice for a team today, since all three packages are tested with it. With nvm:

Source: Block Editor Handbook: Node.js development environment

An engines field in the plugin’s package.json documents the range for everyone else, and wp-scripts check-engines enforces it (since 36.0.0 it checks only the tools listed in engines, and only Node.js when the field is absent).

npm 11.19 blocks the install scripts of dependencies by default: an install ends with a list of packages whose install/postinstall scripts were skipped, and npm install-scripts approve <pkg> records an exception in the allowScripts field of package.json. The @wordpress/scripts 37.0.0 tree has five such packages (core-js, core-js-pure, fs-ext-extra-prebuilt, unrs-resolver and @parcel/watcher); every command on this page worked without approving any of them, so there is no need to approve them blindly.

create-block is run with npx, pinned to a version so the result is reproducible. Given a slug it runs in quick mode: the slug becomes the folder name, the plugin name and the block’s name after the namespace. The options:

Source: Block Editor Handbook: @wordpress/create-block

wp-scripts is meant to be called from the scripts section of package.json (or with npx wp-scripts <command>). The commands in version 37.0.0:

Source: Block Editor Handbook: @wordpress/scripts

Common options of build and start: --source-path (default src), --output-path (default build), --blocks-manifest, --experimental-modules, --webpack-copy-php, --webpack-no-externals and --webpack-bundle-analyzer. A webpack.config.js at the project root replaces the default configuration; extending it means spreading require( '@wordpress/scripts/config/webpack.config' ) and still running wp-scripts, never webpack directly.

WordPress already loads React, ReactDOM and every @wordpress/* package in the editor as registered scripts (react, wp-blocks, wp-block-editor …). A block must use those copies: a second React in the page breaks hooks and context, and bundling @wordpress/block-editor would duplicate megabytes of code that is already there. The dependency extraction plugin in the wp-scripts webpack configuration therefore turns each import of a WordPress-provided package into a reference to a global, and records the script handle it needs:

Source: Block Editor Handbook: @wordpress/dependency-extraction-webpack-plugin

The minified book-card/index.js starts like this; no React or editor code is inside it:

Source: Block Editor Handbook: Working with JavaScript for the Block Editor

Next to it, index.asset.php returns the handles and a content hash:

Source: Block Editor Handbook: @wordpress/dependency-extraction-webpack-plugin

The list follows the imports. Adding import { useState } from 'react'; and import { Button } from '@wordpress/components'; to edit.js and rebuilding adds react and wp-components to the array, while the bundle grows only from 1,249 to 1,285 bytes. Building the same file with --webpack-no-externals (which turns the extraction off) produced a 4,314,995-byte index.js and no asset file at all: React, the components and the block editor copied into the plugin.

How WordPress uses the file:

Hard-coding the dependency array or the version instead of reading the asset file is the classic mistake: a new import then fails with wp.components is undefined at runtime, and a fixed version keeps serving stale code from browser caches.

create-block generates one plugin per block. Lumen Press keeps all its blocks in lumen-catalog, the plugin that also owns the lp_book post type, so the three scaffolds are moved under src/blocks/ and built by one package.json. src/ also holds the namespaced PHP classes autoloaded by Composer (see Plugin Fundamentals):

Source: Block Editor Handbook: @wordpress/scripts, automatic block.json detection

Source: Block Editor Handbook: @wordpress/scripts

The build writes build/blocks/blocks-manifest.php and one folder per block with the same files create-block produced: block.json, index.js, index.asset.php and the four CSS files for each block, render.php for latest-books and wishlist, and view.js with view.asset.php for wishlist.

Lumen\Catalog\Blocks passes build/blocks and its manifest to wp_register_block_types_from_metadata_collection() on init; the class and the errors it can raise are in block.json and Registration. The scaffold’s .gitignore does not ignore build/. Lumen Press ignores it and builds in CI (see Deployment and CI/CD); a plugin installed straight from a Git checkout has to commit it instead, or the blocks are not registered.

lint:js, lint:css, format and test:unit all passed on this project after the fixes listed for the interactive template, and php -l found no syntax errors in the PHP files, blocks-manifest.php and the asset files.

wp-env mounts the plugin folder into a WordPress container and activates it, so npm start in one terminal and the editor in a browser give an edit-save-reload loop with no copying. The plugin’s own .wp-env.json:

Source: Block Editor Handbook: @wordpress/env

The full option list, the override file and the other runtimes are in Local Development Environments. The working session:

Source: Block Editor Handbook: Get started with wp-env

The first start took 78 seconds (image builds and the WordPress download); wp core version then reported 7.1.3 and wp plugin list showed lumen-catalog active at version 0.1.0, next to the inactive Akismet and Hello Dolly.

A WP-CLI one-liner lists what was registered from the manifest, with the asset handles WordPress derived from block.json:

Source: WP-CLI Commands: wp eval

Source: Code Reference: WP_Block_Type

The blocks are offered in the inserter’s Widgets category (the category of their block.json) in the post editor at http://localhost:8888/wp-admin/post-new.php. This is the plugin as scaffolded; block.json and Registration then moves the blocks to the plugin’s own lumen-catalog category and gives lumen/latest-books a view.js module that formats its dates, so from there on its view_modules is no longer empty. A page containing all three, created with wp post create and fetched with curl, showed what reaches the front end: the three style-index.css files inlined as <style id="lumen-…-style-inline-css"> (WordPress inlines small block styles), no script for the two blocks without front-end code, the @wordpress/interactivity import map and a <script type="module"> for wishlist/view.js, and the global state from wp_interactivity_state() as a JSON <script> element. Block assets are enqueued only on pages that contain the block.

With npm start running, saving edit.js triggers an incremental rebuild (a one-off development build of the three blocks took under a second) and a browser reload of the editor shows the change. Changes to block.json regenerate the manifest, and an edited render.php reaches WordPress only once the watcher (or a build) has copied it to build/, because WordPress reads the copy. Because the post editor is always iframed in 7.1, editor styles must be declared in block.json (editorStyle, style) rather than enqueued globally on admin_enqueue_scripts, which no longer reaches the content inside the iframe.

None of the three older books covers block development: the site-owner books stop at using the editor, and the developer-oriented one teaches classic themes and PHP plugins only, so readers coming from them have no build toolchain at all. Tutorials of the WordPress 5.x and 6.x era contain steps that no longer hold: