SidX WordPress Theme Boilerplate

A high-quality, open source WordPress theme boilerplate by SidX. Distributed as a Composer package with a scaffolded-layers architecture — use what you need, remove what you don't.

Quick Start

Point Composer at the private repo (one-time shell session setup):

$env:COMPOSER_REPOSITORIES='[{"type": "vcs", "url": "https://git.b0t.pm/sid/boilerplate-wp.git"}]'

Then create your theme:

composer create-project sidx/boilerplate my-client-theme
cd my-client-theme
npm install
npm run dev

Credentials: Composer will prompt for your Forgejo username/password. To skip the prompt, add an access token to ~/.config/composer/auth.json:

{ "http-basic": { "git.b0t.pm": { "username": "your-username", "password": "your-forgejo-token" } } }

Principles

• High code quality — PHPStan level 8, PHPCS/WPCS, ESLint, Stylelint enforced
• Re-usable components — Navigation, Breadcrumbs, Pagination, and Icon system — all filter-driven and Tailwind-styled
• Secure by design — Security hardeners run first in the boot sequence, defaults locked down
• Progressive enhancement — HTML-first, CSS-enhanced, JS-optional. <details>/<summary> accordion, link-based nav
• No remote dependencies — All fonts, icons, and assets bundled locally. No CDN, no Google Fonts
• Updatable — Composer-managed dependency; composer update sidx/boilerplate pulls improvements

Architecture

The boilerplate organizes into five independent layers, each implementing SidX\Boilerplate\Bootable:

Layer	Contents	Required?
Core	Security, Setup, Cleanup, Assets (Vite + cachebusting)	Always
Design	Design tokens JSON → CSS custom properties, editor styles	Always
Components	Navigation, Breadcrumbs, Pagination, Icon system	Optional
Blocks	Placeholder for custom Gutenberg blocks (upcoming)	Planned
Integrations	SCF, WooCommerce, Matomo, FluentForms, MainWP bridges	Optional

Plugin Stack (Optional Integrations)

The theme auto-detects these plugins and only loads integration code when the plugin is active:

• Secure Custom Fields — Automattic's ACF Pro fork
• WooCommerce — Product gallery support, template overrides
• FluentSMTP + FluentForms — Theme-styled forms
• Matomo — Self-hosted analytics tracking
• MainWP — Child site customizations

Components

Pre-built, Tailwind-styled, filter-driven components:

Core: Navigation, Breadcrumbs, Pagination, Icon
SEO: Meta tags, JSON-LD structured data, XML sitemap
Compliance: Cookie consent banner with category preferences

See docs/components.md for the full API reference.

Build Tooling

• Vite — Dev server with HMR for CSS/JS
• Tailwind CSS 3 — Utility-first, scoped to .theme-wrapper (no Gutenberg conflicts)
• PostCSS — Autoprefixer, RTLCSS (auto-generated RTL), cssnano (minification)
• Design tokens — Single design-tokens.json → CSS custom properties + Tailwind config

Documentation

• docs/getting-started.md — LocalWP setup, dev workflow
• docs/layers.md — Layer architecture, how to disable/remove layers
• docs/integrations.md — Plugin integration guide
• docs/conventions.md — Code style, naming, commit conventions
• docs/components.md — Full component API reference
• docs/security.md — Security hardening and customization
• docs/deployment.md — Production deployment guides
• docs/updating.md — Release process, versioning
• docs/CONTRIBUTING.md — How to contribute

Requirements

• PHP 8.2+
• WordPress 6.5+
• Composer 2+
• Node.js 22+

License

MIT