Gulp is gone. Yarn scripts are unified. TypeScript is default. 14 boilerplates refreshed. One
php bones migrate:to-v2away.
After years of shipping with Gulp, run-s, and a patchwork of per-plugin build scripts, WPBones v2 collapses all of it into a single webpack-based pipeline. Every plugin built with WPBones now uses the same yarn dev/build/test/format/lint commands, the same webpack config, the same TypeScript + Jest + Prettier defaults. And to make the jump painless, v2 ships with php bones migrate:to-v2 β a one-command automated migrator that rewrites your plugin in place.
This is the biggest breaking change in the framework's history, and we made the migration path as short as we could. If you've been putting off modernizing your WPBones plugin, this weekend is a good weekend.
What's New in v2
β¨ One webpack config, zero boilerplate
The old v1.x pipeline was a stack of gulp tasks orchestrated by run-s: one script to compile SCSS, another to bundle JS, a third to transpile TypeScript, a fourth to build React apps, a fifth to copy things. Every boilerplate had its own variation, and every plugin drifted.
v2 replaces all of it with a single webpack.config.js that auto-discovers entries from resources/assets/:
- Drop a file in
resources/assets/apps/<name>.tsxβ builds topublic/apps/<name>.js - Drop a folder at
resources/assets/apps/<name>/index.tsxβ same thing - Drop CSS/SCSS/LESS in
resources/assets/css/β compiles topublic/css/<name>.css - Drop TS/JS in
resources/assets/js/β compiles topublic/js/<name>.js
No more editing gulpfile.js to register a new entry. No more run-s coordination. Just save the file and webpack picks it up.
β¨ Unified yarn scripts across every plugin
Every plugin built on WPBones v2 β from the leanest Base boilerplate to the full Mantine UI demo β now responds to the same five commands:
yarn dev # watch mode (webpack + @wordpress/scripts)
yarn build # production build
yarn test # Jest with @wordpress/jest-preset-default
yarn format # Prettier
yarn lint # ESLint (WP preset)
Move from one plugin to another without re-learning the toolchain.
β¨ TypeScript, Jest, Prettier β configured out of the box
Every v2 plugin ships with tsconfig.json (strict mode), jest.config.js, and .prettierrc β all wired to the @wordpress/* presets. You can use .ts / .tsx anywhere, write Jest tests next to your source, and run yarn format to keep everything consistent.
No opt-in, no separate setup step. Just write code.
β¨ php bones migrate:to-v2 β the automated migrator
The breaking change story is tricky, so v2 ships with a one-shot migration command:
php bones migrate:to-v2
It removes gulpfile.js and package-lock.json, creates webpack.config.js / tsconfig.json / .prettierrc / jest.config.js from framework stubs, rewrites package.json scripts to the v2 set, drops gulp-era devDependencies and installs the v2 set (@wordpress/scripts ^31, typescript, glob, webpack-remove-empty-scripts). Run yarn install && yarn build afterward and you're on v2.
We've used this migrator ourselves on 14 boilerplates. It works.
β¨ php bones make:app with reserved-handle safety
Generating a new React/TypeScript app inside a plugin is now a one-liner:
php bones make:app my-dashboard
The command also refuses to create apps with reserved WordPress core handles (dashboard, post, common, jquery, wp-elementβ¦). We got bitten by this ourselves when a dashboard handle silently got dropped by WP core β now the CLI catches it before it becomes a mystery bug.
β¨ 14 boilerplates, all re-released at v2.0.0
Every boilerplate in the WPBones family got the migration + a shiny new CLAUDE.md with an overview, smoke test steps, template-usage instructions, and a list of the framework surface it exercises:
- Base β the minimum starter (JS/TS, SCSS/LESS/CSS, a small React sample, a Jest test)
- TypeScript β strict TS showcase (interfaces, generics, unions, type guards, utility types)
-
ReactJS β React with only
@wordpress/*libraries, no third-party UI kit - Mantine UI β full admin app: theming, dark mode, tabs, forms, modals, notifications, DataTable
- API β REST API routing with closures + controllers + permission callbacks
- Routes β admin menu routing + custom page routes + named URL helpers
-
Blade β BladeOne templating (
@foreach,{{ }}, partials) - CPT β custom post types + custom taxonomies as service providers
- Cron β scheduled events via service provider
- Database β migrations, seeders, query builder, Eloquent ORM
-
Hooks β
plugin/hooks/*.phpauto-inclusion convention - Internationalization β POT/PO/MO/JSON pipeline with a working Italian translation
-
Options β declarative
config/options.php+ live$plugin->optionsaccessor -
Packages β demos of every official
wpbones/*composer package
Each is a GitHub template repo β click Use this template, run php bones rename, and you have a working plugin.
π v2.0.1 β inline-scripts routing fix
v2.0.1 lands today alongside v2.0.0 with a patch for a regression we caught during Mantine boilerplate testing. The short version: withInlineScript() and withLocalizeScript() now correctly route to adminAppsAssets when the handle was registered via withAdminAppsScript() β before v2.0.1, the inline script was silently dropped by WordPress because the handle wasn't yet enqueued at the moment wp_add_inline_script() ran.
Any plugin combining ->withAdminAppsScript('my-app')->withInlineScript('my-app', 'window.MyApp = {β¦}') would have had window.MyApp come through as undefined. If you hit that, v2.0.1 is the fix. If you didn't, you're still getting it for free.
π Docs, rebuilt
wpbones.com got a full refresh for v2:
- New Boilerplates section with a dedicated page per boilerplate
- Migrating to v2 guide walking through the automated migrator step by step
- WordPress environments comparison (wp-env, Valet, Local, DDEV, Lando, Playground, Docker, Vagrant) β pick the stack that fits your OS and workflow
- Stale Gulp references removed from
core-plugin-files,getting-started, andofficial-packages
Getting Started
New to WPBones?
Pick a boilerplate that matches what you want to build, then:
gh repo create my-plugin --template wpbones/WPKirk-Boilerplate --public --clone
cd my-plugin
composer install
php bones rename "My Plugin"
yarn install && yarn build
Already on v1.x?
From your plugin root:
# Pull in WPBones v2
composer require wpbones/wpbones:^2.0.1
# Run the automated migrator
php bones migrate:to-v2
# Install the new dev deps and build
yarn install && yarn build
Review the Migrating to v2 guide for the full breakdown of what changes.
Links
- π Website & Docs: wpbones.com
- π¦ Framework on Packagist: wpbones/wpbones
- π GitHub: wpbones/WPBones
- π¬ Discord: Join the community
- π v2.0.1 Release Notes: github.com/wpbones/WPBones/releases/tag/v2.0.1
- π Migrating to v2: wpbones.com/docs/migrating-to-v2
- π§ Boilerplates Overview: wpbones.com/docs/boilerplates/overview
About WPBones
WPBones is a Laravel-style framework for WordPress plugin development. It gives you an IoC container, service providers, Blade templating, Eloquent ORM, a CLI code generator, and all the patterns you already know from Laravel β adapted to the WordPress lifecycle. If you like Composer, yarn, webpack, and TypeScript as much as you like WordPress, this is the framework for you.













