Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/toolkit-vite-engine.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'10up-toolkit': major
---

Build with Vite+ and `@10up/wp-vite-plugins` instead of webpack.

`build`, `watch` and `start` keep the same CLI and read the same `"10up-toolkit"` config from package.json, and the dist layout is unchanged. `start --hot` now starts a Vite dev server, bridged into WordPress by `dist/dev-server.php`. `lint-js` and `format-js` run Oxlint and Oxfmt; `test` runs Vitest. Projects can customize the build with a `vite.config.mjs` that starts from `toolkit()` in `10up-toolkit/vite`. Node `^22.18.0` or `>=24.11.0` is required. See UPGRADING.md for what changed and what was removed.
4 changes: 2 additions & 2 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,12 @@ jobs:
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
# Test node 20/22/24 on Ubuntu
# Test node 22/24 on Ubuntu
# Test node 24 on macOS/Windows
# Enable linting only for node 24 & Ubuntu
matrix:
os: [ubuntu-latest]
node: [20, 22, 24]
node: [22, 24]
include:
- os: macos-latest
node: 24
Expand Down
15,169 changes: 5,885 additions & 9,284 deletions package-lock.json

Large diffs are not rendered by default.

5 changes: 3 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,8 @@
"overrides": {
"@types/node": "^20.19.0",
"minimatch": "^9.0.7",
"stylelint-declaration-strict-value": "~1.10.11"
"stylelint-declaration-strict-value": "~1.10.11",
"vite": "npm:@voidzero-dev/vite-plus-core@^1.5.0"
},
"devDependencies": {
"@changesets/cli": "^2.26.1",
Expand All @@ -34,7 +35,7 @@
},
"description": "Collection of reusable scripts for 10up development.",
"engines": {
"node": ">=20.9.0",
"node": "^22.18.0 || >=24.11.0",
"npm": ">=10"
}
}
4 changes: 3 additions & 1 deletion packages/toolkit/.eslintignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,4 @@
node_modules
test-project
test-project
**/dist
**/__fixtures__
2 changes: 2 additions & 0 deletions packages/toolkit/.eslintrc.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,7 @@ module.exports = {
'global-require': 'off',
'import/no-dynamic-require': 'off',
'no-process-exit': 'off',
// Packages that only expose an `exports` map, which the resolver can't read.
'import/no-unresolved': ['error', { ignore: ['^vite-plus', '^@10up/wp-vite-plugins'] }],
},
};
525 changes: 94 additions & 431 deletions packages/toolkit/README.md

Large diffs are not rendered by default.

86 changes: 86 additions & 0 deletions packages/toolkit/UPGRADING.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,91 @@
# Upgrade Guide

## Upgrading from 7 to 8

Version 8 replaces webpack with [Vite+](https://viteplus.dev) (Vite 8 and Rolldown) and
[`@10up/wp-vite-plugins`](https://github.com/10up/wp-vite-plugins). The CLI and the `"10up-toolkit"` config in
`package.json` stay the same, and so does the dist layout: `dist/js/<entry>.js`, `dist/css/<entry>.css`,
`dist/blocks/<block>/…`, `dist/blocks/autoenqueue/…`, and an `.asset.php` file next to every script and stylesheet.
Most projects upgrade by bumping the version and running a build.

### Node version

Node `^22.18.0` or `>=24.11.0` is required, the versions Vite+ supports. Node 20 is no longer supported.

### What to check after upgrading

1. **Run `npm run build` and compare `dist/`** with a build from version 7. Expect the same files. Extra files you will
see: `dist/dev-server.php` and `dist/fast-refresh.php`, plus an `.asset.php` for every CSS-only entry.
2. **JSX now uses the automatic runtime.** Scripts with JSX depend on `react-jsx-runtime` instead of `wp-element`.
WordPress 6.6 and later provide it.
3. **`@wordpress/*` packages.** A package you import but did not install is still treated as provided by WordPress,
as before. Install the packages you import anyway: installed packages give you TypeScript types, and Script
Module packages such as `@wordpress/interactivity` are then detected from their own metadata.
4. **Hot reloading.** `start --hot` now starts a Vite dev server. Replace the `fast-refresh.php` code in your theme or
plugin with:

```php
if ( file_exists( __DIR__ . '/dist/dev-server.php' ) ) {
require_once __DIR__ . '/dist/dev-server.php';
}
```

Until you do, toolkit writes a `dist/fast-refresh.php` shim that loads `dev-server.php`, and
`TenUpToolkit\set_dist_url_path()` does nothing. The `devURL`, `hot` and `devServer` settings for webpack-dev-server
no longer apply. The dev server listens on port 8000; change it with `--port`.
5. **Minified CSS looks different.** Lightning CSS minifies the output, so `@media (min-width: 30em)` ships as
`@media (width>=30em)`. Browsers read both the same way.

### Removed

- **A project `webpack.config.js`.** Toolkit ignores it. Move customizations to a `vite.config.mjs`:

```js
import { toolkit } from '10up-toolkit/vite';

export default toolkit({
// Any Vite config, merged on top of toolkit's.
});
```

- **Linaria and vanilla-extract.** Toolkit no longer compiles them. Add their Vite plugins in a `vite.config.mjs`
if you still need them.
- **Image and SVG minification** (`image-minimizer-webpack-plugin`, `svgo.config.js`). Images, fonts and SVG files
are copied to `dist/` unchanged. Optimize them before you commit them.
- **`--analyze`** (webpack-bundle-analyzer), **`--target`**, **`--include`** and the core-js polyfills. Vite compiles
dependencies as needed and targets modern browsers.
- **CSS source maps in production builds.** `--sourcemap` still writes maps for scripts.
- **Babel.** A project `babel.config.js` is ignored. `@10up/babel-preset-default` is no longer a peer dependency.

### Linting, formatting and tests

- `lint-js` runs [Oxlint](https://oxc.rs/docs/guide/usage/linter) and `format-js` runs Oxfmt, with toolkit's default
configs (`config/oxlintrc.json`, and the 10up house style in `config/oxfmtrc.json`). A project with its own
`.oxlintrc.json` / `.oxfmtrc.json`, or a `vite.config.*` with `lint` / `fmt` blocks, uses that instead.
- A project that keeps an ESLint config and installs `eslint` itself still runs ESLint, so its rules do not change
until you remove the ESLint config. `@10up/eslint-config` is no longer a peer dependency.
- `lint-style` is unchanged.
- `test` runs [Vitest](https://vitest.dev) with the jsdom environment and Jest-style globals. `jest` is an alias of
`vi`, so `jest.fn()` and `jest.spyOn()` keep working. `test-unit-jest` and `test-unit-js` are aliases of `test`. Jest
config files are ignored; move settings to the `test` block of a `vitest.config.mjs`.
- Replace lint-staged with `vp staged` and a `staged` block in a root `vite.config.ts`. See the README.

### Optional: install Vite+ for the whole project

To use `vp check`, `vp test` and `vp run` across a monorepo, install `vite-plus` at the root and add this override so
npm installs one copy of Vite:

```json
{
"devDependencies": {
"vite-plus": "^1.5.0"
},
"overrides": {
"vite": "npm:@voidzero-dev/vite-plus-core@^1.5.0"
}
}
```

## Upgrading from 6 to 7

### Node version
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
/* eslint-disable import/no-extraneous-dependencies */
import { describe, it, expect, beforeAll } from 'vite-plus/test';
import spawn from 'cross-spawn';
import fs from 'fs';
import path from 'path';
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
/* eslint-disable import/no-extraneous-dependencies */
import { describe, it, expect } from 'vite-plus/test';
import spawn from 'cross-spawn';
import fs from 'fs';
import path from 'path';
Expand Down Expand Up @@ -38,8 +39,8 @@ describe('build a project', () => {
const compiledHeadingBlockCSS = fs.readFileSync(headingBlockCSS).toString();
const compiledGroupBlockCSS = fs.readFileSync(groupBlockCSS).toString();

// expect the compiled CSS to contain "min-width: 30em"
expect(compiledHeadingBlockCSS).toMatch('min-width: 30em');
expect(compiledGroupBlockCSS).toMatch('min-width: 30em');
// The global `@custom-media` resolved; Lightning CSS minifies it to `(width>=30em)`.
expect(compiledHeadingBlockCSS).toMatch(/\(width>=30em\)|min-width:\s*30em/);
expect(compiledGroupBlockCSS).toMatch(/\(width>=30em\)|min-width:\s*30em/);
});
});
5 changes: 3 additions & 2 deletions packages/toolkit/__tests__/build-project-global-css/test.js
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
/* eslint-disable import/no-extraneous-dependencies */
import { describe, it, expect } from 'vite-plus/test';
import spawn from 'cross-spawn';
import fs from 'fs';
import path from 'path';
Expand All @@ -18,7 +19,7 @@ describe('build a project', () => {

const compiledCSS = fs.readFileSync(frontendCss).toString();

// expect the compiled CSS to contain "min-width: 30em"
expect(compiledCSS).toMatch('min-width: 30em');
// The global `@custom-media` resolved; Lightning CSS minifies it to `(width>=30em)`.
expect(compiledCSS).toMatch(/\(width>=30em\)|min-width:\s*30em/);
});
});

This file was deleted.

This file was deleted.

This file was deleted.

This file was deleted.

This file was deleted.

9 changes: 0 additions & 9 deletions packages/toolkit/__tests__/build-project-linaria/package.json

This file was deleted.

29 changes: 0 additions & 29 deletions packages/toolkit/__tests__/build-project-linaria/test.js

This file was deleted.

3 changes: 2 additions & 1 deletion packages/toolkit/__tests__/build-project-modules/test.js
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
/* eslint-disable import/no-extraneous-dependencies */
import { describe, it, expect } from 'vite-plus/test';
import spawn from 'cross-spawn';
import fs from 'fs';
import path from 'path';
Expand All @@ -19,7 +20,7 @@ describe('build a project with moduleEntry', () => {

// ensure admin is a module
const adminJs = fs.readFileSync(adminJsPath).toString();
expect(adminJs).toMatch(/export {.*};/);
expect(adminJs).toMatch(/export\s*\{.*\}/);
});

it('extracts css imported in js files', () => {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
/* eslint-disable import/no-extraneous-dependencies */
import { describe, it, expect } from 'vite-plus/test';
import spawn from 'cross-spawn';
import fs from 'fs';
import path from 'path';
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
/* eslint-disable import/no-extraneous-dependencies */
import { describe, it, expect, beforeAll } from 'vite-plus/test';
import spawn from 'cross-spawn';
import fs from 'fs';
import path from 'path';
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
/* eslint-disable import/no-extraneous-dependencies */
import { describe, it, expect, beforeAll } from 'vite-plus/test';
import spawn from 'cross-spawn';
import fs from 'fs';
import path from 'path';
Expand All @@ -25,7 +26,7 @@ describe('build a project (with useBlockAssets)', () => {
.readFileSync(path.join(__dirname, 'dist', 'js', 'frontend.asset.php'))
.toString();

expect(frontendAssetPHP).toMatch('wp-element');
expect(frontendAssetPHP).toMatch('react-jsx-runtime');
expect(frontendAssetPHP).toMatch('react-dom');
expect(frontendAssetPHP).toMatch('react');
});
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
/* eslint-disable import/no-extraneous-dependencies */
import { describe, it, expect, beforeAll } from 'vite-plus/test';
import spawn from 'cross-spawn';
import fs from 'fs';
import path from 'path';
Expand All @@ -25,7 +26,7 @@ describe('build a project (withb block-modules)', () => {
.readFileSync(path.join(__dirname, 'dist', 'js', 'frontend.asset.php'))
.toString();

expect(frontendAssetPHP).toMatch('wp-element');
expect(frontendAssetPHP).toMatch('react-jsx-runtime');
expect(frontendAssetPHP).toMatch('react-dom');
expect(frontendAssetPHP).toMatch('react');

Expand Down Expand Up @@ -56,6 +57,6 @@ describe('build a project (withb block-modules)', () => {

const viewModuleFileContents = fs.readFileSync(viewModuleFile).toString();

expect(viewModuleFileContents).toMatch(/import \* as .* from "@wordpress\/interactivity";/);
expect(viewModuleFileContents).toMatch(/from\s*"@wordpress\/interactivity"/);
});
});

This file was deleted.

Loading
Loading