| name | bundler-matrix-verification |
| description | 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. |
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.
