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, .opencode/command/, and .agents/skills/

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/                    User-facing documentation site content
|- tests/php/               PHPUnit application tests
|- .agents/skills/          Reusable AI skills for this project
|- .opencode/command/       Custom OpenCode slash commands
|- .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 then asks for the plugin name, namespace, and slug and rewrites the boilerplate identity.

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`

AI And Maintenance Notes

AGENTS.md contains the high-level repository rules and doc map
.agents/skills/ contains reusable task-specific guidance
.opencode/command/ contains custom commands such as /readme-update
when repo structure or workflows change, update both README.md and the relevant files in docs/

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