Get started with Bit Apps WP Plugin Boilerplate

Introduction

The boilerplate is a WordPress plugin skeleton with a PHP application layer — router, controllers, ORM, validation — and a React frontend, wired together and ready to build on. Start from the starter template, which scaffolds the whole structure and renames it to your plugin in one command.

Requirements

The minimum is what a site must have for the plugin to run. The recommended column is WordPress's own recommended environment — build and test against it.

	Minimum	Recommended
PHP	8.0	8.3 or greater
WordPress	5.0	Latest release
Database	MySQL 5.5.5 / MariaDB	MariaDB 10.11+ or MySQL 8.0+
HTTPS	—	Required for every install
Web server	—	Apache or Nginx

PHP 7.4 and MySQL 5.5.5 still run WordPress, but both are end-of-life and out of security support.

Local development also needs Composer 2.x, Node 20+ and pnpm 9+. Docker is optional, for the bundled WordPress environment.

Scaffolding a plugin

git clone https://github.com/csemazharul/wp-plugin-starter.git

Clone it into wp-content/plugins/, then pick a path.

With Docker — brings up WordPress with the plugin already activated:

pnpm install
pnpm env:start    # WordPress + automatic plugin activation
pnpm dev:free     # Vite dev server with hot module replacement

Against an existing WordPress install:

composer install
pnpm install
pnpm dev:free

Initialize the plugin

The scaffold ships with placeholder names. Replace them before activating:

php wp-kit plugin:init

It prompts for the plugin name, slug, namespace and API prefix, then rewrites every placeholder — including the PSR-4 namespace the autoloader expects, which is why it must run before activation.

php wp-kit plugin:info   # show the current name, slug and namespace

Generators

The same CLI scaffolds the file types described throughout these docs:

php wp-kit make:controller   # backend/app/HTTP/Controllers
php wp-kit make:model        # backend/app/Models
php wp-kit make:migration    # backend/db/Migrations, and registers it
php wp-kit --help            # every available command

make:migration also registers the class with the installer provider, so a generated migration runs without further wiring. See Migrations.

Dependencies

Four Composer packages do the heavy lifting:

"require": {
  "php": ">=8.0",
  "bitapps/wp-kit": "*",
  "bitapps/wp-database": "*",
  "bitapps/wp-validator": "*",
  "bitapps/wp-telemetry": "*",
  "typisttech/imposter-plugin": "^0.6.2"
}

Package	Provides
bitapps/wp-kit	Routing, requests, responses, middleware, hooks, migrations, HTTP client, helpers
bitapps/wp-database	ORM, query builder and schema builder
bitapps/wp-validator	Validation rules and sanitizers
bitapps/wp-telemetry	Opt-in usage reporting and deactivation feedback
typisttech/imposter-plugin	Namespace-prefixes dependencies at install time — see Packages

The Bit Apps packages track latest, so composer install resolves the current release of each. composer.lock is what pins the versions a given checkout actually uses; run composer update deliberately rather than as part of routine setup.

Frontend stack

React 18 and TypeScript, built by Vite, with Ant Design and Tailwind for UI, Jotai for state and TanStack Query for server state.

Command	Does
pnpm dev:free	Vite dev server with HMR
pnpm build	Production build
pnpm test	Vitest
pnpm test:e2e	Playwright
pnpm lint	ESLint over frontend/
pnpm lint:php	PHP CS Fixer and PHPCS
pnpm env:start / env:stop	The bundled WordPress environment

Next steps

• Directory structure — where each kind of file belongs
• Request lifecycle — how a request reaches your code
• Routing — define your first endpoint

Loading...