majiayu000 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