Native Block Development

Creating native WordPress blocks for the Oh My Brand! FSE theme using @wordpress/scripts.

When to Use

Creating new WordPress blocks with editor and frontend components
Configuring block metadata and supports
Writing PHP render templates for server-side rendering
Registering block assets (styles, scripts)

Block File Structure

Every block lives in src/blocks/{block-name}/:

src/blocks/gallery/
├── block.json          # Block metadata and registration
├── index.js            # Block registration entry point
├── edit.tsx            # Editor React component
├── render.php          # Server-side render template
├── helpers.php         # Block-specific helper functions
├── style.css           # Frontend styles (auto-enqueued)
├── editor.css          # Editor-only styles (optional)
├── view.ts             # Frontend TypeScript (Web Component)
└── view.test.ts        # Unit tests

File Templates

Use templates from block-scaffolds:

| File | Template | Purpose | |------|----------|---------| | block.json | block-json-native.json | Block metadata | | render.php | render-native.php | Server-side render | | helpers.php | helpers-native.php | Helper functions | | view.ts | view.ts | Frontend Web Component | | style.css | style.css | Frontend styles | | edit.tsx | edit.tsx | Editor component |

block.json Key Properties

| Property | Required | Description | |----------|----------|-------------| | $schema | Yes | https://schemas.wp.org/trunk/block.json | | apiVersion | Yes | Always use 3 | | name | Yes | Format: theme-oh-my-brand/{block-name} | | version | Yes | Semantic version (e.g., 1.0.0) | | textdomain | Yes | theme-oh-my-brand | | render | Yes | file:./render.php | | editorScript | Yes | file:./index.js | | viewScript | Optional | file:./view.js for frontend JS | | style | Yes | file:./style.css |

Common Supports

"supports": {
    "align": ["wide", "full"],
    "anchor": true,
    "className": true,
    "color": {
        "background": true,
        "text": true
    },
    "spacing": {
        "margin": true,
        "padding": true,
        "blockGap": true
    }
}

Render Template Guidelines

| Guideline | Description | |-----------|-------------| | declare(strict_types=1) | Always include at top | | Early return | Return early if no data to display | | get_block_wrapper_attributes() | Use for consistent wrapper | | Escape all output | esc_html(), esc_attr(), esc_url() | | Unique IDs | Use wp_unique_id() for instances | | Web Component wrapper | Use <omb-{block-name}> for frontend JS |

Helper Function Guidelines

| Guideline | Description | |-----------|-------------| | Function prefix | Use omb_{block_name}_ prefix | | function_exists() guard | Wrap in existence check | | Type hints | Use parameter and return types | | DocBlocks | Include @param and @return |

Asset Handling

Automatic Loading

Assets defined in block.json are automatically enqueued:

| Property | When Loaded | |----------|-------------| | style | Frontend and editor | | editorStyle | Editor only | | editorScript | Editor only | | viewScript | Frontend only |

Assets only load when the block is present on the page.

Step-by-Step Creation

Create directory: mkdir -p src/blocks/my-block
Add block.json: Copy from template, replace placeholders
Create edit.tsx: See block-editor-components
Create render.php: Copy from template
Create helpers.php: Copy from template
Create view.ts: See web-components
Add style.css: See css-standards
Write tests: See vitest-testing
Build: pnpm run build
Verify: Check block appears in editor

Related Skills

block-scaffolds - Copy-paste templates
web-components - Frontend view scripts
block-editor-components - Editor components
php-standards - PHP conventions
css-standards - CSS conventions
acf-block-registration - ACF blocks

native-block-development