Steven Slack

WordPress Block Development and Locality of Behaviour

When I began developing blocks for the WordPress block editor, also referred to as Gutenberg, one of the most convenient aspects of the developer experience was the organization of block files. Specifically I mean where the files are located.

All of a blocks files, the JavaScript/Typescript, PHP, CSS/SCSS, and JSON can be authored in the blocks directory effectively encapsulating all the behavior.

The behaviour of a unit of code should be as obvious as possible by looking only at that unit of code The Locality of Behaviour Principle from the HTMX essays

In other development contexts, there is often a focus on the ‘separation of concerns’ principle, which involves segregating JavaScript, HTML, and CSS files into their respective directories within the file system. The bundler would then compile these files accordingly. There is still a strong argument for this pattern. However, the more complex the application becomes the more challenging it can be to find all the behavior associated with a feature or functionality.

The true benefit of locality of behavior lies in enhancing the developer experience. By locating all the block files in the same directory the code becomes more “manageable and maintainable”. When working on a team it is much easier to direct a developer to a directory rather than asking them to “find” all the files that impact the behavior of that block functionality.

When developing blocks with @wordpress/scripts, the build script handles the compilation and transpilation of TypeScript and SASS, while also copying relevant PHP files into the build directory. This feature is particularly useful as it eliminates the need for developers to set up complex file inclusion structures for the block’s entry point.

WordPress itself will handle the inclusion of the scripts and styles by calling them only when the block is present on the page. This in turn is performant for the overall application by excluding unnecessary scripts and styles and unused code.


Locality of behavior is an added benefit of developing blocks in WordPress. It improves maintainability and enhances the developer experience when building Gutenberg blocks.