WordPress Block Architecture: A Deep Dive

The Shift to Blocks

The introduction of Gutenberg (the Block Editor) fundamentally changed how WordPress stores and renders content. Instead of a single blob of HTML content, posts are now composed of distinct units called blocks.

This shift brings WordPress closer to modern component-based architectures like React, but with a unique twist: the data is still saved as serialized HTML comments in the database.

Block Anatomy

A typical block consists of three main parts:

1. Block Registration (block.json): Defines metadata like name, attributes, and file paths.
2. Edit Component (edit.js): The React component rendered in the editor interface.
3. Save Component (save.js or PHP render): Defines the output for the frontend.

React in WordPress

Many developers don’t realize that the Block Editor is a full Single Page Application (SPA) built with React. The wp.element package is essentially a wrapper around React.

// Valid block code
const { useState } = wp.element;

export default function Edit() {
    const [count, setCount] = useState(0);
    return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}

Attribute Handling

Attributes are the state of your block. They are serialized into the HTML comment delimiters.

/* Database storage format */
<!-- wp:my-plugin/hero {"title":"Hello World","bg":"blue"} -->
<div class="hero bg-blue"><h1>Hello World</h1></div>
<!-- /wp:my-plugin/hero -->

Correctly defining attribute types and sources is critical for data integrity.

Dynamic vs. Static Blocks

• Static Blocks: The HTML is generated at save time (in JS) and stored in the DB. Fast, but hard to update if the markup changes later.
• Dynamic Blocks: Only the attributes are stored. The HTML is rendered on the server (PHP) at runtime. Ideal for complex logic or frequently changing content.

Best Practices

1. Use block.json: It’s the standard for a reason. It handles asset loading (styles/scripts) efficiently.
2. Avoid jQuery: The editor is React. Don’t mix paradigms.
3. Server-Side Rendering: Prefer dynamic blocks for anything that relies on post data or site settings.

By mastering the block architecture, you unlock the ability to build truly complex, interactive experiences directly within the WordPress editor.