README

A Project-Centric PHP tool for scaffolding and building WordPress Block projects with automated environments and remote configuration support.

Features

• Project-Centric Workflow: Manage multiple blocks under a single project container.
• Fast Scaffolding: Create new blocks in < 1 second using local templates.
• Block Templates: Support for specialized block types (e.g., accordion).
• Magic Previews: Instant testing in WordPress Playground with auto-insertion into a live preview page.
• Shared Dependencies: Save disk space by sharing one node_modules across all projects.
• Remote Configuration: (Optional) Sync project metadata and Blueprints from a central API.

Installation

Install Blockyard globally:

composer global require locomotive-agency/blockyard

Note: Ensure your Composer bin directory is in your $PATH.

One-Time Setup

Install global shared dependencies (WordPress build tools):

blockyard setup

Getting Started

1. Initialize a Project

Create a project container. This holds your shared configuration and WordPress environment settings.

# Standard local initialization
blockyard init --name="My Project" --namespace="my-blocks" --author="Your Name"

2. Create a Block

Run this inside your project folder to scaffold a new block:

cd my-project
blockyard create-block --name="Feature Card"

Available Block Templates:

• default - Basic content block
• accordion - Collapsible content panels
• slider - Image carousel with navigation
• tabs - Tabbed interface for content organization
• hero - Full-width hero section with background image and CTAs
• card - Versatile card component (image + content + CTA)
• cta - Prominent call-to-action section

Example with template:

blockyard create-block --name="Image Gallery" --type=slider

3. Build, Preview & Deploy

Navigate to your block folder to develop and test:

cd feature-card

# Build production assets
blockyard build

# Start the magic preview
blockyard preview

# Package as a WordPress Plugin
blockyard deploy

# Package as Static HTML
blockyard deploy --target=html

4. Deploy Your Block

Package the block for WordPress or static sites:

WordPress Plugin (Default):

cd feature-card
blockyard deploy
# Creates: dist/feature-card.zip (ready to upload to WordPress)

Static HTML:

blockyard deploy --target=html
# Creates: dist/static/
#   - block.html (clean snippet)
#   - index.html (standalone preview)
#   - build/ (CSS/JS assets)

The static HTML deployment automatically:

• Boots WordPress Playground
• Renders your block server-side
• Extracts the real HTML
• Generates production-ready files

5. Yard Login and Run Deployment (MVP)

Authenticate once, then deploy app metadata to Yard:

# OAuth login (stores ~/.blockyard/tokens.json)
blockyard login

# Verify current identity from Yard (/v1/me)
blockyard whoami

# Queue a deployment in Yard (/v1/apps/deploy)
blockyard deploy --target=run --app=test --mode=public

--target=run supports:

• --app=<slug>: target app slug (defaults from block.json name)
• --mode=public|private: deployment mode
• --regions=us,eu or explicit regions (us-central1,europe-west1)
• --commit=<sha>: override commit SHA (defaults to git rev-parse HEAD)
• --json: machine-readable output

CLI Reference

Advanced: Remote Configuration

Blockyard can be integrated with a central API to manage project configurations across a team. This is useful for agencies wanting to standardize namespaces and WordPress Blueprints.

Environment Setup

Create a .env file in the current directory or ~/.blockyard/.env:

YARD_API_URL="https://yard-xxxxx-uc.a.run.app"
BLOCKYARD_OAUTH_CLIENT_ID="...apps.googleusercontent.com"
BLOCKYARD_OAUTH_CLIENT_SECRET="..." # optional
BLOCKYARD_ALLOWED_DOMAIN="company.com"

Using Remote Mode

When initializing, use the --remote flag to pull configuration from your API:

blockyard init --remote --client=123

--remote is Yard-only:

• Requires YARD_API_URL
• Requires a valid login token from blockyard login
• Uses:
  • GET {YARD_API_URL}/v1/clients/{id}
  • GET {YARD_API_URL}/v1/clients/{id}/blueprint

Author

Locomotive Agency
Website: locomotive.agency

Release Automation

• elease-flow.ps1 supports rerunnable prepare/publish release flow for protected main. See scripts/scripts.md for the full release procedure.

  License

GPL-2.0-or-later