Skip to main content
How to Use block.json to Register Gutenberg Blocks the Right Way
Back to Blog
WordPressGutenbergBlock Development

How to Use block.json to Register Gutenberg Blocks the Right Way

E

Emre Ekener

22 Nov 2026

7 min read

block.json is the one file that defines a custom Gutenberg block. Learn the fields that matter, how to register blocks in PHP and how to load assets only where needed.

Every custom Gutenberg block should start with one file: block.json. It tells WordPress the block's name, its attributes, which scripts and styles belong to it, and how to render it. If your block still registers its assets by hand, you are building it the old way, and your visitors pay for it in page weight.

I see this regularly when I take over existing WordPress projects. The block works in the editor, but its CSS and JavaScript load on every page of the site, whether the block is there or not. A proper block.json fixes that without extra code.

This guide shows how I set up block.json in client projects: the fields that matter, how to register the block in PHP, how to load assets only when the block is used, and the mistakes I fix most often.

Where block.json Lives

Each block gets its own folder with a block.json at the root. In a plugin built with @wordpress/scripts, the source files sit in src/ and the build output goes to build/. The build step copies block.json into build/, and that copy is the one WordPress reads.

Block plugin file structure in VS Code showing block.json next to the edit and save files

A typical block folder holds:

  • block.json: the block's definition
  • index.js: registers the block in the editor
  • edit.js and save.js: the editor interface and the saved markup
  • style.scss and editor.scss: frontend and editor-only styles
  • render.php: the server-side template, for dynamic blocks only

Keep one block per folder. When a plugin has several blocks, each folder has its own block.json, and the plugin registers them in a loop.

A Minimal block.json

Here is a small, complete example for a call to action block:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "ekener/cta",
  "version": "1.0.0",
  "title": "Call to Action",
  "category": "design",
  "icon": "megaphone",
  "description": "A headline, short text and a button.",
  "textdomain": "ekener-blocks",
  "attributes": {
    "heading": { "type": "string", "default": "" },
    "buttonUrl": { "type": "string", "default": "" }
  },
  "supports": {
    "align": ["wide", "full"],
    "color": { "background": true, "text": true },
    "spacing": { "padding": true }
  },
  "editorScript": "file:./index.js",
  "editorStyle": "file:./index.css",
  "style": "file:./style-index.css"
}

The fields that matter most:

  • $schema: gives your editor autocomplete and validation for the whole file. It costs one line, and I include it every time.
  • apiVersion: use 3, the current version. It loads the block inside the iframed editor, so its styles stay isolated from the admin interface.
  • name: a unique namespace/block-name. It must match everywhere the block is referenced, including your JavaScript and any saved content.
  • attributes: the data the block stores. Give every attribute a type and a default.
  • supports: turns on core features such as colour, spacing and alignment. Use these instead of writing your own controls. You get tested UI, theme.json integration and less code to maintain.
  • textdomain: needed for translating the strings in the file.

Registering the Block in PHP

Once block.json exists, registering the block takes one function call. Point register_block_type() at the folder that contains the file:

function ekener_register_blocks() {
    register_block_type( __DIR__ . '/build/cta' );
}
add_action( 'init', 'ekener_register_blocks' );

WordPress reads block.json, registers the block and its scripts and styles, and handles the asset dependencies and versions for you. You do not call wp_register_script() or wp_enqueue_script() yourself.

In the editor script, import the metadata and pass it along:

import { registerBlockType } from '@wordpress/blocks';
import metadata from './block.json';
import Edit from './edit';
import save from './save';

registerBlockType( metadata.name, { edit: Edit, save } );

Registering on the server is not optional if you want the block's assets to load conditionally. It is also required for dynamic blocks. I register every block in PHP, even simple static ones.

Loading Assets the Right Way

This is the part that matters for performance. block.json has separate fields for each place an asset can load:

| Field | Loads in | When | | --- | --- | --- | | editorScript | Editor | When the editor loads | | editorStyle | Editor | When the editor loads | | style | Editor and frontend | On the frontend only if the block is on the page | | viewScript | Frontend | Only if the block is on the page | | viewScriptModule | Frontend | Only if the block is on the page, as an ES module (WordPress 6.5 and later) |

The frontend rows are the important ones. A block's style and viewScript files load only on pages that actually contain the block. A slider block with 40 KB of JavaScript does not slow down your contact page.

Compare that with the old pattern: one wp_enqueue_script() call hooked to wp_enqueue_scripts, which loads the file on every request. That is one of the quiet reasons WordPress sites feel slow, and it is the kind of thing I look for in a performance audit.

Two practical tips:

  • Put frontend interactivity in viewScript or viewScriptModule, never in editorScript. Editor code should not ship to visitors.
  • Keep editorStyle for editor-only rules, such as outlines and placeholders, so they never reach the frontend.

Dynamic Blocks with render

Some blocks should not save their markup in the database. A latest posts list, a price table that reads from post meta or a block that depends on the current user are better rendered on the server. For those, add a render field:

"render": "file:./render.php"

Then create render.php in the same folder:

<?php
$heading = $attributes['heading'] ?? '';
?>
<div <?php echo get_block_wrapper_attributes(); ?>>
    <h2><?php echo esc_html( $heading ); ?></h2>
    <?php echo wp_kses_post( $content ); ?>
</div>

WordPress gives the file three variables: $attributes, $content and $block. In the editor, save returns null for a dynamic block, so nothing is stored in the post content except the block comment and its attributes.

Two things I always do here. I call get_block_wrapper_attributes() so the block picks up its classes, alignment and the support settings from block.json. And I escape every value on output, because a dynamic block is PHP code running on the live site.

Common Mistakes

These are the problems I fix most often when I work on existing block plugins:

  1. Registering scripts by hand next to a block.json. The block already declares its assets. A second wp_enqueue_script() call loads the same file on every page and undoes the main benefit of block.json.
  2. A name without a namespace, or a name that differs between files. The block name must be namespace/block-name and identical in block.json and everywhere else it appears. A mismatch gives you a block that shows as unsupported.
  3. Pointing file: paths at src/ instead of build/. The paths in block.json are relative to the file WordPress reads. If you register the build/ folder, the paths must match the built files.
  4. Forgetting to rebuild. Editing src/block.json changes nothing until the build copies it. If a change does not show up, run the build before debugging anything else.
  5. Attributes without a type or default. Untyped attributes behave unpredictably and make block validation errors harder to trace.
  6. Changing save output without a deprecation. Any change to saved markup breaks existing instances of the block. Add a deprecated version so older posts keep working.
  7. Skipping supports. Custom colour and spacing controls written from scratch add code and ignore the theme's settings. Most of the time a supports entry does the same job better.

Wrapping Up

A good block.json makes a block easier to maintain and faster for visitors. It declares everything about the block in one place, registers with a single PHP function call and loads its assets only on pages that use it.

A custom Gutenberg block in the WordPress editor

If you are new to block development, start with How to Build Your First Custom Gutenberg Block from Scratch and How to Create a Custom Block Plugin for WordPress. For blocks that contain other blocks, read How to Create an Inner Blocks Area in Your Custom Gutenberg Block.

If you need a custom block plugin built properly from the start, with clean registration and fast asset loading, you can get in touch.

WordPressGutenbergBlock Development

Share this article

Next Article

WordPressFreelanceDevelopment

Why Cheap WordPress Development Costs More in the Long Run