@10up/wp-vite-plugins 1.0.0-alpha.2 → 1.0.0-alpha.4

package/README.md

@@ -7,14 +7,34 @@ A focused set of Vite plugins that handle what WordPress projects actually need:
 ## Install
 
 ```sh
-npm install --save-dev @10up/wp-vite-plugins
+npm install --save-dev @10up/wp-vite-plugins@alpha
 ```
 
-Requires Node ≥ 20.11 and Vite ^8 (Rolldown-powered).
+1.0 is in alpha, published under the `alpha` dist-tag. Requires Node `^22.18.0 || ^24.11.0 || >=26` and Vite 8 (Rolldown-powered).
+
+### Coming from `10up-toolkit`?
+
+[Migrating from `10up-toolkit`](./docs/migrating-from-toolkit.md) walks a wp-scaffold project over to Vite+ and these plugins, and the [migration field notes](./docs/migration-field-notes.md) collect what real migrations ran into.
 
 ### Vite+ / Rolldown compatibility
 
-The plugins use only Rolldown-implemented plugin APIs, so they work unchanged with [Vite+](https://viteplus.dev) — `vp dev`, `vp build`, and `vp build --mode modules` read the same `vite.config.ts` and produce identical output to plain `vite` commands. The test suite runs under `vp test` (Vitest) as well.
+The plugins use only Rolldown-implemented plugin APIs, so they work unchanged with [Vite+](https://viteplus.dev) — `vp dev` and `vp build` read the same `vite.config.ts` as plain `vite` commands and produce identical output. The test suite runs under `vp test` (Vitest) as well.
+
+In a Vite+ project, pin `vite` to the Vite+ core with an npm override, as `vp migrate` does. Without it, npm installs a second, plain Vite next to Vite+, and `vp` refuses to run against it. The `vite` peer range is `^8.0.0 || ^1.0.0`: Vite 8, or `@voidzero-dev/vite-plus-core` 1.x under the `vite` alias (Vite never had a stable 1.x). Without the second half, npm marks the override invalid and refuses to upgrade a lockfile to a newer Vite+:
+
+```json
+{
+	"devDependencies": {
+		"@10up/wp-vite-plugins": "^1.0.0-alpha.4",
+		"vite-plus": "^1.6.0"
+	},
+	"overrides": {
+		"vite": "npm:@voidzero-dev/vite-plus-core@^1.6.0"
+	}
+}
+```
+
+This repository builds, lints, formats and tests itself with Vite+ (`vp pack`, `vp check`, `vp test`).
 
 ## Quick start
 
@@ -40,19 +60,20 @@ That single call wires up:
 - **`wpBlocks`** — discovers every `block.json`, turns `file:` references into Rollup entries, copies `block.json` + sibling PHP into `dist/`, and emits `blocks-manifest.php` (WP 6.7+).
 - **`wpBlockStyles`** — emits each stylesheet under `blocksStylesDir` as its own CSS entry for selective PHP enqueueing.
 - **`wpCopyAssets`** — copies images / fonts / SVG from `copyAssetsDir` to `dist/`.
-- **`wpAdminPages`** — builds `@wordpress/boot` admin pages from `adminPagesDir` in the module pass (`content` / `route` entries, `loader.js` anchor, per-page `content.css`), and optionally generates the whole `@wordpress/build`-style PHP registration layer.
-- **`wpExternals`** — rewrites `@wordpress/*` imports against `window.wp.*` (or preserves them as ESM in module mode) and emits `<entry>.asset.php` dependency sidecars.
-- **`wpScriptDedupe`** _(auto, script mode)_ — gives every script-mode entry a private copy of the modules it imports, so no entry has to `import` a shared chunk (a classic script can't).
-- **`wpScriptIife`** _(auto)_ — wraps script-mode entries in an IIFE so they enqueue cleanly as classic `<script>` tags, defines `import.meta` away, and fails the build on output that isn't valid as a classic script.
+- **`wpCss`** _(when `css` is set)_ — compiles CSS with Lightning CSS and gives every stylesheet the project's custom media, custom selectors and mixins without an `@import`. Relative `url()`s work in the build and on the dev server.
+- **`wpAdminPages`** — builds `@wordpress/boot` admin pages from `adminPagesDir` as Script Modules (`content` / `route` entries, `loader.js` anchor, per-page `content.css`), and optionally generates the whole `@wordpress/build`-style PHP registration layer.
+- **`wpExternals`** — rewrites `@wordpress/*` imports against `window.wp.*` (or preserves them as ESM for Script Modules) and emits `<entry>.asset.php` dependency sidecars.
+- **`wpScriptDedupe`** _(auto, classic scripts)_ — gives every classic-script entry a private copy of the modules it imports, so no entry has to `import` a shared chunk (a classic script can't).
+- **`wpScriptIife`** _(auto, classic scripts)_ — wraps classic-script entries in an IIFE so they enqueue cleanly as classic `<script>` tags, defines `import.meta` away, and fails the build on output that isn't valid as a classic script.
 - **`wpCleanCssChunks`** _(auto)_ — deletes the empty JS shims Vite leaves next to CSS-only entries.
+- **`wpCssAssetInfo`** _(auto)_ — emits an `.asset.php` sidecar for CSS-only entries, which `wpExternals` can't write for them (there's no JS chunk to walk).
+- **`wpEnvironments`** _(auto)_ — builds classic scripts and Script Modules as two Vite build environments into one `dist/`; see [below](#classic-scripts-and-script-modules).
+- **`wpCssEntryGuard`** _(auto)_ — keeps CSS-only entries whose output is byte-identical (two empty stylesheets, say) from collapsing into one emitted file, which would 404 the other.
 
 ## Wrapper options
 
 ```ts
 wp({
-  // Build mode for all sub-plugins. Default: 'script'.
-  buildType: 'script', // or 'module'
-
   // Top-level shortcuts — pass a directory to enable the plugin.
   blocksDir:       './includes/blocks',
   blocksStylesDir: './assets/css/blocks',
@@ -65,48 +86,71 @@ wp({
   copyAssets:  { pattern: '**/*.{png,svg}' },
   adminPages:  { php: {} }, // `php` turns on PHP generation; see docs/wp-admin-pages.md
   externals: {
-    scriptModuleNamespaces: ['ignite-*'],
+    scriptModuleNamespaces: ['acme-*'],
     additionalExternals:    { myLib: { global: 'MyLib', handle: 'my-lib' } },
+    moduleEntryMatchers:    ['/assets/js/modules/'], // your own Script Module entries
   },
 
   // Helper opt-outs.
-  scriptDedupe:   false, // disable wpScriptDedupe (script mode only)
-  iife:           false, // disable wpScriptIife (script mode only)
+  scriptDedupe:   false, // disable wpScriptDedupe (classic scripts only)
+  iife:           false, // disable wpScriptIife (classic scripts only)
   cleanCssChunks: false, // disable wpCleanCssChunks (always on by default)
 });
 ```
 
 `externals` is always included unless you pass `externals: false`. The other four are included only when their directory option is provided (top-level or nested). See [docs/wp.md](./docs/wp.md) for the full inclusion and option-merging rules.
 
-## Dual-pass builds (script + module)
+## Classic scripts and Script Modules
+
+One `vp build` builds both. `wp()` declares two [Vite build environments](https://vite.dev/guide/api-environment) — `client` for classic scripts (`window.wp.*`, IIFEs) and `modules` for Script Modules (ESM, bare `@wordpress/*` specifiers for WordPress's import map) — and builds them into one `dist/`:
+
+```jsonc
+{
+  "scripts": {
+    "build": "vp build",          // both environments; dist/ emptied once
+    "watch": "vp build --watch",  // each environment rebuilds on its own
+    "dev": "vp dev"               // one dev server serves both; see below
+  }
+}
+```
 
-For projects that ship both classic scripts and Script Modules, dispatch on Vite's `mode`:
+Block assets go where their `block.json` field says (`viewScriptModule` → `modules`), admin pages are always Script Modules, and your own `build.rollupOptions.input` entries are classic scripts unless their path matches `externals.moduleEntryMatchers`:
 
 ```ts
-export default defineConfig(({ mode }) => ({
-  plugins: [
-    wp({
-      buildType: mode === 'modules' ? 'module' : 'script',
-      blocksDir: './includes/blocks',
-    }),
-  ],
-}));
+wp({ externals: { moduleEntryMatchers: ['/assets/js/modules/'] } })
 ```
 
-Run the two passes separately: `vite build` (default script mode) and `vite build --mode modules`. The module pass is safe to run unconditionally — when no block declares a `scriptModule` / `viewScriptModule` (and no other module entries are configured), `wpBlocks` turns it into a no-op build instead of letting Rollup error on empty input.
+A project with no Script Modules skips the `modules` environment. Because the build is one cache-aware command, `vp run --cache build` replays `dist/` when nothing changed. → [Details](./docs/wp.md#classic-scripts-and-script-modules)
 
-Or let the bundled CLI drive both passes, one command per task — it cleans `dist/` exactly once and keeps the passes from deleting each other's output:
+## Dev server
 
-```jsonc
-{
-  "scripts": {
-    "build": "wp-vite build", // script pass, then module pass; fails fast
-    "watch": "wp-vite watch" // both passes watched in a single process
-  }
+`vp dev` starts a real Vite dev server for a WordPress install — instant transforms, native ESM in the browser, HMR — and writes the one file PHP needs to know about it:
+
+```sh
+vp dev
+```
+
+```
+dist/.wp-vite-dev.json   { "origin": "http://localhost:5173", "base": "/", "plugins": [] }
+```
+
+Present means hot; absent means serve the built files. Alongside it, [`wpDevServer`](./docs/wp-dev-server.md) writes dev `.asset.php` sidecars for every entry a build writes one for — blocks, block styles, admin pages and your own `rollupOptions.input` entries — with the same keys a build writes plus `'source'`, mapping each asset back to the file the server serves. It also writes the `block.json` / `blocks-manifest.php` tree `register_block_type()` reads off disk, and keeps all of it in step as blocks are added and removed mid-session.
+
+Wiring it into WordPress is one line, next to your other `dist/` requires:
+
+```php
+if ( file_exists( __DIR__ . '/dist/dev-server.php' ) ) {
+	require_once __DIR__ . '/dist/dev-server.php';
 }
 ```
 
-→ [Full documentation](./docs/cli.md)
+`dev-server.php` is generated by every build (and by the dev server on start). Cold, it costs one `file_exists()`. Hot, it repoints every classic script (`script_loader_src` + a `type="module"` stamp), every Script Module (`script_module_loader_src`, WP 6.5+) and every stylesheet enqueued out of `dist/` at the running server, and enqueues Vite's HMR client. **No other PHP changes** — your registration code doesn't know the difference.
+
+One server handles both kinds of entry: a classic entry gets the `window.wp.*` rewrite, a Script Module entry keeps its bare `@wordpress/*` specifiers for WordPress's runtime import map. The plugin is included by `wp()` by default, is `apply: 'serve'`, and costs a build nothing.
+
+`@vitejs/plugin-react` gets React Fast Refresh for free — no extra config. When the hot file reports the plugin, `dev-server.php` attaches its preamble to the Vite client handle, ahead of every component module.
+
+→ [Full documentation](./docs/wp-dev-server.md)
 
 ## Using plugins individually
 
@@ -115,6 +159,7 @@ The wrapper is just sugar. Every plugin is exported on its own for finer control
 ```ts
 import { defineConfig } from 'vite';
 import {
+  wpEnvironments,
   wpBlocks,
   wpBlockStyles,
   wpCopyAssets,
@@ -127,15 +172,21 @@ import {
 
 export default defineConfig({
   plugins: [
-    wpBlocks({ blocksDir: './includes/blocks', buildType: 'script' }),
+    // The `client` + `modules` build environments. Without it only `client`
+    // exists, and Script Module entries never build.
+    wpEnvironments(),
+    wpBlocks({ blocksDir: './includes/blocks' }),
     wpBlockStyles({ blocksStylesDir: './assets/css/blocks' }),
     wpCopyAssets({ copyAssetsDir: './assets' }),
-    // Module pass only — a no-op with buildType: 'script'. Composed by hand,
-    // it needs a matching `wpBuildAssetMatchers` entry on wpExternals.
-    wpAdminPages({ adminPagesDir: './assets/js/admin-pages', buildType: 'module' }),
-    wpExternals({ buildType: 'script' }),
-    // Script mode only, and in this order: dedupe partitions the graph, the
-    // IIFE wrapper vets the result.
+    // Composed by hand, it needs a matching `wpBuildAssetMatchers` entry on
+    // wpExternals.
+    wpAdminPages({ adminPagesDir: './assets/js/admin-pages' }),
+    ...wpExternals({ wpBuildAssetMatchers: ['/assets/js/admin-pages/'] }),
+    // Classic scripts only (each applies to `client` alone), in this order:
+    // dedupe partitions the graph, the IIFE wrapper vets the result. Composed by hand, wpScriptIife gets no
+    // `globals` map, so Rolldown's runtime `require()` of an external has
+    // nothing to resolve against — pass wpExternals' `globalsSink` through
+    // both if any dependency reaches an external from CommonJS.
     wpScriptDedupe(),
     wpScriptIife(),
     wpCleanCssChunks(),
@@ -147,13 +198,19 @@ export default defineConfig({
 
 Two runnable consumer projects live under [`examples/`](./examples/README.md), each with a WordPress Playground blueprint for end-to-end verification:
 
-- [`examples/minimal-block-plugin`](./examples/minimal-block-plugin) — one plugin, one block, single-pass build.
-- [`examples/scaffold-monorepo`](./examples/scaffold-monorepo) — a full [10up/wp-scaffold](https://github.com/10up/wp-scaffold)-style monorepo (classic theme, block theme, mu-plugin) building through npm workspaces, including a dual-pass Script Module build.
+- [`examples/minimal-block-plugin`](./examples/minimal-block-plugin) — one plugin, one block.
+- [`examples/scaffold-monorepo`](./examples/scaffold-monorepo) — a full [10up/wp-scaffold](https://github.com/10up/wp-scaffold)-style monorepo (classic theme, block theme, mu-plugin) building through npm workspaces, including Interactivity API Script Modules and `@wordpress/boot` admin pages.
 
 ## Plugins
 
 The sections below are the quick reference. Each plugin also has an in-depth page under [`docs/`](./docs/README.md) covering internals, output formats, and caveats.
 
+### `wpDevServer(options)`
+
+→ [Full documentation](./docs/wp-dev-server.md)
+
+Serve-only (`apply: 'serve'`), included by `wp()` by default. Writes `dist/.wp-vite-dev.json` on `listening` and deletes it on exit; writes dev `.asset.php` sidecars and the blocks metadata tree; keeps Script Module entries' bare specifiers intact for WordPress's import map; refreshes everything on watcher events. Its build-side twin `wpDevServerPhp` emits `dist/dev-server.php`, the PHP bridge, into every build. Disable both with `wp({ devServer: false })`.
+
 ### `wpBlocks(options)`
 
 → [Full documentation](./docs/wp-blocks.md)
@@ -170,7 +227,6 @@ Scans `blocksDir` for `block.json` files. For each one:
 | Option | Type | Default | Notes |
 | --- | --- | --- | --- |
 | `blocksDir` | `string` | (required) | Root directory containing `block.json` files. |
-| `buildType` | `'script' \| 'module'` | `'script'` | Which `block.json` fields to discover as entries. |
 | `emitManifest` | `boolean` | `true` | Emit `blocks-manifest.php`. |
 | `skip` | `string[]` | `[]` | Block directory names (relative to `blocksDir`) to skip entirely. |
 
@@ -193,25 +249,27 @@ The sidecar comes in two shapes, chosen per entry, because WordPress core and bo
 
 For every entry, `version` now hashes the chunk code *and* its extracted CSS, and dependencies are unioned across the entry chunk and every chunk it imports, so shared chunks don't lose deps. See the [sidecar reference](./docs/wp-externals.md#the-assetphp-sidecar) and its [breaking-change note](./docs/wp-externals.md#breaking-change-pre-10).
 
-For non-`@wordpress/*` packages, a hardcoded vendor map covers `react`, `react-dom`, `jquery`, `lodash`, `moment`. Pass `additionalExternals` to extend or replace that map.
+For non-`@wordpress/*` packages, a hardcoded vendor map covers `react`, `react-dom`, `jquery`, `lodash`, `lodash-es`, `moment`. Pass `additionalExternals` to extend or replace that map.
 
 **Options**
 
 | Option | Type | Default | Notes |
 | --- | --- | --- | --- |
 | `projectRoot` | `string` | `process.cwd()` | Resolution root for `@wordpress/*` package metadata. |
-| `buildType` | `'script' \| 'module'` | `'script'` | Controls import rewriting strategy. |
 | `externalNamespaces` | `Record<string, ExternalNamespace>` | `{}` | Add classic-script externals for namespaces like `@woo/*`. |
 | `additionalExternals` | `Record<string, { global, handle }>` | (vendor map) | Override the non-scoped vendor externals. |
-| `moduleEntryMatchers` | `string[]` | `[]` | File path substrings that should be treated as module-mode regardless of `buildType`. |
+| `moduleEntryMatchers` | `string[]` | `[]` | Path substrings of Script Module entries: built in `modules` (via `wp()`), served in module mode by the dev server. |
 | `wpBuildAssetMatchers` | `string[]` | `[]` | Entry source-path substrings whose `.asset.php` uses the `@wordpress/build` shape. |
 | `scriptModuleNamespaces` | `string[]` | `[]` | Plugin-local Script Module namespaces (exact or `prefix-*` glob). |
+| `globalsSink` | `Map<string, string>` | — | Out-param, filled with specifier → window global so `wpScriptIife` can shim `require()` for CJS deps. Wired automatically by `wp()`. |
+| `bundle` | `string[]` | `[]` | Bare package names to bundle instead of externalizing, on top of the default (`@wordpress/icons`). |
+| `uninstalledWordPressPackages` | `'bundle' \| 'external'` | `'bundle'` | `'external'` assumes WordPress provides a `@wordpress/*` package that isn't installed. |
 
 ### `wpAdminPages(options)`
 
 → [Full documentation](./docs/wp-admin-pages.md)
 
-Builds [`@wordpress/boot`](https://github.com/WordPress/gutenberg/tree/trunk/packages/boot)-powered admin pages (WP 6.9+ Script Module admin screens) as part of the **module pass**, replacing a separate esbuild pipeline. Every immediate subdirectory of `adminPagesDir` with a `content` entry is a page:
+Builds [`@wordpress/boot`](https://github.com/WordPress/gutenberg/tree/trunk/packages/boot)-powered admin pages (WordPress 7.0+, or the Gutenberg plugin) as Script Modules, in the same `vp build`, replacing a separate esbuild pipeline. Every immediate subdirectory of `adminPagesDir` with a `content` entry is a page:
 
 ```
 dist/modules/<page>/
@@ -226,16 +284,15 @@ dist/modules/<page>/
 
 Entries containing JSX must use `.jsx` / `.tsx` — Vite doesn't parse JSX out of `.js`.
 
-Pass `php: {}` and the plugin also generates the `@wordpress/build`-style PHP layer next to the modules — `build.php`, `constants.php`, `pages.php`, `pages/<slug>/page{,-wp-admin}.php`, `routes.php`, `routes/registry.php` — so a consuming plugin needs no hand-written PHP beyond `require_once __DIR__ . '/dist/build.php';`. Per-page `page.json` covers titles, menu registration, init modules, modes and REST preload. See [the reference](./docs/wp-admin-pages.md#generated-php); `AbstractBootAdminPage` stays a supported alternative.
+Pass `php: {}` and the plugin also emits the `@wordpress/build`-style PHP layer next to the modules — `build.php` (the pages as data) and the `wp-boot/` classes it loads (from [`10up/wp-boot`](../wp-boot)) — so a consuming plugin needs no hand-written PHP beyond `require_once __DIR__ . '/dist/build.php';`. Per-page `page.json` covers titles, menu registration, init modules, modes and REST preload. See [the reference](./docs/wp-admin-pages.md#generated-php); `AbstractBootAdminPage` stays a supported alternative.
 
 **Options**
 
 | Option | Type | Default | Notes |
 | --- | --- | --- | --- |
 | `adminPagesDir` | `string` | (required) | Directory whose immediate subdirectories are pages. |
-| `buildType` | `'script' \| 'module'` | `'script'` | No-op in script mode; pages are Script Modules. |
 | `php` | `WpAdminPagesPhpOptions` | (off) | Presence enables PHP generation (`prefix`, `handlePrefix`, `baseUrl`, `textdomain`). |
-| `projectRoot` | `string` | Vite's `root` | `package.json` supplying the generated version / prefix defaults. |
+| `projectRoot` | `string` | Vite's `root` | Root whose `package.json` supplies the generated PHP's prefix defaults. |
 
 Via `wp({ adminPagesDir })` the pages directory is also fed to `wpExternals`' `wpBuildAssetMatchers` so page sidecars get the `@wordpress/build` shape; set that option yourself when composing the plugins by hand.
 
@@ -250,6 +307,7 @@ Every stylesheet under `blocksStylesDir` becomes a dedicated CSS entry under `di
 | Option | Type | Default | Notes |
 | --- | --- | --- | --- |
 | `blocksStylesDir` | `string` | (required) | Directory of per-block stylesheets. |
+| `outputPrefix` | `string` | `'autoenqueue'` | Directory under `dist/` the stylesheets land in. `'blocks/autoenqueue'` keeps a `10up-toolkit` project's paths. |
 
 ### `wpCopyAssets(options)`
 
@@ -263,19 +321,37 @@ Copies static assets (images, fonts, SVG) from `copyAssetsDir` to `dist/`, prese
 | --- | --- | --- | --- |
 | `copyAssetsDir` | `string` | (required) | Source directory. |
 | `pattern` | `string` | `**/*.{jpg,jpeg,png,gif,webp,avif,ico,svg,eot,ttf,woff,woff2,otf}` | Glob, relative to `copyAssetsDir`. |
-| `buildType` | `'script' \| 'module'` | `'script'` | Only runs in script mode (to avoid double-emission on dual-pass builds). |
+
+### `wpCss(options?)`
+
+→ [Full documentation](./docs/wp-css.md)
+
+Compiles every stylesheet with Lightning CSS, in place of the PostCSS stack `10up-toolkit` ran. The `@custom-media`, `@custom-selector` and `@define-mixin` definitions in the `globals` files reach every stylesheet without an `@import`, and local `@import`s are inlined. Relative `url()`s are kept relative to the built file, and on the dev server they point at the copied file's source. Use it through `wp({ css })`, which also passes `copyAssetsDir`.
+
+**Options**
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `globals` | `string[]` | `[]` | Globs of the globals files, relative to the Vite root. |
+| `mixins` | `MixinMap \| () => MixinMap` | none | Mixins defined in JS: name → declarations. |
+| `browserslist` | `string \| string[]` | the project's config | The compile targets. |
+| `assetsDir` | `string` | `wp()`'s `copyAssetsDir` | Source of the files copied into `dist/`, for dev-server urls. |
 
 ### `wpScriptDedupe()`
 
 → [Full documentation](./docs/wp-script-dedupe.md)
 
-Duplicates every statically shared module into each script-mode entry (webpack's behavior), so Rolldown never leaves an entry importing a shared chunk — invalid in a classic `<script>`. Also inlines Rolldown's CJS interop runtime and wpExternals' CJS global shims, which are injected too late to partition. Script mode + `vite build` only. No options.
+Duplicates every statically shared module into each classic-script entry (webpack's behavior), so Rolldown never leaves an entry importing a shared chunk — invalid in a classic `<script>`. Also inlines Rolldown's CJS interop runtime and wpExternals' CJS global shims, which are injected too late to partition. `client` environment + build only. No options.
 
-### `wpScriptIife()`
+### `wpScriptIife(options?)`
 
 → [Full documentation](./docs/wp-script-iife.md)
 
-Wraps each script-mode entry chunk in an IIFE in `writeBundle`. Avoids global-scope leaks when WP enqueues bundles as classic `<script>` tags. Injects the `import.meta.url` / `import.meta.resolve` `define` script mode needs, and fails the build if a chunk still holds a live `import`/`export` statement or an `import.meta` reference. No options.
+Wraps each classic-script entry chunk in an IIFE in `writeBundle`. Avoids global-scope leaks when WP enqueues bundles as classic `<script>` tags. Injects the `import.meta.url` / `import.meta.resolve` `define` classic scripts need, and fails the build — before any chunk is wrapped — if a chunk still holds a live `import`/`export` statement or an `import.meta` reference.
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `globals` | `Map<string, string>` | `new Map()` | Specifier → window global, used to shim `require()` for CJS deps Rolldown resolves at runtime. Wired automatically by `wp()`. |
 
 ### `wpCleanCssChunks()`