eighteen73 / block-theme-developer
A developer focused companion plugin for building block themes for WordPress.
Installs: 15
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Type:wordpress-plugin
pkg:composer/eighteen73/block-theme-developer
Requires (Dev)
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
- File Mode: Saves patterns as
- Rich Metadata Support:
- Description
- Categories (WordPress core pattern categories)
- Keywords
- Viewport Width
- Block Types
- Post Types
- Template Types
- Inserter Visibility
Part 2: Template Export (Coming Soon)
Template and template part export functionality will be implemented in a future update.
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 fordevelopment
orlocal
environmentsapi
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.
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 watchingnpm run build
- Build production assetsnpm run lint:js
- Lint JavaScript filesnpm run lint:css
- Lint CSS filesnpm 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