README

This repository is a modern, object-oriented WordPress plugin boilerplate. It is intended as a source repo, starter template, and reference implementation for developers and AI coding agents building production-ready plugins.

If you want the user-facing documentation site entry point, start with docs/index.mdx.

What This Repository Includes

Composer-based PHP structure with namespacing
Centralized WordPress hook registration through the loader
@wordpress/scripts for bundling, linting, and formatting
@wordpress/env for reproducible local WordPress development
PHPUnit application testing in the dedicated tests-cli container
GitHub Actions for analysis, testing, and release automation
AI-oriented project instructions in AGENTS.md, .agents/skills/wp-plugin-bp/, and official WordPress skills in .agents/skills/wp-*/

Typical Use

Use this repo when you want to:

create a new plugin with sane defaults
inspect the preferred project structure before extending a plugin
sync an existing plugin with upstream boilerplate changes
give an AI agent enough repo context to make safe edits

Repository Map

.
|- demo-plugin.php          Main bootstrap file only
|- src/                     Plugin logic grouped by feature/domain
|- resources/               Admin and frontend assets
|- docs/                    Source documentation site content; emptied after plugin setup
|- tests/php/               PHPUnit application tests
|- .agents/skills/wp-plugin-bp/   Unified plugin AI skill with task references
|- .agents/skills/wp-*/     Official WordPress agent skills for focused workflows
|- .github/workflows/       CI/CD workflows
`- README.txt               WordPress.org plugin readme template

Local Development

Create a Plugin From the Boilerplate

composer create-project juvo/wordpress-plugin-boilerplate

The setup script asks for the plugin name, namespace, and slug, runs the packaged wp-plugin-bp replacement script, and removes .agents/ from the initialized plugin. After replacement, setup asks whether to install agent skills for ongoing AI-assisted work.

Common Commands

Command	Purpose
`npm run env:start`	Start the local WordPress environment
`npm run env:stop`	Stop the environment
`npm run build`	Build production assets
`npm run start`	Watch and rebuild assets during development
`npm run test:php`	Run PHPUnit application tests in `wp-env`
`npm run lint:js`	Lint JavaScript
`npm run lint:style`	Lint styles
`composer run phpstan`	Run PHP static analysis
`composer run phpcs`	Run WordPress coding standards checks
`composer run i18n:extract`	Extract translatable strings
`composer run i18n:compile`	Compile translation files

Architecture Notes

Keep business logic in src/; do not place it in demo-plugin.php
Register hooks, filters, shortcodes, CLI commands, and abilities through the loader
Put assets in resources/admin/ and resources/frontend/
Add PHPUnit application tests in tests/php/
Treat docs/ as user-facing documentation and keep it in sync with repo behavior

Where To Look Next

Goal	Start here
Understand the docs site structure	`docs/index.mdx`
Learn local environment workflows	`docs/wp-env.mdx`
Write application tests	`docs/testing.mdx`
Work on bundling or block assets	`docs/bundeling.mdx`, `docs/create-blocks.mdx`
Configure translations	`docs/i18n.mdx`
Review AI-specific repo rules	`AGENTS.md`, `docs/work-with-ai.mdx`, `.agents/skills/wp-plugin-bp/SKILL.md`

AI And Maintenance Notes

AGENTS.md contains the high-level repository rules and doc map
.agents/skills/wp-plugin-bp/ contains the unified skill, task references, doc snapshots, and scripts
.agents/skills/wp-*/ contains official WordPress skills for block development, Interactivity API, PHPStan, project triage, and REST API work
natural requests such as "sync with upstream project conventions" should route through the wp-plugin-bp skill and infer the upgrade workflow
when repo structure or workflows change, update README.md, the relevant files in docs/, and .agents/skills/wp-plugin-bp/

Upstream Reference

This plugin was created using the wordpress-plugin-boilerplate. Keep that upstream reference so future updates and comparisons stay straightforward.

juvo / wordpress-plugin-boilerplate

Maintainers

Package info

Statistics

Security