wp-interactivity-api_skill

Overview

This skill helps build and debug WordPress Interactivity API features including data-wp-* directives, @wordpress/interactivity stores/actions, block viewScriptModule integration, and wp_interactivity_*() server helpers. It focuses on performance, hydration correctness, directive behavior, and common failure modes to get interactive blocks and themes working reliably.

How this skill works

Inspect the codebase for directive usage (data-wp-interactive, data-wp-on--*, data-wp-bind--*, data-wp-context) and for viewScriptModule or @wordpress/interactivity imports. Verify store definitions, initial server state, and whether server-side directive processing or supports.interactivity is enabled. Run targeted checks for module loading, hydration mismatches, and common tooling issues.

When to use it

• You see interactive directives that don’t fire or hydrate correctly.
• Building or converting a block to use viewScriptModule and interactivity stores.
• Investigating hydration flicker, layout shift, or initial-state mismatches.
• Adding server-rendered initial state or context for interactive UI.
• Debugging client-side navigation or module loading issues after WP 6.9 changes.

Best practices

• Pre-render interactive HTML and initialize state in PHP with wp_interactivity_state() to avoid layout shift.
• Enable supports.interactivity in block.json or call wp_interactivity_process_directives() for themes/plugins.
• Keep directive usage minimal and scoped to small DOM subtrees to reduce overhead.
• Ensure viewScriptModule is enqueued and the build outputs module-compatible code (check bundler config).
• Replicate derived-state logic in PHP when it affects initial rendering to ensure hydration alignment.

Example use cases

• A block’s click handlers don’t run because viewScriptModule wasn’t enqueued — verify module entry and data-wp-interactive attribute.
• Hydration flicker where hidden bindings differ on load — add derived state in PHP via wp_interactivity_state() to match client logic.
• Converting a theme widget to interactive behavior using data-wp-on--click and a namespaced store.
• Troubleshooting client-side navigation where server state resets between transitions after WP 6.9.
• Adding Playwright E2E tests to confirm directives trigger and state updates propagate.