When developing custom blocks for WordPress, it’s best practice to register them within plugins rather than themes. This strategy guarantees that your blocks stay accessible, even when users switch themes. While there might be situations where embedding blocks directly into a theme could be appropriate, this guide focuses on blocks housed within a plugin. Specifically, it details the file structure as produced by the
Adhering to the
create-block tool’s structure is not mandatory, but it serves as a reliable reference. The files it generates encompass everything needed for a block’s definition and registration. Following this structure can help maintain consistency and ensure your blocks are well-organized and easy to maintain.
When creating a block in a WordPress plugin, you usually register the block on the server in the main PHP file of the plugin. This is done using the
package.json file is used to configure a Node.js project, which is technically what a block plugin is. In this file, you define the
npm dependencies of the block and the scripts used for local development.
In a standard project, the
The build process provided by
wp-scripts will then take the files from this folder and generate the production-ready files in the project’s
block.json file contains the block’s metadata, streamlining its definition and registration across client-side and server-side environments.
When a build process is applied, the
block.json file and the other generated files are moved to a designated folder, often the
build folder. Consequently, the file paths specified within
block.json point to these processed, bundled versions of the files.
A few of the most important properties that can be defined in a
editorScript: Usually set with the path of a bundled
index.jsfile that was built from
style: Usually set with the path of a bundled
style-index.cssfile that was built from
editorStyle: Usually set with the path of a bundled
index.cssthat was built from
render: Usually set with the path of a bundled
render.phpthat was copied from
viewScript: Usually set with the path of a bundled
view.jsthat was built from
index.js file (or any other file defined in the
editorScript property of
registerBlockType function to register the block on the client and typically imports the
save.js files to get the functions required for block registration.
edit.js file contains the React component responsible for rendering the block’s editing user interface, allowing users to interact with and customize the block’s content and settings in the Block Editor. This component gets passed to the
edit property of the
registerBlockType function in the
save.js exports the function that returns the static HTML markup that gets saved to the WordPress database. This function gets passed to the
save property of the
registerBlockType function in the
style file with extensions
.sass contains the styles of the block that will be loaded in both the Block Editor and on the front end. In the build process, this file is converted into
style-index.css, which is usually defined using the
style property in
wp-scripts includes a css-loader chained with postcss-loader and sass-loader that allows it to process CSS, SASS or SCSS files. Check Default webpack config for more info
editor file with extensions
.sass contains the additional styles applied to the block in the Block Editor. You will often use this file for styles specific to the block’s user interface. This file is converted to
index.css during the build process, usually defined using the
editorStyle property in
render.php file (or any other file defined in the
render property of
block.json) defines the server-side process that returns the markup for the block when there is a request from the front end. If defined, this file will take precedence over other ways to render the block’s markup on the front end.
view.js file (or any other file defined in the
viewScript property of
block.json) will be loaded in the front end when the block is displayed.
build folder contains the compiled and optimized versions of the code from the
src folder. These files are generated from the build process, triggered by the
start commands of
build folder’s contents to render the block in the Block Editor and on the front end.
output-path option of
wp-scripts build commands to customize the entry and output points.