WordPress Theme Boilerplate

---

🛠️ Technologies

Frontend

Build Tools

Code Quality

---

---

📚 Documentation

• INSTALLATION.md: setup and requirements
• DEPENDENCIES.md: dependency overview
• CHANGELOG.md: release history
• .github/agents/THEME-HOW-IT-WORKS.md: high-level theme architecture
• .github/agents/THEME-JSON-WORKFLOW.md: TypeScript theme.json workflow
• .github/agents/THEME_AUTOCOMPLETION.md: preset and custom property autocomplete system

---

🚀 Installation

composer create-project ralfhortt/wordpress-theme-boilerplate

For detailed setup, see INSTALLATION.md.

---

💻 Development

Quick Start

npm start

Starts development watchers for assets, blocks, block styles, and theme configuration.

npm run build

Runs a production build for assets, blocks, and generated theme files.

Main Commands

Build and Watch

Command	Description
npm run build	Full production build
npm start	Start all development watchers
npm run build:theme	Build root theme.json from TypeScript config
npm run watch:theme	Watch TypeScript config and rebuild theme.json
npm run generate:theme-types	Refresh schema-derived theme TypeScript types

Scaffolding and Helpers

Command	Description
npm run make:block	Scaffold a new block
npm run make:block-config	Scaffold a TypeScript block config file
npm run make:block-style	Scaffold a block style variation config
npm run make:pattern	Scaffold a pattern file
npm run css:clamp	CSS clamp helper
npm run css:color	Color conversion helper
npm run css:contrast	Contrast helper

Linting and Formatting

Command	Description
npm run lint	Run Stylelint and PHP lint checks
npm run lint:css	Run Stylelint for SCSS
npm run lint:css:fix	Auto-fix Stylelint issues
npm run lint:php	Run PHP lint via Composer scripts
composer run lint:php	Run PHPStan analysis
composer run format	Format PHP with Pint
composer run refactor	Apply Rector refactors
composer run refactor:dry	Preview Rector refactors

Commit Workflow

This repository enforces commit quality checks through Husky hooks:

• Pre-commit: runs Rector and Pint on staged PHP files, then lint checks.
• Commit-msg: enforces Conventional Commits format.

Example commit messages:

• feat: add starter pattern scaffold
• fix: handle empty post type input
• chore: update lint tooling

---

🏗️ Theme Architecture

The project uses a TypeScript-first workflow for theme configuration.

Source of Truth

• src/blocks/theme.ts: base theme configuration
• src/blocks/core/: per-core-block config modules
• theme.json: generated output consumed by WordPress

Build Flow

1. Edit files in src/blocks/.
2. Run npm run build:theme or npm run build.
3. Commit source changes and generated outputs as needed by your workflow.

For full details, see .github/agents/THEME-JSON-WORKFLOW.md.