PHPackages                             eighteen73/block-theme-developer - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. eighteen73/block-theme-developer

ActiveWordpress-plugin[Utility & Helpers](/categories/utility)

eighteen73/block-theme-developer
================================

A developer focused companion plugin for building block themes for WordPress.

v1.4.0(2w ago)166[1 issues](https://github.com/eighteen73/block-theme-developer/issues)PHP

Since Sep 19Pushed 3mo agoCompare

[ Source](https://github.com/eighteen73/block-theme-developer)[ Packagist](https://packagist.org/packages/eighteen73/block-theme-developer)[ RSS](/packages/eighteen73-block-theme-developer/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (10)Dependencies (3)Versions (16)Used By (0)

Block Theme Developer
=====================

[](#block-theme-developer)

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
--------

[](#features)

### Part 1: Pattern Management

[](#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

[](#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
------------

[](#installation)

1. Clone this repository into your WordPress plugins directory
2. Run `npm install` to install dependencies
3. Run `npm run build` to build the JavaScript assets
4. Activate the plugin in your WordPress admin

Configuration
-------------

[](#configuration)

### BLOCK\_THEME\_DEVELOPER\_MODE Constant

[](#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

[](#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
-----

[](#usage)

### Creating Patterns

[](#creating-patterns)

1. Go to **Patterns** in your WordPress admin
2. Click **Add New Pattern**
3. Create your pattern content using the block editor
4. 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

[](#importing-existing-theme-patterns)

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

1. Go to **Patterns > Import Patterns** in your admin menu
2. Select which pattern files you want to import
3. Click **Import Selected Patterns**
4. Edit the imported patterns using the rich interface
5. 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

[](#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

[](#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

[](#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
--------------------

[](#development-workflow)

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

### **Typical Workflow**

[](#typical-workflow)

1. **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
2. **Production Environment**:

    - Deploy theme files (no plugin needed)
    - Patterns work natively in WordPress
    - No database records or plugin dependencies
3. **Pull from Production**:

    - Download production site
    - Activate plugin locally
    - Auto-import existing theme patterns for editing
    - Continue development with full editing capability

### **Benefits**

[](#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

[](#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:

```

Hello world.
```

### API Mode

[](#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

[](#setting-up-application-passwords)

1. Go to **Users > Profile** in your WordPress admin
2. Scroll down to the **"Application Passwords"** section
3. Enter a name for your application (e.g., "Client Site")
4. Click **"Add New Application Password"**
5. Copy the generated username and password
6. 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

[](#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": "Hello world.",
  "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
-----------

[](#development)

### Build Process

[](#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

[](#coding-standards)

This plugin follows the [eighteen73 WordPress Coding Standards](https://github.com/eighteen73/wordpress-coding-standards).

Run PHP CodeSniffer:

```
composer test
```

Requirements
------------

[](#requirements)

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

License
-------

[](#license)

GPL-2.0-or-later

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance67

Regular maintenance activity

Popularity13

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~28 days

Recently: every ~34 days

Total

12

Last Release

18d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/73229?v=4)[Brett Mason ](/maintainers/brettsmason)[@brettsmason](https://github.com/brettsmason)

---

Top Contributors

[![brettsmason](https://avatars.githubusercontent.com/u/73229?v=4)](https://github.com/brettsmason "brettsmason (27 commits)")

### Embed Badge

![Health badge](/badges/eighteen73-block-theme-developer/health.svg)

```
[![Health](https://phpackages.com/badges/eighteen73-block-theme-developer/health.svg)](https://phpackages.com/packages/eighteen73-block-theme-developer)
```

###  Alternatives

[milo/hydrator

Hydrates object from array, exports object to array

2572.3k](/packages/milo-hydrator)[jeremeamia/iter8

4913.2k](/packages/jeremeamia-iter8)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)