wp-block-development

Fix broken Gutenberg block workflows by updating block.json metadata and rendering.

Updated Sep 22, 2024
One-click install
npx skills add https://github.com/WordPressBugBounty/plugins-woocommerce-for-japan --skill wp-block-development-wordpressbugbounty
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: wp-block-development
Source: https://github.com/WordPressBugBounty/plugins-woocommerce-for-japan/tree/main/woocommerce-for-japan/.claude/skills/wp-block-development
Command: npx skills add https://github.com/WordPressBugBounty/plugins-woocommerce-for-japan --skill wp-block-development-wordpressbugbounty

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

WordPress (Gutenberg) block changes often break attributes, rendering, or compatibility, causing blocks to become “Invalid”, fail to save data, or behave differently between editor and frontend.

Core Features & Use Cases

  • Block triage & discovery: detect the block’s root and enumerate block.json files to focus changes precisely.
  • Correct block metadata & rendering: update block.json safely, choose the right model (static vs dynamic vs interactive), and implement render.php/render_callback patterns.
  • Serialization + deprecations/migrations: address attribute persistence issues and prevent invalid blocks by adding deprecated versions and migration paths.
  • Build/test workflows: align development with @wordpress/scripts and @wordpress/create-block workflows, plus wp-env when needed.

Quick Start

Use the wp-block-development skill to fix a block that inserts correctly but shows “attributes not persisting” after saving by updating the block.json metadata and the attribute serialization pattern, then verifying the block in the editor and frontend.

Frequently Asked Questions about wp-block-development

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does my WordPress block show as invalid after updating block.json attributes?

WordPress blocks become invalid after block.json updates because existing saved content lacks the new attribute serialization schema. You must implement block deprecations and migration paths to safely evolve content and prevent invalid block errors.

How do I add dynamic rendering to an existing Gutenberg block?

To add dynamic rendering to a Gutenberg block, implement a render.php file or render_callback pattern within your block.json configuration. This shifts the block from static HTML saving to server-side rendering for consistent editor and frontend behavior.

When do I need to migrate my WordPress block to apiVersion 3?

You need to migrate your WordPress block to apiVersion 3 when updating block.json metadata to ensure compatibility with current Gutenberg editor standards. This requires updating attribute serialization patterns and verifying registration approaches to prevent rendering failures.

What is the correct way to fix WordPress block attributes not persisting after saving?

Fixing WordPress block attributes that do not persist after saving requires correcting the attribute serialization pattern in block.json. You must align the save function with the schema and verify the block model selection to ensure data retention.

Can I use wp-env and @wordpress/scripts to test block deprecations?

Yes, you can use wp-env and @wordpress/scripts to build and test block deprecations. Aligning your development workflow with these tools allows you to verify deprecated versions and migration paths against editor and frontend rendering failures.

What is the best way to choose between static and dynamic rendering for a Gutenberg block?

Choosing between static and dynamic rendering for a Gutenberg block depends on whether content changes independently of the database. Use render.php for dynamic server-side output, or standard save functions for static HTML, ensuring correct block.json registration.