@10up/wp-vite-plugins 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,263 @@
+# @10up/wp-vite-plugins
+
+Vite plugins for building modern WordPress projects the 10up way.
+
+A focused set of Vite plugins that handle what WordPress projects actually need: `block.json` discovery, `@wordpress/*` externals with `.asset.php` emission, per-block style entries, and static asset copying.
+
+## Install
+
+```sh
+npm install --save-dev @10up/wp-vite-plugins
+```
+
+Requires Node ≥ 20.11 and Vite ^8 (Rolldown-powered).
+
+### 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.
+
+## Quick start
+
+The `wp()` composer covers the common case. Point it at your block directory and you're done:
+
+```ts
+import { defineConfig } from 'vite';
+import { wp } from '@10up/wp-vite-plugins';
+
+export default defineConfig({
+  plugins: [
+    wp({
+      blocksDir: './includes/blocks',
+      blocksStylesDir: './assets/css/blocks',
+      copyAssetsDir: './assets',
+    }),
+  ],
+});
+```
+
+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.
+- **`wpScriptIife`** _(auto)_ — wraps script-mode entries in an IIFE so they enqueue cleanly as classic `<script>` tags.
+- **`wpCleanCssChunks`** _(auto)_ — deletes the empty JS shims Vite leaves next to CSS-only entries.
+
+## 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',
+  copyAssetsDir:   './assets',
+  adminPagesDir:   './assets/js/admin-pages',
+
+  // Per-plugin escape hatches. Nested wins on conflict. Pass `false` to disable entirely.
+  blocks:      { skip: ['legacy-block'] },
+  blockStyles: { /* extra WpBlockStylesOptions */ },
+  copyAssets:  { pattern: '**/*.{png,svg}' },
+  adminPages:  { php: {} }, // `php` turns on PHP generation; see docs/wp-admin-pages.md
+  externals: {
+    scriptModuleNamespaces: ['ignite-*'],
+    additionalExternals:    { myLib: { global: 'MyLib', handle: 'my-lib' } },
+  },
+
+  // Helper opt-outs.
+  iife:           false, // disable wpScriptIife (script mode 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)
+
+For projects that ship both classic scripts and Script Modules, dispatch on Vite's `mode`:
+
+```ts
+export default defineConfig(({ mode }) => ({
+  plugins: [
+    wp({
+      buildType: mode === 'modules' ? 'module' : 'script',
+      blocksDir: './includes/blocks',
+    }),
+  ],
+}));
+```
+
+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.
+
+## Using plugins individually
+
+The wrapper is just sugar. Every plugin is exported on its own for finer control:
+
+```ts
+import { defineConfig } from 'vite';
+import {
+  wpBlocks,
+  wpBlockStyles,
+  wpCopyAssets,
+  wpAdminPages,
+  wpExternals,
+  wpScriptIife,
+  wpCleanCssChunks,
+} from '@10up/wp-vite-plugins';
+
+export default defineConfig({
+  plugins: [
+    wpBlocks({ blocksDir: './includes/blocks', buildType: 'script' }),
+    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' }),
+    wpScriptIife(),
+    wpCleanCssChunks(),
+  ],
+});
+```
+
+## Examples
+
+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.
+
+## 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.
+
+### `wpBlocks(options)`
+
+→ [Full documentation](./docs/wp-blocks.md)
+
+Scans `blocksDir` for `block.json` files. For each one:
+
+- Discovers `file:`-prefixed assets and registers them as Rollup entries.
+- Copies `block.json` (with `file:` references rewritten to `.js` / `.css`) and any sibling PHP files into `dist/blocks/<block-name>/`.
+- Stamps a SHA-256 `version` hash on the block when no explicit version is set (hashes the source style content, not the built output).
+- Emits `blocks-manifest.php` for `wp_register_block_types_from_metadata_collection` (WP 6.7+).
+
+**Options**
+
+| 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. |
+
+### `wpExternals(options)`
+
+→ [Full documentation](./docs/wp-externals.md)
+
+Decides which imports to externalize and emits `<entry>.asset.php` sidecars.
+
+For `@wordpress/*` packages, the decision reads each package's *own* `package.json`:
+
+- `wpScript: true` → classic script externalization (rewrites `import { foo } from '@wordpress/x'` to `const { foo } = window.wp.x` and lists `wp-x` as a dependency handle).
+- `wpScriptModuleExports` → Script Module externalization (preserves the ESM import for WP's import map; lists the specifier in the sidecar's `module_dependencies`).
+- Neither → bundle into the consumer's output (no special handling).
+
+The sidecar comes in two shapes, chosen per entry, because WordPress core and boot-page PHP want irreconcilable things from the `dependencies` key:
+
+- **Default (core-compatible):** module-mode `dependencies` stays the Script Module dependency list core reads, and the classic handles a module reads off `window.*` are added under a new `script_dependencies` key.
+- **`wpBuildAssetMatchers` entries** (wired automatically by `wp()` for `adminPagesDir`): the `@wordpress/build` shape — `dependencies` = classic handles, `module_dependencies` = `array( 'id' => …, 'import' => … )` entries, omitted when empty.
+
+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.
+
+**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`. |
+| `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). |
+
+### `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:
+
+```
+dist/modules/<page>/
+├── content.js          # ESM entry
+├── content.asset.php   # classic handles + module_dependencies + version
+├── content.css         # extracted CSS imported by content.js
+├── route.js            # ESM entry (optional per page)
+├── route.asset.php
+├── loader.js           # generated empty anchor module
+└── routes/<name>/      # additional routes, same files
+```
+
+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.
+
+**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. |
+
+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.
+
+### `wpBlockStyles(options)`
+
+→ [Full documentation](./docs/wp-block-styles.md)
+
+Every stylesheet under `blocksStylesDir` becomes a dedicated CSS entry under `dist/autoenqueue/<block-name>/<file>.css`. Lets PHP selectively enqueue per-block stylesheets without bundling.
+
+**Options**
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `blocksStylesDir` | `string` | (required) | Directory of per-block stylesheets. |
+
+### `wpCopyAssets(options)`
+
+→ [Full documentation](./docs/wp-copy-assets.md)
+
+Copies static assets (images, fonts, SVG) from `copyAssetsDir` to `dist/`, preserving the relative path. So `assets/images/logo.svg` → `dist/images/logo.svg`.
+
+**Options**
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `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). |
+
+### `wpScriptIife()`
+
+→ [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. No options.
+
+### `wpCleanCssChunks()`
+
+→ [Full documentation](./docs/wp-clean-css-chunks.md)
+
+Deletes the empty `.js` shim Vite emits next to a CSS-only entry. No options.
+
+## License
+
+GPL-2.0-or-later. See [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,231 @@
+import { Plugin } from 'vite';
+
+/**
+ * Enables generation of the `@wordpress/build`-style PHP layer next to the
+ * built modules — `build.php`, `constants.php`, `pages.php`,
+ * `pages/<slug>/page{,-wp-admin}.php`, `routes.php` and
+ * `routes/registry.php`. A consuming plugin then needs no hand-written PHP
+ * beyond `require_once __DIR__ . '/dist/build.php';`.
+ */
+interface WpAdminPagesPhpOptions {
+    /**
+     * Identifier prefix for every generated function, global and hook.
+     * Default: `wpPlugin.name` from the consumer's package.json, else its
+     * (de-scoped) package name. Dashes are underscored for PHP identifiers;
+     * the result must be a valid PHP identifier fragment.
+     */
+    prefix?: string;
+    /**
+     * Script Module id prefix — route modules are registered as
+     * `<handlePrefix>/routes/<page>/<route>/{content,route}`.
+     * Default: `wpPlugin.handlePrefix`, else `prefix`.
+     */
+    handlePrefix?: string;
+    /**
+     * Raw PHP expression for the URL of the build directory, interpolated
+     * into `constants.php` verbatim. Default `plugin_dir_url( __FILE__ )`
+     * (`build.php` and friends live in the build directory itself).
+     */
+    baseUrl?: string;
+    /** Text domain for the generated `__()` calls. Default `'default'`. */
+    textdomain?: string;
+}
+interface WpAdminPagesOptions {
+    /**
+     * Directory whose immediate subdirectories are pages. A subdirectory is
+     * a page when it contains a `content.{tsx,ts,jsx,js}` entry; a sibling
+     * `route.{tsx,ts,jsx,js}` is picked up when present, as are additional
+     * routes under `<page>/routes/<name>/`.
+     */
+    adminPagesDir: string;
+    /**
+     * Admin pages are Script Modules, so they only build in the module pass.
+     * In `'script'` mode (the default, matching the other plugins) this
+     * plugin contributes nothing.
+     */
+    buildType?: 'script' | 'module';
+    /**
+     * Generate the PHP registration layer. Presence enables it; every key
+     * is optional.
+     */
+    php?: WpAdminPagesPhpOptions;
+    /**
+     * Root whose `package.json` supplies the generated `version` and the
+     * `wpPlugin.name` / `wpPlugin.handlePrefix` defaults. Defaults to Vite's
+     * `root`, else `process.cwd()`.
+     */
+    projectRoot?: string;
+}
+declare function wpAdminPages(options: WpAdminPagesOptions): Plugin;
+
+interface WpBlocksOptions {
+    blocksDir: string;
+    buildType?: 'script' | 'module';
+    /**
+     * Emit `blocks-manifest.php` (returns one PHP array of all block.json
+     * contents). Lets PHP use `wp_register_block_types_from_metadata_collection`
+     * (WP 6.7+) instead of N filesystem reads + JSON parses on every request.
+     * Default: `true`.
+     */
+    emitManifest?: boolean;
+    /**
+     * Block directory names (relative to `blocksDir`) to skip entirely —
+     * neither discovered as entries nor included in the manifest.
+     */
+    skip?: string[];
+}
+declare function wpBlocks(options: WpBlocksOptions): Plugin;
+
+interface WpBlockStylesOptions {
+    blocksStylesDir: string;
+}
+declare function wpBlockStyles(options: WpBlockStylesOptions): Plugin;
+
+interface WpCopyAssetsOptions {
+    /** Source directory (default: `./assets`). */
+    copyAssetsDir: string;
+    /** Override the glob pattern (relative to `copyAssetsDir`). */
+    pattern?: string;
+    /** Only run during the script pass — module pass would emit duplicates. */
+    buildType?: 'script' | 'module';
+}
+declare function wpCopyAssets(options: WpCopyAssetsOptions): Plugin;
+
+interface ExternalNamespace {
+    /** Window global path, e.g. `wp` for `@wordpress/*`, `woo` for `@woo/*`. */
+    global: string;
+    /** Script-handle prefix used in `.asset.php`. `wp` → `wp-block-editor`. */
+    handlePrefix: string;
+}
+interface WpExternalsOptions {
+    /**
+     * Project root used to resolve `@wordpress/*` (and other) package.jsons.
+     * Defaults to `process.cwd()`. Pass the absolute project root for
+     * deterministic resolution in monorepos / weird CWDs.
+     */
+    projectRoot?: string;
+    /**
+     * Additional namespaces to externalize. The metadata-driven path covers
+     * `@wordpress/*` automatically; this lets you add `woo`, `acme`, etc.
+     * as classic-script externals (no metadata read — global/handle config
+     * only).
+     */
+    externalNamespaces?: Record<string, ExternalNamespace>;
+    /**
+     * Non-scoped vendor externals (`react`, `jquery`, etc.). These don't
+     * carry WP metadata so we keep the hardcoded mapping. Pass `{}` to
+     * disable.
+     */
+    additionalExternals?: Record<string, {
+        global: string;
+        handle: string | null;
+    }>;
+    /**
+     * 'script' (default) rewrites `import { x } from '@wordpress/y'` into
+     * `const { x } = window.wp.y;` so the resulting bundle works as a
+     * classic <script>. `.asset.php` lists `wp-y`-style handles for
+     * `wp_register_script`.
+     *
+     * 'module' leaves ESM imports of Script-Module-eligible packages intact
+     * (resolved at runtime by WP's import map) for use with
+     * `wp_register_script_module` — required for the Interactivity API and
+     * Script Modules generally. `.asset.php` lists those specifiers under
+     * `module_dependencies` and includes `'type' => 'module'`. Script-only
+     * packages (`wpScript`, vendor globals) have no module form, so they're
+     * still rewritten to their `window.*` global with the classic handle
+     * recorded in `dependencies`.
+     */
+    buildType?: 'script' | 'module';
+    /**
+     * Substring matchers for file paths that should *always* be treated as
+     * `module`-mode regardless of the plugin-level `buildType`. Lets a
+     * single Vite dev server (which can only run one global mode at a time)
+     * still serve Script Module entries with their ESM imports intact.
+     *
+     * Example: `['/view.ts', '/view-module.ts', '/view-module.js']`
+     */
+    moduleEntryMatchers?: string[];
+    /**
+     * Substring matchers for entry *source* paths (the entry chunk's
+     * `facadeModuleId`) whose `.asset.php` should use the
+     * `@wordpress/build` shape:
+     *
+     *   'dependencies'        => classic script handles
+     *   'module_dependencies' => array( 'id' => …, 'import' => 'static'|'dynamic' )
+     *
+     * Entries that don't match keep the shape WordPress core reads when it
+     * registers a Script Module from `block.json`
+     * (`register_block_script_module_id()` passes `dependencies` straight
+     * into `wp_register_script_module()`), so module specifiers stay in
+     * `dependencies` there.
+     *
+     * `wp()` wires this automatically for `adminPagesDir`. Set it yourself
+     * when composing plugins by hand.
+     *
+     * Example: `['/assets/js/admin-pages/']`
+     */
+    wpBuildAssetMatchers?: string[];
+    /**
+     * Plugin-local Script Module namespaces — exact names or `prefix-*` globs.
+     * Imports matching `@<ns>/<anything>` are externalized as Script Modules:
+     * the ESM import is preserved (no global rewrite) and the specifier is
+     * recorded in the `.asset.php` dependency list.
+     *
+     * Example: `['ignite-wp-navigation', 'ignite-*']`
+     */
+    scriptModuleNamespaces?: string[];
+}
+declare function wpExternals(options?: WpExternalsOptions): Plugin[];
+
+interface WpOptions {
+    /** Build mode for sub-plugins. Default: `'script'`. */
+    buildType?: 'script' | 'module';
+    blocksDir?: string;
+    blocksStylesDir?: string;
+    copyAssetsDir?: string;
+    adminPagesDir?: string;
+    /**
+     * Per-plugin escape hatches. Pass `false` to disable; pass an object
+     * to merge extra options into the sub-plugin. Nested wins on conflict.
+     */
+    blocks?: Partial<WpBlocksOptions> | false;
+    blockStyles?: Partial<WpBlockStylesOptions> | false;
+    copyAssets?: Partial<WpCopyAssetsOptions> | false;
+    adminPages?: Partial<WpAdminPagesOptions> | false;
+    externals?: WpExternalsOptions | false;
+    /** Disable the auto-included script-IIFE helper. Default: enabled in script mode. */
+    iife?: false;
+    /** Disable the auto-included CSS-only-chunk cleanup. Default: always enabled. */
+    cleanCssChunks?: false;
+}
+declare function wp(options?: WpOptions): Plugin[];
+
+/**
+ * vite-plugin-wp-script-iife
+ *
+ * Wraps each script-mode entry chunk in an IIFE post-write — esbuild/oxc's
+ * minifier would otherwise inline a plain intro/outro IIFE for var-heavy
+ * bodies, defeating the global-scope isolation needed when WP enqueues
+ * these as classic <script> tags.
+ *
+ * Only run this in script mode. Module-mode entries (`wp_register_script_module`)
+ * must stay as bare ESM for WP's import map to resolve them at runtime.
+ */
+
+declare function wpScriptIife(): Plugin;
+
+/**
+ * vite-plugin-wp-clean-css-chunks
+ *
+ * Deletes the empty `.js` shim Vite leaves next to a CSS-only entry.
+ *
+ * Vite's Rollup-driven model treats every entry as a JS module that may
+ * pull in CSS via side-effect imports. For an entry whose source IS a CSS
+ * file (e.g. each per-block stylesheet produced by wpBlockStyles), Vite
+ * still emits a tiny empty `.js` chunk that just imports the `.css`.
+ * Useless for WP enqueueing.
+ */
+
+declare function wpCleanCssChunks(): Plugin;
+
+export { type ExternalNamespace, type WpAdminPagesOptions, type WpAdminPagesPhpOptions, type WpBlockStylesOptions, type WpBlocksOptions, type WpCopyAssetsOptions, type WpExternalsOptions, type WpOptions, wp, wpAdminPages, wpBlockStyles, wpBlocks, wpCleanCssChunks, wpCopyAssets, wpExternals, wpScriptIife };