Superpowers Sage:wp Block Native

Native WordPress Block Development

When to use

When building editor blocks that require capabilities beyond what ACF Composer provides: InnerBlocks nesting, block transforms, block variations, JS-heavy editor UI, or block deprecations. Also use when you need fine-grained control over the editor experience or when a block's primary complexity is in its editor behavior rather than its field configuration.

Inputs required

• The block's purpose and editor behavior requirements
• Whether ACF Composer could handle it (use the decision table below)
• Target WordPress version (determines apiVersion and available block supports)
• Whether the block needs InnerBlocks, transforms, or deprecations

Procedure

1. Decision table: ACF Composer vs Native blocks

Both can coexist in the same project. ACF blocks and native blocks appear side by side in the inserter.

2. Block structure in a Sage project

resources/
  scripts/
    editor/
      blocks/
        hero/
          index.js          # Block registration (edit + save)
          edit.js            # Editor component
          save.js            # Save component (or null for dynamic)
          style.css          # Front-end styles
          editor.css         # Editor-only styles
          block.json        # Block metadata

3. block.json

See references/block-json-native.md for full field reference and attribute source types.

Use apiVersion 3 for WordPress 6.3+. Key fields: name, attributes, supports, editorScript, render.

4. edit and save functions

See references/edit-save.md for complete edit/save examples, deprecations, and ServerSideRender.

• edit — React component; interactive; output not stored
• save — pure function; stored HTML; must match on re-parse
• Add deprecations whenever saved markup changes

5. Dynamic blocks (PHP render)

See references/dynamic-blocks.md for PHP render templates, Blade integration, and InnerBlocks with dynamic rendering.

For blocks that query WordPress data, set save: () => null and use the render field in block.json:

// render.php — receives $attributes, $content, $block
<div <?php echo get_block_wrapper_attributes(['class' => 'hero']); ?>>
    <?php echo $content; ?>
</div>

6. Vite integration

See references/vite-integration.md for Vite configuration, @wordpress/* externals, and the single-bundle vs per-block entry pattern.

Key: declare @wordpress/* packages as externals in Vite — do not bundle them. Enqueue via enqueue_block_editor_assets:

add_action('enqueue_block_editor_assets', function () {
    wp_enqueue_script(
        'sage-editor-blocks',
        Vite::asset('resources/scripts/editor/index.js'),
        ['wp-blocks', 'wp-element', 'wp-block-editor', 'wp-components'],
        null,
        true
    );
});

7. InnerBlocks

import { useBlockProps, useInnerBlocksProps } from '@wordpress/block-editor';

export default function Edit() {
    const blockProps = useBlockProps({ className: 'card-grid' });
    const innerBlocksProps = useInnerBlocksProps(blockProps, {
        allowedBlocks: ['sage/card', 'core/paragraph'],
        template: [['sage/card', {}], ['sage/card', {}]],
        templateLock: false,
    });
    return <div {...innerBlocksProps} />;
}

Verification

1. Block appears in the editor inserter under the correct category.
2. Block renders correctly in the editor (edit component).
3. Block saves without validation errors (save component matches output).
4. Block renders correctly on the front end (PHP render or saved HTML).
5. Block supports (color, spacing, typography) apply styles correctly.
6. Deprecations: edit a post with an old version of the block, update the block code, and confirm the editor recovers gracefully.
7. InnerBlocks: child blocks can be added, removed, and reordered within the parent.

Failure modes

Escalation

• If block deprecations are not recovering old content, check that the deprecated save function exactly reproduces the old output. Use browser console to compare expected vs actual HTML.
• If register_block_type() silently fails, enable WP_DEBUG and check for errors. Common cause: invalid block.json syntax or missing required fields.
• When the editor experience requires extensive custom JS, consider whether a plugin-based approach might be cleaner than embedding everything in the theme.