Migrating from v1.x to v2.0

WP Bones v2.0 unifies the build pipeline around @wordpress/scripts and webpack, drops the old gulp + run-s + per-app-script approach, and standardises the developer commands across every plugin and boilerplate. This guide walks you through the upgrade.

TL;DR

For most plugins, the upgrade is a single command:

php bones migrate:to-v2
yarn install
yarn build

That’s it. Everything under resources/assets/ is preserved, only the build infrastructure is swapped out. Read on for the full picture.

What changed

Removed

• gulpfile.js — the whole gulp pipeline is gone.
• gulp, gulp-babel, gulp-clean-css, gulp-less, gulp-sass, gulp-typescript, gulp-uglify, gulp-watch, sass devDependencies.
• npm-run-all — no more run-s orchestration.
• Per-app scripts in package.json (build:apps, start:apps, build:widget, …). Webpack auto-discovers every entry now.

Added

• webpack.config.js — a single file that scans resources/assets/ and builds everything.
• tsconfig.json — TypeScript ready out of the box (JS still works).
• .prettierrc, jest.config.js.
• @wordpress/scripts ^31, typescript, glob, less-loader, webpack-remove-empty-scripts, @types/react*, @wordpress/jest-preset-default devDependencies.

Unified scripts

{
  "scripts": {
    "dev":            "wp-scripts start",
    "build":          "wp-scripts build",
    "test":           "wp-scripts test-unit-js",
    "test:watch":     "wp-scripts test-unit-js --watch",
    "format":         "wp-scripts format",
    "format:check":   "wp-scripts format --check",
    "lint":           "wp-scripts lint-js resources/",
    "lint:style":     "wp-scripts lint-style 'resources/**/*.{css,scss}'"
  }
}

Same shape in every v2 plugin and boilerplate. Once you know one, you know them all.

New bones commands

• php bones make:app <name> — scaffold a new React/TS app
• php bones migrate:to-v2 — the automated migrator

Package manager

v2 uses yarn. package-lock.json is deleted during migration; a fresh yarn.lock is generated by yarn install.

Running the migrator

git status
git commit -am "snapshot before v2 migration"

"require": {
  "php": ">=8.1",
  "wpbones/wpbones": "^2.0.0"
}

php bones migrate:to-v2

composer update
yarn install
yarn build

yarn test   # if you had tests

Migrating apps that used per-script entries

If your v1.x package.json had something like:

"build:apps":   "wp-scripts build resources/assets/apps/app --output-path=public/apps/",
"build:widget": "wp-scripts build resources/assets/apps/dashboard-widget --output-path=public/apps/dashboard-widget"

…you can delete them all. Just organise resources/assets/apps/ so each app is either:

• A subfolder with index.{ts,tsx,js,jsx} — good for apps with components, e.g. apps/dashboard/index.tsx.
• A single top-level file — good for tiny apps, e.g. apps/widget.tsx.

Webpack picks them up automatically. Output stays the same as before (public/apps/<name>.js + <name>.asset.php).

File extensions

v1.x boilerplates shipped app.jsx. v2 defaults to app.tsx because TypeScript is set up by default — but plain .js/.jsx still works. Rename at your leisure.

Custom gulp tasks

If your gulpfile.js had project-specific tasks (not the WP Bones defaults), they won’t be migrated automatically. Rewrite them as webpack plugins, a script in package.json, or a tiny shell command triggered by yarn dev.

Troubleshooting

”WPKirkMantine has already been declared”

A v1.x bug where withInlineScript double-enqueued inline code. Fixed in v2 framework. If you see it, make sure your vendor/wpbones/wpbones is at 2.0.0+.

The React app doesn’t mount

Check that the app name isn’t one of the reserved WordPress script handles. dashboard, post, jquery, etc. are owned by core and will silently replace your bundle.

”Class not found” when running composer update on a renamed plugin

This was a v1.x bootstrap issue that’s fixed in v2. If you still hit it on v1.x first, upgrade to at least WP Bones v1.11.1.

Rollback

If something doesn’t work, roll back via git:

git reset --hard HEAD
rm -rf node_modules vendor
composer install
npm install   # v1.x path

Then open an issue with the error output and we’ll help.