Diagnostics
PluginDiagnosticsAPI — structured diagnostic channel for Boltdocs plugins with severity levels, FIFO queue, and machine-readable codes.
ctx.diagnostics — PluginDiagnosticsAPI
Structured diagnostics channel. Plugins push records instead of spamming
the logger; downstream tools (dev-server overlay, CI reporters, IDE
plugins) drain the queue via list().
ts
type DiagnosticSeverity = 'info' | 'warn' | 'error'
// Report a diagnostic
ctx.diagnostics.report(
'warn',
'MY_PLUGIN_SLOW_TRANSFORM',
'Transformation took 3.2s — consider caching the result',
{ filePath: '/abs/path/to/page.mdx' },
)
// Read all pending diagnostics (snapshot, not a live stream)
const allDiagnostics: readonly DiagnosticRecord[] = ctx.diagnostics.list()
// Clear the queue
ctx.diagnostics.clear()
See also
- PluginContext — base context object
- Caches — transform, routes, and memory caches
- Server — HTTP middleware & server lifecycle
- Lifecycle Hooks — build/dev hooks, transform chains, and chain signals
Last updated on October 18, 2026
