README

A developer-focused plugin for developing block themes for WordPress. This plugin provides essential tools for professional WordPress block theme developers to streamline pattern management and template synchronization.

Features

Part 1: Pattern Management

Custom Post Type: btd_pattern for managing block patterns
React Sidebar: Rich metadata editor in the block editor sidebar
Dual Mode Operation:
- File Mode: Saves patterns as .php files in your active theme's /patterns directory
- API Mode: Provides REST API endpoints for pattern data retrieval
Rich Metadata Support:
- Description
- Categories (WordPress core pattern categories)
- Keywords
- Viewport Width
- Block Types
- Post Types
- Template Types
- Inserter Visibility

Part 2: Template Export

Automatic Template Export in File Mode:
- Exports wp_template changes to your active stylesheet theme /templates directory as .html
- Exports wp_template_part changes to your active stylesheet theme /parts directory as .html
Strict Development Guardrails:
- In file mode, successful template exports remove DB overrides so file changes remain the source of truth
- Helps prevent accidental long-lived template data in the database during development

Installation

Clone this repository into your WordPress plugins directory
Run npm install to install dependencies
Run npm run build to build the JavaScript assets
Activate the plugin in your WordPress admin

Configuration

BLOCK_THEME_DEVELOPER_MODE Constant

The plugin behavior is controlled by the BLOCK_THEME_DEVELOPER_MODE constant:

file: Saves patterns as PHP files in your active theme
api: Provides REST API access to pattern data

Setting the Mode

Option 1: wp-config.php (Recommended)

define( 'BLOCK_THEME_DEVELOPER_MODE', 'file' );

Option 2: Automatic Detection If not defined, the plugin will automatically set:

file mode for development or local environments
api mode for all other environments

Usage

Creating Patterns

Go to Patterns in your WordPress admin
Click Add New Pattern
Create your pattern content using the block editor
Fill in the pattern metadata in the Pattern Metadata panel in the sidebar:
- Description
- Categories
- Keywords
- Block Types
- Post Types
- Template Types
- Viewport Width
- Inserter visibility

Importing Existing Theme Patterns

When working with existing themes that have pattern files, you can import them into the database for editing:

Go to Patterns > Import Patterns in your admin menu
Select which pattern files you want to import
Click Import Selected Patterns
Edit the imported patterns using the rich interface
Your changes will automatically update the theme files when you save

Auto-Import: In development environments, the plugin automatically imports any existing theme patterns when first activated.

Exporting Templates and Template Parts

In file mode, saving templates from the Site Editor exports changes directly to the active stylesheet theme:

Templates: /templates/{slug}.html
Template parts: /parts/{slug}.html
Exported block markup is automatically formatted with consistent indentation for improved readability.

When export succeeds, the plugin removes the corresponding database override so local development stays file-first.

Important Notes

Autosaves, revisions, and draft-like states are skipped by guardrails.
Export requires users with edit_theme_options capability.
Filesystem write access must be available to WordPress.
If formatting cannot be safely validated against the original block structure, the plugin falls back to the original content and logs a debug message when WP_DEBUG_LOG is enabled.

Troubleshooting

Enable WP_DEBUG_LOG in your WordPress environment to review export logs.
Failed exports keep DB content intact (no cleanup is performed).

Development Workflow

This plugin supports a hybrid development workflow that's perfect for professional theme development:

Typical Workflow

Development Environment:
- Install plugin as dev dependency
- Import existing theme patterns (auto-imports on activation)
- Edit patterns with rich UI and metadata
- Export to theme files automatically on save
Production Environment:
- Deploy theme files (no plugin needed)
- Patterns work natively in WordPress
- No database records or plugin dependencies
Pull from Production:
- Download production site
- Activate plugin locally
- Auto-import existing theme patterns for editing
- Continue development with full editing capability

Benefits

Development: Rich editing interface with metadata management
Production: Clean, lightweight theme files only
Version Control: Pattern files are easily tracked in Git
Collaboration: Team members can edit patterns visually
Deployment: No plugin dependencies in production

File Mode

When in file mode, patterns are automatically saved to your active theme's /patterns directory as PHP files with proper WordPress pattern headers.

Example generated file:

<?php
/**
 * Title: My Awesome Pattern
 * Description: A simple paragraph pattern for greetings
 * Categories: hero, text
 * Keywords: greeting, hello
 * Viewport Width: 1200
 * Block Types: core/paragraph
 * Post Types: post, page
 * Template Types: author, 404
 * Inserter: yes
 */
?>
<p>Hello world.</p>

API Mode

When in API mode, access pattern data via REST API with WordPress Application Passwords authentication:

Get all patterns:

GET /wp-json/btd/v1/patterns

Get authentication information:

GET /wp-json/btd/v1/auth-info

Setting up Application Passwords

Go to Users > Profile in your WordPress admin
Scroll down to the "Application Passwords" section
Enter a name for your application (e.g., "Client Site")
Click "Add New Application Password"
Copy the generated username and password
Use these credentials for HTTP Basic Authentication

Important: The user must have the btd_api_access capability to access the API. When in API mode, the plugin automatically:

Creates the btd_api_access capability
Creates an API User role with this capability
Assigns the capability to administrators

You can assign this capability to other users or roles using a plugin like User Role Editor.

Example Usage

cURL with Basic Auth:

curl -u "username:password" \
  https://yoursite.com/wp-json/btd/v1/patterns

JavaScript with fetch:

const response = await fetch('/wp-json/btd/v1/patterns', {
  headers: {
    'Authorization': 'Basic ' + btoa('username:password')
  }
});
const patterns = await response.json();

Response format:

{
  "id": 123,
  "title": "My Awesome Pattern",
  "content": "<p>Hello world.</p>",
  "description": "A simple paragraph pattern for greetings",
  "categories": ["hero", "text"],
  "keywords": ["greeting", "hello"],
  "viewportWidth": 1200,
  "blockTypes": ["core/paragraph"],
  "postTypes": ["post", "page"],
  "templateTypes": ["author", "404"],
  "inserter": true
}

Development

Build Process

npm run start - Start development build with file watching
npm run build - Build production assets
npm run lint:js - Lint JavaScript files
npm run lint:css - Lint CSS files
npm run format - Format code with Prettier

Coding Standards

This plugin follows the eighteen73 WordPress Coding Standards.

Run PHP CodeSniffer:

composer test

Requirements

WordPress 6.2+
PHP 8.3+
Node.js 22+ (for development)

License

GPL-2.0-or-later

eighteen73 / block-theme-developer

Maintainers

Package info

Statistics

Security