The landscape of WordPress development is approaching a significant transition as assembly tools prepare for a major technical shift. While most developers currently utilizing the standard scripts package will not notice immediate disruptions, the underlying philosophy and user experience are being rebuilt from the ground up. This evolution is driven by a desire to simplify complex workflows while maintaining the power required for modern web applications.
At the center of this movement is @wordpress/build, a high-performance engine designed to modernize the current development pipeline. By replacing traditional webpack and Babel configurations with a significantly faster mechanism, the tool automates PHP registration and handles multiple asset types in a single pass. It relies on a folder-based discovery system that identifies JavaScript packages and administrative routes automatically, a methodology already proven within the Gutenberg project to manage over one hundred distinct packages.
Despite its potential, the tool is currently in a transitional phase and is not yet optimized for every possible scenario. Developers focusing specifically on block registration may encounter certain limitations that still necessitate manual workarounds to function correctly. As lead developers have noted, identifying these specific edge cases requires broader testing beyond the internal requirements of the Gutenberg repository.
The following report explores the mechanics of @wordpress/build, its practical application within current projects, and the specific areas where the community can provide essential feedback. Understanding these changes is vital for developers who wish to stay ahead of the upcoming convergence of WordPress build utilities.
Summary of technical specifications and development milestones
Strategic vision for a simplified development ecosystem
Since the introduction of the block editor, the existing scripts package has provided a reliable foundation by pre-configuring webpack and managing asset dependencies. However, over the years, this system has accumulated significant complexity due to flexible configurations and custom Babel plugins. Notably, the Gutenberg project itself has historically relied on its own custom tooling rather than the standard scripts provided to the public.
A turning point occurred in October 2025 when Riad Benguella published a vision for the second version of WordPress scripts under issue #72032. The core question was whether the inherent complexity of development could be absorbed by the tools themselves to make plugin creation more intuitive. The goal was a system where adding a new block or admin page required nothing more than placing a folder in the correct directory.
«What if instead of flexibility we put complexity into the tool itself to make plugin development as easy as it should have been?»
The proposed solution moves away from manual configuration in favor of established conventions where code is placed in predefined folders like packages or routes. By using a single build command, the system identifies all entry points and automatically generates the necessary PHP registration files. This eliminates the need for managing entry point lists or complex Babel pipelines, allowing the tool to handle the heavy lifting behind the scenes.
This initiative was formalized in October 2025 with the introduction of @wordpress/build as a standalone package via pull request #72743. It has since become the internal engine for Gutenberg, serving as a testbed for the features that will eventually be rolled out to all plugin developers. The primary focus now is ensuring the tool remains robust enough for the diverse needs of the wider WordPress ecosystem.
Accelerated performance via modern internal engines
The JavaScript ecosystem has largely moved past the era where webpack and Babel were the only viable options for enterprise-grade assembly. Modern tools written in compiled languages such as Go or Rust can now analyze and compile code at speeds that were previously impossible. These engines process files in a single pass, drastically reducing the time required to turn source code into a finished product.
By integrating esbuild – a Go-based bundler – @wordpress/build leverages these performance gains to transform the development cycle. For a project as large as Gutenberg, full build sequences that once took minutes are now completed in a few seconds. When running in watch mode, the tool uses incremental rebuilding to recompile only the modified packages and their direct dependencies, providing almost instant feedback to the developer.
It is important to note that the use of esbuild is considered an internal implementation detail rather than a public API feature. This means the underlying engine could be swapped in the future without changing how developers interact with the tool or its commands. The focus remains on the speed and reliability of the output rather than the specific technology used to generate it.
While speed is a major selling point, the true value of the tool lies in how it manages complexity. Traditional scripts often required thin but flexible wrappers that developers had to configure manually for different use cases. In contrast, @wordpress/build absorbs that complexity internally, providing a rigid but highly efficient set of conventions for the most common development patterns.
Core logic of the discovery mechanism
The operational logic of the tool is built on a discovery model that eliminates the need for manual path mapping. By organizing code into specific top-level folders, developers allow the tool to automatically detect and process each component without additional instructions. This “hands-off” approach is designed to scale from small projects to massive monorepos with dozens of active packages.
- packages/ – Dedicated to JavaScript packages where each subfolder contains its own metadata and source files for automatic detection.
- routes/ – An experimental directory for administrative page routes where each subfolder maps to a specific URL and UI component.
There is also an active proposal under issue #74542 to introduce a dedicated blocks folder following this same pattern. This would allow the system to discover and register blocks automatically, further reducing the amount of boilerplate code required to initialize a new plugin. The intent is to create a predictable structure that any WordPress developer can navigate and understand at a glance.
Because discovery is tied to the folder structure, a separate build configuration file is no longer a requirement for most projects. The tool reads a small set of fields from the existing package metadata to determine how to bundle and register the code. This streamlines the root directory of the plugin and keeps the focus on the source code rather than the build environment.
Developers should be aware that these folder names are currently fixed and cannot be renamed or redirected through command-line flags. If an existing project already uses these names for different purposes, a structural reorganization will be necessary before adopting the new tool. This limitation is a known trade-off of the convention-based model and is a point where developer feedback is highly encouraged.
Structured configuration levels
For settings that cannot be inferred from the folder structure alone, the tool utilizes a two-tier configuration system. This approach ensures that global plugin settings remain separate from individual module requirements, allowing for granular control where necessary. Most of these settings live within the standard package metadata files that developers are already familiar with.
- Root package.json – Handles plugin-wide settings including the namespace, global variable names, and prefixes for script handles.
- Module package.json – Defines specific behavior for each detected unit, such as whether it should be treated as a standard script or an ESM module.
In the Gutenberg repository, the root configuration defines the project name and the global “wp” variable used to expose internal scripts. This ensures that every package built within the project follows a consistent naming convention. It also allows the tool to correctly prefix handles, preventing conflicts with other plugins or core WordPress functionality.
On a package level, simple boolean fields or export definitions tell the build tool how to package the code. A package can be bundled as an Immediately Invoked Function Expression for global access or exposed as a modern script module. Packages requiring web workers also have specific fields to ensure they are compiled as self-contained units loaded via Blob URLs.
This streamlined configuration replaces the dense forests of webpack plugins and Babel presets that previously dominated project roots. By using only a few standardized fields, developers can achieve complex results – such as registering a script as a global WordPress handle – without writing a single line of configuration logic. This transition represents a significant reduction in the technical debt associated with project maintenance.
Automated integration with WordPress PHP
Beyond bundling code, @wordpress/build manages the crucial bridge between JavaScript assets and the WordPress PHP environment. It automatically generates the necessary PHP code to register scripts, modules, and styles within the CMS. This means developers no longer need to manually write hundreds of lines of registration code for complex plugins.
Integration is as simple as including a single generated file within the main plugin logic. This file acts as a loader for the underlying script and style registrations, ensuring that every asset produced by the build tool is correctly recognized by WordPress. It removes the risk of human error when mapping handles to file paths or manually updating asset version numbers.
The generated logic also handles sophisticated dependency tracking by analyzing imports within the JavaScript source. It distinguishes between static and dynamic module imports, allowing WordPress to optimize the import map for better performance. This deep integration ensures that the right scripts are loaded at the right time without the developer having to manage the dependency array manually.
Integrated namespace architecture
Developers familiar with previous assembly tools will recognize how dependencies are typically extracted and mapped to global variables. In older setups, an import from a WordPress package would be converted into a reference to a window-level object at runtime. The new tool takes this concept further by embedding the logic directly into the bundling process for greater consistency.
The namespace configuration of a plugin determines how its internal packages are exposed to the rest of the environment. If a package is configured to be a script, it is wrapped and assigned a specific handle and global path based on the plugin’s metadata. This allows different packages within the same plugin to import from one another while maintaining clean separation and proper loading order.
This architectural model also extends to third-party ecosystems, enabling seamless interaction between different plugins. By declaring the namespace of another plugin as external, a developer can import its components directly into their code. The build tool will automatically resolve these imports to the correct global variables and add the necessary handles to the asset dependencies, ensuring WooCommerce or other tools load before the plugin scripts.
Primary users for current implementation
Contributing members of the Gutenberg project are the most immediate users of this technology, as it currently powers their daily development environment. Understanding how the tool resolves dependencies and transforms files is essential for debugging build issues within the core repository. It provides a window into how the future of WordPress core will be structured and assembled.
Developers who manage complex plugins with numerous scripts or internal packages will also find immediate value in adopting this tool. It is not restricted to monorepos; even single-plugin repositories can use the packages directory to manage multiple entry points efficiently. This approach is ideal for any architecture that currently suffers from overly complex webpack configurations or manual PHP loading logic.
There is a unique opportunity for developers who wish to influence the future of WordPress tooling by testing the API while it is still flexible. By applying the tool to diverse real-world projects, developers can identify friction points and report them to the core team. This feedback is critical for closing the gap between a tool that works for Gutenberg and one that works for the entire community.
For the majority of developers working on simpler projects, the recommendation is to continue using the existing scripts package for the time being. Those using standard block creation tools will receive the benefits of the new engine automatically once the convergence is complete. Waiting for this integration is the most stable path for those who do not require the advanced features of the new system immediately.
Participating in the design and refinement of the tool is vital for its success
This is where the development remains in an active state of flux, and professional experience can directly impact the final product. Several key areas of the tool’s design are still being finalized based on how developers interact with the experimental features. Identifying these “rough edges” now ensures a smoother transition for the entire ecosystem in the coming years.
Proposed block folder structure and registration
The system currently provides experimental support for a routes directory and is moving toward a similar model for blocks. By placing a block’s source files within a dedicated folder, the tool can theoretically handle the entire registration process automatically. This would result in a generated PHP file that manages block metadata without any manual loader code or style registration boilerplate.
This change is intended to become the new default for block creation utilities, replacing older assembly methods. The vision is a streamlined workflow where the mere existence of a block.json file in the correct directory triggers the full build and registration cycle. This would significantly lower the barrier to entry for new developers while speeding up the workflow for veterans.
A major question currently facing the community is whether the proposed folder structure aligns with how developers actually build plugins today. Whether the blocks folder should reside in the root or elsewhere is a topic of active debate that requires input from those outside the core Gutenberg team. Developers whose primary work involves block creation are encouraged to participate in the ongoing discussion under issue #74542.
Furthermore, developers are looking into whether blocks should be registered using the new metadata registry approach introduced in version 6.8. This technical decision will impact how block metadata is stored and accessed by the server, potentially improving performance. Monitoring these technical discussions is essential for anyone building high-performance block plugins.
Challenges for standalone plugin environments
Setting up @wordpress/build outside of a monorepo currently presents several hurdles that are not yet fully documented. It requires specific workspace configurations to resolve imports correctly and necessitates the installation of certain hidden dependencies. These requirements can be daunting for developers used to the “plug and play” nature of previous build scripts.
The project team is actively calling for developers to test the tool in these standalone environments to find and fix these obstacles. Every barrier identified by a third-party developer helps the team bridge the gap between internal utility and public tool. Success in this area is a prerequisite for making the tool the standard for all WordPress development.
Metadata resolution for external dependencies
The assembly process relies on reading metadata from installed packages to decide how imports should be handled. It determines whether to treat an import as a classic global variable or a modern script module, ensuring cross-compatibility between different types of assets. This logic is central to the tool’s ability to manage complex dependency trees without developer intervention.
An ongoing area of concern is whether this model supports all common dependency patterns found in the wild. A recent pull request, #75196, focuses specifically on improving how the tool recognizes dependencies for script modules. Ensuring that these interactions are stable across different plugin architectures remains a high priority for the development team.
Developers who encounter issues with dependency resolution or have suggestions for improvement are encouraged to share their findings. The official Gutenberg repository serves as the central hub for reporting bugs and proposing architectural changes. Transparent communication between the core team and the community is the only way to ensure the tool meets the needs of all users.
Strategic roadmap for tool convergence
It is important to understand that @wordpress/build is not intended to be a separate replacement for the existing scripts package. Instead, it is being designed as the engine that will eventually power those scripts from the inside. This ensures that the ecosystem benefits from the new technology without needing to learn an entirely new set of commands.
The current phase sees the tool as a standalone package used primarily for internal Gutenberg development. The next milestone will involve integrating the build engine into the standard scripts, allowing the existing build command to use the faster Go-based logic. Eventually, the old webpack and Babel pipelines will be deprecated for those using standard configurations.
This roadmap ensures that every developer will eventually gain access to faster builds and automated PHP registration. Features such as RTL style generation and static/dynamic module tracking will become standard parts of the WordPress development experience. The speed and smoothness of this transition depend largely on the feedback received during this early phase of development.
Developers are encouraged to monitor the progress of these changes by following issue #72032 on the official tracker. Engaging with the project now is the best way to ensure the future of WordPress development tools is built for everyone. As the API stabilizes, the path toward a more efficient and simplified assembly process will become clear for all plugin authors.
