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}/:

code

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

json

"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