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

Command	Option	Description
`init`	`--remote`	Use API to fetch project data.
`create-block`	`--type`	`default`, `accordion`, `slider`, `tabs`, `hero`, `card`, `cta`.
`deploy`	`--target`	`plugin` (default), `html`, `run`.
`deploy`	`--out`	Output directory (default: `dist`).
`deploy`	`--target=run`	Queue app deploy in Yard (`--app`, `--mode`, `--regions`, `--commit`).
`login`	`--json`	OAuth login and local token cache (`~/.blockyard/tokens.json`).
`whoami`	`--json`	Show current Yard identity using stored token.

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

locomotive-agency / blockyard

Maintainers

Package info

Statistics

Security