Idea: Clean up root package.json and convert tools and tests to workspace packages #75041

Benefits

Converting tools and test directories to workspace packages provides several key advantages:

1. Separation of Concerns: Each tool/test suite declares its own dependencies, making it clear what each component needs to function.

2. Cleaner Root package.json: Reduces the root package.json from 81 devDependencies to only essential shared tools (ESLint, Stylelint, Husky, TypeScript, etc.).

3. Improved Maintainability: Changes to one tool's dependencies don't require updating the root configuration, reducing merge conflicts and simplifying updates.

4. Better Dependency Visibility: Makes it easier to audit and understand what dependencies are used by each tool, improving security review processes.

5. Prepares for Stricter Dependency Isolation: With npm, dependencies get hoisted to the root node_modules, so workspaces can accidentally access dependencies from anywhere in the monorepo ("phantom dependencies"). By moving dependencies to workspaces that need them and cleaning up root, we make dependency relationships explicit. This is good practice now and becomes even more impactful when we later migrate to pnpm, where workspaces can only access their own declared dependencies plus the monorepo root - making a clean root the only way to fully prevent phantom dependencies.

Already Converted (Reference)

Merged:

• storybook → @wordpress/storybook (PR Infrastructure: Convert storybook to a workspace package #74640)

• Convert directories in test/ to workspaces #74684

• test/e2e → @wordpress/e2e-tests-playwright

• test/performance → @wordpress/performance-tests

• test/storybook-playwright → @wordpress/storybook-playwright

Conversion Pattern

Each workspace conversion follows this pattern (established in PR #74640):

1. Create package.json in the target directory with:

   • Name: @wordpress/<workspace-name>
   • "private": true for non-published packages
   • Only required devDependencies
   • Workspace-specific scripts

2. Create/update tsconfig.json extending ../../tsconfig.base.json

3. Update root package.json:

   • Add to "workspaces" array
   • Update scripts to use npm run --workspace @wordpress/<name> syntax
   • Remove migrated dependencies (once all consumers are converted)

4. Update root tsconfig.json with project reference

5. Update CI workflows to use workspace-scoped commands

I asked Claude Code to come up with a phased plan for the conversion. Here is what it came up with:

Phase 1: Test Infrastructure

1.1 Unit Tests Workspace

• Create test/unit workspace → @wordpress/unit-tests - refactor: migrate tests/unit to npm workspace @wordpress/unit-tests #77063

1.2 Native Tests Workspace

• Create test/native workspace → @wordpress/native-tests - Migrate native tests to workspace #77425

1.3 Integration Tests Workspace

• Create test/integration workspace → @wordpress/integration-tests - Test(Integration): migrate test/integration into @wordpress/integration-tests workspace #77556

Phase 2: Documentation Tools

2.1 API Documentation Generator

• Create tools/api-docs workspace → @wordpress/api-docs-generator - refactor: migrate bin/api-docs to tools/api-docs as workspace @wordpress/api-docs-generator #77019

Phase 3: Release & Plugin Tools

3.1 Plugin CLI Tools

• Create tools/release workspace → @wordpress/release-tools - Tools(Release): migrate bin/plugin into @wordpress/release-tools workspace #77695

3.2 Cherry-Pick Tool

• Include in tools/release or create separate workspace - Add cherry-pick script and update release tools in package.json #78560

3.3 PHP Sync Issue Generator

• Include in tools/release workspace - Move PHP Sync Issue Generator file to @wordpress/release-tools #78456

Phase 4: Build & Validation Tools

4.1 Build Tools

• Create tools/build workspace → @wordpress/build-tools - Build Tools: Move build scripts to @wordpress/build-scripts workspace package #78509

  Consideration: These scripts are core to the build process and have deep integration with lerna and the package build system. May need careful evaluation of whether separation is beneficial.

4.2 Validation Tools

• Create tools/validation workspace → @wordpress/validation-tools - Refactor validation tools and update related scripts #77522

Phase 5: ESLint Configuration

5.1 ESLint Tools

• Create tools/eslint workspace → @wordpress/eslint-tools - ESLint: Consolidate config into tools/eslint/ workspace package #77215

Phase 6: Miscellaneous Tools

6.1 Create Block Test

• Move to tools/validation - Migrate create-test-block.sh to @wordpress/validation-tools workspace #78665

Current State:

• bin/test-create-block.sh - Shell script for testing create-block
• CI: create-block.yml workflow

Tasks:

• Move bin/test-create-block.sh → tools/validation/test-create-block.mjs. Use child_process to invoke npm/bins via npm exec --no -- <bin> (no hardcoded paths). Wire it up:
• tools/validation/package.json: add @wordpress/create-block (file:../../packages/create-block) devDep and "test-create-block": "node ./test-create-block.mjs" script.
• Root package.json: "test:create-block": "npm run --workspace @wordpress/validation-tools test-create-block --".
• .github/workflows/create-block.yml: run: npm run test:create-block.

6.2 Performance Results Logger

• Include in tools/release workspace - feat: Migrate performance results to tools release #78761

Phase 7: Cleanup & Finalization

7.1 Root Package.json Cleanup

Tasks

• Remove .browserslistrc from root - feat: Migrate the browserlintrc file to packages/postcss-plugins-preset #78764

  • Delete .browserslistrc
  • Add @wordpress/browserslist-config to packages/postcss-plugins-preset/package.json
  • Add overrideBrowserslist: require( '@wordpress/browserslist-config' ) to require( 'autoprefixer' )() call after grid: true

• Move babel deps out of root Refactor workspace configuration for Babel dependencies #78974

  • Verify that there are no babel related deps in root

• Move test/jest deps out of root - Refactor: Remove jest/test deps from root package.json #78801

  • Remove test/jest related deps from root
  • Add the required deps to all the workspaces that need them

• Move @types/prettier out of root - Remove migrated dependencies from root package.json #78813

  • Remove @types/prettier from root package.json
  • Add @types/prettier to devDependencies in packages/prettier-config/package.json

• Move @types/node out of root - Remove migrated dependencies from root package.json #78813

  • Remove @types/node from root package.json
  • Remove typeRoots entry from test/performance/tsconfig.json, because that was the last package to use @types/node from the root. Removing that entry will make it rely on its own declared dependency in isolated mode.

• Move react related types out of root. - refactor: move React dependencies to workspace configuration and upda… #78981

  • Remove react and react-dom from root package.json
  • Move react-docgen-typescript from root to storybook/package.json
  • Add react or react-dom as workspace dependencies/devDependencies/peerDependencies as needed
  • Update build-scripts build vendor script to resolve dependencies from the workspace directory, instead of root.
  • Update the consumer routes, if needed.

• Move glob out of root - Refactor to move 'glob' dependency to appropriate workspaces #79145

  • Remove glob from root package.json
  • Add "glob": "^13.0.6" to packages/dependency-extraction-webpack-plugin/ and packages/readable-js-assets-webpack-plugin/package.json

• Convert routes/lock-unlock.ts to a workspace - Add lock-unlock route as a workspace and update dependencies #79138

  • Create a workspace for the file - routes/lock-unlock/route.ts just like other routes
  • Add an appropriate package.json file like other routes.
  • Declare @wordpress/private-apis as the only dependency
  • Update the consumer routes, if needed.

• Move eslint and relevant deps out of root - Eslint: move deps from root into tools/eslint and packages/eslint-plugin #79110

  • Remove eslint, eslint-formatter-compact, and @eslint/eslintrc from root package.json
  • Add eslint and eslint-formatter-compact to tools/eslint/package.json
  • Add eslint to dev deps in packages/eslint-plugin/package.json
  • Update tools/eslint/lint-js.cjs to resolve formatters from the workspace directory

• Move prettier out of root - Refactor Prettier configuration and update dependencies #79219

  • Remove prettier from root package.json
  • Change require( '@wordpress/prettier-config' ) to require( './packages/prettier-config' ) in .prettierrc.js
  • Add "prettier": "npm:wp-prettier@^3.0.3" to packages/theme/package.json

• Add missing devDependencies to root, as they are used there. - fix: Add missing root devDependencies for WordPress packages #79221

  • "@playwright/test": "^1.58.2",
  • "@wordpress/env": "file:./packages/env",
  • "@wordpress/scripts": "file:./packages/scripts",

• Decouple .npmpackagejsonlintrc from root. - Refactor npm-package-json-lint configuration and update dependencies #79223

  • Remove .npmpackagejsonlintrc.json
  • Add @wordpress/npm-package-json-lint-config to packages/stylelint-config/package.json
  • Create .npmpackagejsonlintrc.js

• Move stylelint config and deps out of root - Refactor: move stylelint config and deps to tools/stylelint workspace #79226

  • Remove stylelint-plugin-logical-css from root package.json
  • Create tools/stylelint workspace and move .stylelingrc.js to tools/stylelint/config.js
  • Expose the moved config via package.json exports
  • Create .stylelintrc.mjs in root which extends '@wordpress/stylelint-tools/config'

• Remove @wordpress/vips from root

7.2 Dependencies to Keep in Root

Let us aim to remove as many dependencies from the root as possible.

Verification

After all workspaces are created and verified:

• Remove migrated dependencies from root package.json
• Verify all scripts work correctly
• Update documentation
• Add a CI check for root deps which fails when new dep is added to root. - CI: Disallow new dependencies in the root package.json #78616

7.3 CI Workflow Updates Summary

Workflows that need updates:

• unit-test.yml - Use @wordpress/unit-tests workspace
• static-checks.yml - Use validation tools workspace
• performance.yml - Use release tools workspace
• publish-npm-packages.yml - Use release tools workspace
• create-block.yml - Potentially update paths

7.4 Documentation

Done via #78615

• Update contributing documentation, especially highlighting to create workspaces in tools if something needs for the repo, instead of adding dependencies to the root.
• Add workspace development guide
• Update CI documentation

Implementation Order

Follow the phases sequentially:

1. Phase 1: Test Infrastructure (Unit, Native, Integration tests)
2. Phase 2: Documentation Tools (API docs generator)
3. Phase 3: Release & Plugin Tools (CLI, cherry-pick, PHP sync)
4. Phase 4: Build & Validation Tools
5. Phase 5: ESLint Configuration
6. Phase 6: Miscellaneous Tools
7. Phase 7: Cleanup & Finalization

Notes

• Each phase can be implemented as a separate PR for easier review
• Test thoroughly in CI before merging
• Keep backward compatibility during transition (old script paths can delegate to new workspaces)
• Monitor CI performance after each change

Related PRs

• Infrastructure: Convert storybook to a workspace package #74640 - Storybook workspace conversion (reference implementation)
• Convert directories in test/ to workspaces #74684 - [In Progress] - Additional workspace conversions
• Framework: Update Node.js version to v24 LTS #72973 - Many of these tools can later be converted to TypeScript when we use Node v24 with native type stripping