# Bundler Matrix Verification

> How to verify @inkline/plugin and @inkline/cli changes across the 6 bundler adapters and the two compile paths, including watch-mode scenarios and error-path checks. Use for any core/plugin or tooling/cli change and for QA of tooling claims.

- Skill: `inkline/bundler-matrix-verification` (Agent Skill)
- Install (CLI): `npx skillmds@latest add inkline/bundler-matrix-verification`
- Raw SKILL.md: https://api.skillmd.com/api/skills/inkline/bundler-matrix-verification/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: inkline (https://skillmd.com/u/inkline)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/inkline/bundler-matrix-verification

---


# Bundler matrix verification

## The matrix

`@inkline/plugin` is one unplugin factory with **6 adapters**: `vite`, `webpack`, `rollup`, `esbuild`, `rspack`, `farm` — consumed as `@inkline/plugin/<bundler>` (or `inkline/plugin/<bundler>` via the barrel). All bundler peer deps are optional; consumers install only theirs. The factory registers a single transform matching `*.ink.tsx` that runs `compileIncremental` from `@inkline/compiler`.

Plugin options (`InklinePluginOptions`): `target` (**required**, no auto-detection — `undefined` is a build-time error), `sourceMap`, `config` (inline partial config; the plugin does **not** load `inkline.config.ts` — pair with `@inkline/config-loader`). It builds with **unbuild**, not `vp pack` — exports-map changes touch both `package.json` and consumer tsconfigs.

**Reality check: the plugin has ZERO direct tests today.** Its coverage rides the compiler fixture suite (same compile path) and repo consumers. Any plugin change should leave tests behind; building the matrix harness is a standing mission.

## "Works in Vite" is not done

| Change class                                     | Minimum verification                                                                   |
| ------------------------------------------------ | -------------------------------------------------------------------------------------- |
| Factory core (transform wiring, filter, options) | Vite + webpack + one of Rollup/Rspack, fresh app builds per target                     |
| Incremental/cache behavior                       | Repeated builds + file edits; confirm `compileIncremental` reuses state, output stable |
| Source-map flag                                  | V3 map emitted/omitted per flag; mappings hit the `.ink.tsx` source                    |
| Adapter-specific subpath                         | That adapter + Vite as control                                                         |
| CLI compile / barrels / story generation         | `pnpm --filter @inkline/components build` + inspect `ui/*/.inkline/` + generated CSF   |
| `inkline init` / `add`                           | Fresh temp dir AND a messy existing project; re-run must be idempotent                 |

## The two paths (test the right one)

- **CLI path** — `inkline compile 'src/**/*.ink.tsx' --config inkline.config.ts`: config-loader → glob → compile per target → write `targetOutDir` (`.inkline/`) → barrels (`index`/`headless`/`stories` per config `barrels`) → story CSF via `@inkline/storybook/generator`. `--watch` recompiles on change; `--no-clean` preserves outputs; `--src-dir` controls path preservation; `--target` filters targets.
- **Plugin path** — bundler transform, in-memory, one target, no barrels/stories/config file.

Divergence is by design; a bug report must say which path. `inkline check` re-exposes compiler diagnostics without writing output — the cheap first probe.

## Error paths (must stay loud and typed)

- Missing `target` on the plugin → clear build-time error, not a silent no-op.
- Compiler diagnostics must surface through the bundler with file/loc (a swallowed INK error is a p1).
- CLI: unknown glob → helpful message; diagnostics formatted TTY-aware (`lib/diagnostics.ts`); writes atomic with source-map sidecars (`lib/writer.ts`).
- Config discovery is deliberately narrow: `inkline.config.{ts,js,mjs}` only — no rc files, no package.json field, no dotenv (`core/config-loader` disables them). Widening discovery is a decision, not a patch.

## Harnesses & consumers

- Compiler-side: `@inkline/compiler/testing` + `@inkline/test-utils` (compile/mount/conformance) — plugin transforms should get colocated tests that call the factory's transform directly.
- Live consumers that double as smoke tests: `ui/components` build (CLI path), per-framework Storybooks (consume `.inkline/` output), the e2e visual-parity suite.
- Remember stale dist: `vp pack` in `core/compiler` before verifying CLI/plugin behavior after compiler edits.
- Watch-mode scenarios once plugin HMR lands (v1 frontier): edit component → only affected module recompiles; edit `inkline.config.ts` → full reload; introduce a diagnostic then fix → dev server survives with correct output. Design tests for these now; don't let HMR ship untested.