locomotive-agency/blockyard

CLI tool for scaffolding and building WordPress blocks

Maintainers

Details

gitlab.com/locomotive-agency/blockyard

Homepage

Source

Issues

Installs: 1

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Forks: 0

pkg:composer/locomotive-agency/blockyard

v0.3.0 2026-02-05 07:03 UTC

Requires

Requires (Dev)

GPL-2.0-or-later d0f99ee99dacf49e51fb292ecbfa4c6db49f1f61

  • Locomotive Agency <web.woop@locomotive.agency>

cliwordpressscaffoldingblocksgutenberg

This package is not auto-updated.

Last update: 2026-02-05 07:05:31 UTC

README

A PHP-based CLI tool for scaffolding and building WordPress Gutenberg blocks with client-specific configuration.

Features

  • Fast scaffolding - Create blocks in < 1 second using local templates
  • One-command setup - Automated environment configuration
  • Smart defaults - Auto-derive slugs, auto-link dependencies
  • Instant previews - Test blocks in WordPress Playground
  • Build wrapper - Simplified npm build commands
  • Quality checks - PHPStan level 8, PHP-CS-Fixer, PHPUnit

Requirements

  • PHP 8.1+ with CLI
  • Node.js 20.18+ and npm
  • Composer for dependency management

Installation

# Install dependencies
composer install

# Make CLI executable (Linux/macOS)
chmod +x bin/blockyard

Quick Start

# One-time setup (5-10 minutes)
./bin/blockyard setup

# Create a block (< 1 second)
./bin/blockyard init --client=1 --name="My Block"

# Build it
cd my-block
../bin/blockyard build

# Preview in WordPress Playground
../bin/blockyard preview

Commands

setup

Set up shared dependencies for fast block creation.

./bin/blockyard setup

What it does:

  • Creates ~/.blockyard/shared-deps/
  • Installs WordPress dependencies (~300MB)
  • Installs WordPress Playground CLI (~40MB)
  • Takes 5-10 minutes (one-time)

Options:

  • --force - Force reinstall even if already set up

Example:

./bin/blockyard setup --force

init

Initialize a new block project.

./bin/blockyard init --client=1 --name="Block Name"

Options:

  • --client=ID (required) - Client ID to fetch configuration for
  • --name=NAME (required) - Human-readable block name
  • --slug=SLUG (optional) - Block slug (auto-derived from name if not provided)
  • --no-shared-deps - Don't use shared dependencies
  • --use-npx - Use slow official npx method instead of fast templates
  • --dry-run - Validate inputs without creating project

What it does:

  • Validates prerequisites (Node.js, npm)
  • Fetches client configuration from API
  • Scaffolds project using fast local templates (< 1 second)
  • Auto-links shared dependencies (no npm install needed)
  • Creates .blockyard.json config file

Examples:

# Minimal (slug auto-derived)
./bin/blockyard init --client=1 --name="Header Block"
# Creates: header-block/

# With custom slug
./bin/blockyard init --client=1 --name="My Block" --slug=custom-slug

# Interactive mode
./bin/blockyard init

# Without shared deps (requires npm install)
./bin/blockyard init --client=1 --name="Block" --no-shared-deps

build

Build the block project for production.

cd my-block
../bin/blockyard build

What it does:

  • Checks for required dependencies
  • Runs npm run build
  • Creates production assets in build/ directory

Requirements:

  • Must be run from within a block project directory
  • Dependencies must be installed (automatic with shared deps)

Example:

cd header-block
../bin/blockyard build

preview

Preview block in WordPress Playground.

cd my-block
../bin/blockyard preview

Options:

  • --port=PORT - Port to run Playground on (default: 9400)
  • --wp=VERSION - WordPress version (default: latest)
  • --php=VERSION - PHP version (default: 8.3)

What it does:

  • Validates project is built
  • Starts WordPress Playground
  • Auto-mounts and activates your block
  • Opens at http://localhost:9400

Requirements:

  • Block must be built first (../bin/blockyard build)
  • Node.js 20.18+ installed

Access:

Examples:

# Default (port 9400, latest WP, PHP 8.3)
../bin/blockyard preview

# Custom port
../bin/blockyard preview --port=8080

# Specific WP/PHP versions
../bin/blockyard preview --wp=6.4 --php=8.2

# Combined
../bin/blockyard preview --port=8080 --wp=6.4 --php=8.2

Stop server: Press Ctrl+C

Complete Workflow

# === ONE-TIME SETUP ===
./bin/blockyard setup

# === CREATE BLOCK ===
./bin/blockyard init --client=1 --name="Header Block"

# === DEVELOP ===
cd header-block
npm start  # Hot reload development

# === BUILD ===
../bin/blockyard build

# === PREVIEW ===
../bin/blockyard preview
# Opens WordPress at http://localhost:9400

Development

Run Tests

composer test

Code Quality

# PHPStan
composer stan

# PHP-CS-Fixer
composer lint
composer lint:fix

# All checks
composer check

How It Works

Shared Dependencies

After running setup, all blocks share WordPress dependencies from ~/.blockyard/shared-deps/:

Benefits:

  • Instant block creation (< 1 second)
  • Save disk space (300MB once vs 300MB per block)
  • No npm install needed for each block

Location: ~/.blockyard/shared-deps/node_modules/

Fast Scaffolding

Uses local templates instead of npx @wordpress/create-block:

Speed comparison:

  • Old way (npx): 5-10 minutes per block
  • New way (templates): < 1 second per block

WordPress Playground

Tests blocks in real WordPress without server setup:

  • Runs WordPress in WebAssembly
  • SQLite-based (no MySQL needed)
  • Disposable (fresh every time)
  • Instant startup (< 5 seconds)

Troubleshooting

"Node.js not found"

Install Node.js 20.18+ from https://nodejs.org

node --version  # Should show v20.18+

"Build directory not found"

Build your block first:

../bin/blockyard build

"Shared dependencies not found"

Run setup:

./bin/blockyard setup

Preview port already in use

Use a different port:

../bin/blockyard preview --port=9401

Project Structure

blockyard/
├── bin/
│   └── blockyard           # CLI entry point
├── src/
│   ├── Command/            # CLI commands
│   ├── Service/            # Business logic
│   └── Model/              # Data models
├── templates/
│   └── wordpress-block/    # Block templates
├── tests/                  # PHPUnit tests
├── composer.json           # PHP dependencies
└── README.md               # This file

Author

Locomotive Agency
Email: web@locomotive.agency

License

GPL-2.0-or-later