Create Block Theme

Scaffold a new WordPress block theme with full-site editing support

A powerful CLI tool for creating modern WordPress block themes based on best practices and the latest WordPress development standards.

Quick Start

Create a new theme with one command:

npx @cloudcatch/create-block-theme my-awesome-theme

The interactive CLI will prompt you for:

• Theme name and slug
• Description
• Author information
• Repository details
• Composer vendor prefix

The CLI will then:

• ✨ Copy the latest theme template
• 🎨 Replace all placeholders with your details
• 📦 Install npm and Composer dependencies
• 🚀 Get you ready to develop immediately

Usage

# Interactive mode with prompts
npx @cloudcatch/create-block-theme my-theme-name

# Skip dependency installation
npx @cloudcatch/create-block-theme my-theme-name --skip-install

Features

The generated theme includes:

• Modern Build Setup: Uses @wordpress/scripts with extended Webpack configuration
• Automatic Block Registration: Place blocks in src/blocks/block-library and they're automatically registered
• Conditional Style Loading: Block styles only load when the block is present on the page
• TypeScript Support: Full TypeScript configuration for type-safe development
• Linting & Code Quality: ESLint, StyleLint, and PHPCS pre-configured
• Local Development: Integrated @wordpress/env for quick local WordPress setup
• Testing: Playwright end-to-end testing setup
• Build Automation: Scripts for building production-ready theme zips
• Semantic Release: Automated versioning and changelog generation

What Gets Generated

my-theme/
├── assets/              # Static assets
├── bin/                 # Build scripts
│   ├── build-zip.js    # Generate distributable .zip
│   └── create-block.js # Scaffold new blocks
├── inc/                 # PHP includes
├── languages/           # Translation files
├── parts/               # Template parts
├── patterns/            # Block patterns
├── src/                 # Source files
│   ├── blocks/         # Block development
│   ├── js/             # JavaScript entry points
│   └── scss/           # Styles
├── templates/           # Block templates
├── tests/              # E2E tests
├── composer.json       # PHP dependencies
├── functions.php       # Theme functions
├── package.json        # Node dependencies
├── style.css           # Theme header
├── theme.json          # Theme configuration
└── webpack.config.js   # Build configuration

Development Workflow

After creating your theme:

cd my-theme

# Start development server
npm start

# Or start local WordPress environment
npm run wp-env:start

# Build for production
npm run build

# Create theme package (zip)
npm run theme-zip

# Run linters
npm run lint:js
npm run lint:css
npm run lint:php

# Run tests
npm test

Creating New Blocks

Use the included block generator:

npm run create-block

This will prompt you for block details and scaffold a new block in src/blocks/block-library/.

Requirements

• Node.js 18.0.0 or higher
• npm, yarn, or pnpm
• Composer (optional, for PHP dependencies)
• Docker (optional, for local WordPress environment)

Testing

This CLI includes comprehensive tests to ensure generated themes work correctly:

Run Integration Tests

Tests the CLI generation and all npm scripts:

npm test

Run WordPress Environment Tests

Tests the generated theme in a real WordPress environment using Docker:

npm run test:wp-env

This will:

1. Generate a test theme
2. Install dependencies
3. Start WordPress with Docker
4. Activate the theme
5. Run Playwright E2E tests
6. Clean up

Note: Requires Docker to be installed and running.

Continuous Integration

All tests run automatically on GitHub Actions for every push and pull request, testing against Node.js 18.x, 20.x, and 22.x.

Template Repository

This CLI is based on the Simple Block Theme starter theme.

License

GPL-2.0-or-later

Support

• Report Issues
• Documentation

Made with ❤️ by CloudCatch