Wp Block Development

1---
2name: wp-block-development
3description: "Use when developing WordPress (Gutenberg) blocks: block.json metadata, register_block_type(_from_metadata), attributes/serialization, supports, dynamic rendering (render.php/render_callback), deprecations/migrations, viewScript vs viewScriptModule, and @wordpress/scripts/@wordpress/create-block build and test workflows."
4compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
5---
6 
7# WP Block Development
8 
9## When to use
10 
11Use this skill for block work such as:
12 
13- creating a new block, or updating an existing one
14- changing `block.json` (scripts/styles/supports/attributes/render/viewScriptModule)
15- fixing “block invalid / not saving / attributes not persisting”
16- adding dynamic rendering (`render.php` / `render_callback`)
17- block deprecations and migrations (`deprecated` versions)
18- build tooling for blocks (`@wordpress/scripts`, `@wordpress/create-block`, `wp-env`)
19 
20## Inputs required
21 
22- Repo root and target (plugin vs theme vs full site).
23- The block name/namespace and where it lives (path to `block.json` if known).
24- Target WordPress version range (especially if using modules / `viewScriptModule`).
25 
26## Procedure
27 
28### 0) Triage and locate blocks
29 
301. Run triage:
31   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
322. List blocks (deterministic scan):
33   - `node skills/wp-block-development/scripts/list_blocks.mjs`
343. Identify the block root (directory containing `block.json`) you’re changing.
35 
36If this repo is a full site (`wp-content/` present), be explicit about *which* plugin/theme contains the block.
37 
38### 1) Create a new block (if needed)
39 
40If you are creating a new block, prefer scaffolding rather than hand-rolling structure:
41 
42- Use `@wordpress/create-block` to scaffold a modern block/plugin setup.
43- If you need Interactivity API from day 1, use the interactive template.
44 
45Read:
46- `references/creating-new-blocks.md`
47 
48After scaffolding:
49 
501. Re-run the block list script and confirm the new block root.
512. Continue with the remaining steps (model choice, metadata, registration, serialization).
52 
53### 2) Ensure apiVersion 3 (WordPress 6.9+)
54 
55WordPress 6.9 enforces `apiVersion: 3` in the block.json schema. Blocks with apiVersion 2 or lower trigger console warnings when `SCRIPT_DEBUG` is enabled.
56 
57**Why this matters:**
58- WordPress 7.0 will run the post editor in an iframe regardless of block apiVersion.
59- apiVersion 3 ensures your block works correctly inside the iframed editor (style isolation, viewport units, media queries).
60 
61**Migration:** Changing from version 2 to 3 is usually as simple as updating the `apiVersion` field in `block.json`. However:
62- Test in a local environment with the iframe editor enabled.
63- Ensure any style handles are included in `block.json` (styles missing from the iframe won't apply).
64- Third-party scripts attached to a specific `window` may have scoping issues.
65 
66Read:
67- `references/block-json.md` (apiVersion and schema details)
68 
69### 3) Pick the right block model
70 
71- **Static block** (markup saved into post content): implement `save()`; keep attributes serialization stable.
72- **Dynamic block** (server-rendered): use `render` in `block.json` (or `render_callback` in PHP) and keep `save()` minimal or `null`.
73- **Interactive frontend behavior**:
74  - Prefer `viewScriptModule` for modern module-based view scripts where supported.
75  - If you're working primarily on `data-wp-*` directives or stores, also use `wp-interactivity-api`.
76 
77### 4) Update `block.json` safely
78 
79Make changes in the block’s `block.json`, then confirm registration matches metadata.
80 
81For field-by-field guidance, read:
82- `references/block-json.md`
83 
84Common pitfalls:
85 
86- changing `name` breaks compatibility (treat it as stable API)
87- changing saved markup without adding `deprecated` causes “Invalid block”
88- adding attributes without defining source/serialization correctly causes “attribute not saving”
89 
90### 5) Register the block (server-side preferred)
91 
92Prefer PHP registration using metadata, especially when:
93 
94- you need dynamic rendering
95- you need translations (`wp_set_script_translations`)
96- you need conditional asset loading
97 
98Read and apply:
99- `references/registration.md`
100 
101### 6) Implement edit/save/render patterns
102 
103Follow wrapper attribute best practices:
104 
105- Editor: `useBlockProps()`
106- Static save: `useBlockProps.save()`
107- Dynamic render (PHP): `get_block_wrapper_attributes()`
108 
109Read:
110- `references/supports-and-wrappers.md`
111- `references/dynamic-rendering.md` (if dynamic)
112 
113### 7) Inner blocks (block composition)
114 
115If your block is a “container” that nests other blocks, treat Inner Blocks as a first-class feature:
116 
117- Use `useInnerBlocksProps()` to integrate inner blocks with wrapper props.
118- Keep migrations in mind if you change inner markup.
119 
120Read:
121- `references/inner-blocks.md`
122 
123### 8) Attributes and serialization
124 
125Before changing attributes:
126 
127- confirm where the attribute value lives (comment delimiter vs HTML vs context)
128- avoid the deprecated `meta` attribute source
129 
130Read:
131- `references/attributes-and-serialization.md`
132 
133### 9) Migrations and deprecations (avoid "Invalid block")
134 
135If you change saved markup or attributes:
136 
1371. Add a `deprecated` entry (newest → oldest).
1382. Provide `save` for old versions and an optional `migrate` to normalize attributes.
139 
140Read:
141- `references/deprecations.md`
142 
143### 10) Tooling and verification commands
144 
145Prefer whatever the repo already uses:
146 
147- `@wordpress/scripts` (common) → run existing npm scripts
148- `wp-env` (common) → use for local WP + E2E
149 
150Read:
151- `references/tooling-and-testing.md`
152 
153## Verification
154 
155- Block appears in inserter and inserts successfully.
156- Saving + reloading does not create “Invalid block”.
157- Frontend output matches expectations (static: saved markup; dynamic: server output).
158- Assets load where expected (editor vs frontend).
159- Run the repo’s lint/build/tests that triage recommends.
160 
161## Failure modes / debugging
162 
163If something fails, start here:
164 
165- `references/debugging.md` (common failures + fastest checks)
166- `references/attributes-and-serialization.md` (attributes not saving)
167- `references/deprecations.md` (invalid block after change)
168 
169## Escalation
170 
171If you’re uncertain about upstream behavior/version support, consult canonical docs first:
172 
173- WordPress Developer Resources (Block Editor Handbook, Theme Handbook, Plugin Handbook)
174- Gutenberg repo docs for bleeding-edge behaviors
175