Resource Block Configuration (blocks)

WPKernel's primary block development workflow is discovery-based: the CLI automatically finds and registers any block.json files in your project. This is the recommended approach for most blocks. For more details on this modern workflow, please see the Blocks Guide.

In addition to that, the resources.<key>.blocks object in wpk.config.ts provides an optional, config-driven way to generate a block scaffold that is explicitly tied to a specific resource. You can use this when you want WPKernel to create the initial block files for a resource you are defining.

---

resources.<key>.blocks

Adding this object inside a resource definition tells WPKernel:

“Generate a starter Gutenberg block for this resource.”

The generator produces:

• a canonical block.json
• an editor script entrypoint (React/JS)
• a PHP registration helper
• optionally, a PHP render callback file

Once generated, these files behave as ordinary blocks, you edit, extend, and evolve them manually.
WPKernel does not regenerate or overwrite your customisations after the first scaffold.

---

mode

This property determines whether the block’s frontend output is rendered:

• entirely in JavaScript (client-rendered), or
• by WordPress/PHP (server-rendered).

mode: 'js' (default)

A client-rendered block.
This is the standard block model in modern Gutenberg:

• Editor UI runs in JavaScript.
• Frontend output is produced entirely by JavaScript when the post is rendered.
• The block’s saved representation (HTML or comment-based attributes) is what appears on the frontend.

When to use it

• Your block’s UI is static, interactive, or editor-driven.
• It doesn’t need PHP involvement for output.
• The block’s content can be saved directly in post content (the default for most blocks).
• You prefer “pure JS” blocks that behave like native Gutenberg components.

This matches how the majority of WordPress and core blocks are written today.

---

mode: 'ssr'

A server-rendered block, also called a PHP render callback block in WordPress.

This is not React SSR.
This is not hydration.
This does not fetch dynamic data automatically.
This is simply the WordPress block model where the frontend output is generated by a PHP function registered via render_callback.

What it does

• The block’s save function is omitted — it becomes a “dynamic block”.
• WordPress calls your PHP callback (render.php) whenever the block appears in post content.
• The callback receives block attributes and context and returns HTML.

When to use it

Use server-rendered blocks when:

• The block’s final HTML must be generated at page load, not saved as static content.
• You need PHP runtime access:
  • template functions
  • WordPress APIs
  • permission checks
  • contextual data
  • server configuration
• You want block output that updates automatically when underlying data changes.
• You want to avoid storing large HTML payloads in post content.

Examples:

• A “Latest Posts” or “Recent Comments” block.
• A block whose output depends on theme config, options, or user state.
• A block that must respect WordPress filters or template tags.

Important clarification (modern WordPress)

Server-rendered blocks do not automatically “mirror server truth” in the sense of API fetches or real-time data.
They simply render using PHP at request time.

This is the correct, modern definition of SSR in Gutenberg:
→ frontend = PHP output; editor = JS preview/editor UI.

---

Generated Artifacts

When a resource includes blocks, WPKernel generates the following canonical files under:

.wpk/blocks/<resource>/**

This includes:

• block.json
• Editor entrypoint (e.g. edit.js or index.js)
• PHP registration helper (e.g. Blocks/Register.php)
• render.php if mode: 'ssr'

If your project defines directory overrides (e.g., directories.blocks: 'src/blocks'), these canonical files are applied to those paths when you run:

wpk apply

From that point forward, you own the files. They are ordinary WordPress block assets.

---

Schema

• Type: object
• Required: No
• Properties:
  • mode: 'js' | 'ssr'