ralfhortt/wordpress-theme-boilerplate

There is no license information available for the latest version (dev-master) of this package.

A WordPress Boilerplate Theme by Ralf Hortt

dev-master 2025-11-29 22:56 UTC

Requires

• laravel/pint: ^1.22
• laravel/prompts: *
• ralfhortt/wp-assets: *
• ralfhortt/wp-image-sizes: *

Requires (Dev)

• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.1
• rector/rector: ^2.0
• szepeviktor/phpstan-wordpress: ^2.0

Unknown License

README

🛠️ Technologies

Frontend

Build Tools

Code Quality

📚 Documentation

Comprehensive guides to help you get started and understand the project structure:

📦 Installation Guide Step-by-step installation instructions including requirements (Composer, Node.js) and setup process.	🎨 Theme.json Workflow Learn how to work with TypeScript-based theme.json configuration, including type safety benefits and daily development workflow.	📋 Dependencies Detailed breakdown of all npm and Composer dependencies, explaining what each package does and why it's included.
📝 Changelog Track version history and changes to the project.	📁 Folder READMEs Every major folder contains its own README.md with specific instructions for that section.

🚀 Installation

composer create-project ralfhortt/wordpress-theme-boilerplate

📖 Check INSTALLATION.md for detailed installation steps

💻 Development

⚡ Quick Start

🏗️ Production Build npm run build Builds all assets and generates theme.json

👀 Development Mode npm start Starts file watchers with auto-rebuild

🔧 Commands

🎨 Development Helpers

Command	Description
npm run make:block-config	Create TypeScript block configuration
npm run make:block-style	Create TypeScript block style variation
npm run make:block	Create a block pattern
npm run make:pattern	Create a block pattern
npm run css:clamp	Calculate CSS clamp values
npm run css:color	Convert color notations (rgb, hex, oklch)
npm run css:contrast	Calculate color contrast ratios
npm run generate:theme-types	Generate TypeScript types from WordPress schema

🏗️ Build Commands

Command	Description
npm run build:theme	Build theme.json from TypeScript files
npm run watch:theme	Watch and auto-rebuild theme files
npm run build	Production build (includes theme.json)
npm start	Development mode with file watchers

🔍 Linters

Command	Description
npm run lint:css	Run Stylelint for CSS/SCSS
npm run lint:php	Run PHPStan analysis
composer run lint	Run PHPStan static analysis

Available Tools:

• PHPStan - Static analysis
• Stylelint - CSS/SCSS linting

🔧 Fixers & Formatters

Command	Description
npm run lint:css:fix	Auto-fix Stylelint issues
npm run lint:php:fix	Format PHP with Laravel Pint
composer run format	Format PHP code with Laravel Pint
composer run format:prettier	Format all files with Prettier
composer run refactor	Refactor PHP code with Rector
composer run refactor:dry	Preview Rector changes

Available Tools:

• Laravel Pint - PHP formatter
• Rector - PHP refactoring
• Stylelint - Auto-fix CSS
• Prettier - Code formatter

Using Rector

If you don't have dev dependencies installed, run:

composer install --no-interaction --prefer-dist

Preview Rector changes (recommended):

composer run refactor:dry

Apply Rector refactors:

composer run refactor

You can also run Rector directly with the vendor binary:

vendor/bin/rector process src --dry-run

⚙️ Project Setup

Command	Description
composer run replace-textdomain	Replace textdomain with project name
composer run copy-env	Copy environment configuration files

🏗️ Build Process

The theme uses TypeScript for theme.json configuration with full type safety:

📁 Project Structure

src/theme/
├── theme.ts                    # Main theme configuration
├── theme.d.ts                  # Auto-generated TypeScript types
└── blocks/core/*/              # Block-specific settings and styles
    ├── blockname.ts            # Block configuration
    └── blockname.stylename.ts  # Block style variations → styles/blockname.stylename.json

✨ Features

• 🎯 Type Safety: TypeScript types auto-generated from official WordPress theme.json schema
• ⚡ No Compilation: Node.js loads TypeScript directly with --experimental-strip-types flag
• 🎨 Block Styles: Style variations (files matching blockname.*.ts) automatically generate separate JSON files in styles/ directory
• 🔄 Live Reload: Watch mode automatically rebuilds when TypeScript files change

🚀 Workflows

Production npm run build Complete production build with theme.json generation

Development npm start File watchers with automatic theme.json rebuild