Boltdocs Logo
GuidesIntegrationsAPIPluginsComponents
  1. Home
  2. ChevronRightPlugin API Reference
  3. ChevronRightPlugin API Reference

Plugin API Reference

Complete reference for the Boltdocs Plugin API — PluginContext, caches, diagnostics, path resolution, and virtual modules. Covers every field and method exposed to plugin lifecycle hooks.

The PluginContext object passed to every lifecycle hook carries seven enriched namespaces that give plugins safe, typed access to the core's internal machinery: caches, diagnostics, paths, virtual modules, middleware, server, and hmr.

This section is the official API reference. Read it alongside the Plugin System overview for the architecture and examples.

Each namespace has its own dedicated page — use the sidebar or the cards below to navigate.

PluginContext

Base context object passed to every lifecycle hook.

Caches

Transform, routes, and memory caches.

Diagnostics

Structured diagnostic reporting.

Paths

Safe workspace path resolution.

Virtual Modules

Runtime virtual module declarations.

Middleware

Transform middleware pipeline.

Server

HTTP middleware & server lifecycle.

HMR

Dev-server file watching & custom events.

Lifecycle Hooks

Build/dev hooks, transform chains, and chain signals.

PluginContextLink

Every lifecycle hook receives a PluginContext as its first argument:

interface PluginContext {
  readonly config: BoltdocsConfig      // Read-only resolved config
  readonly logger: PluginLogger        // info / warn / error / debug
  readonly store: PluginStore          // Namespaced key-value store
  readonly meta: PluginMeta            // Current plugin identity
  readonly docsDir: string             // Absolute path to docs/
  readonly rootDir: string             // Absolute path to project root
  readonly outDir: string              // Build output (e.g. 'dist/')
  readonly routes: RouteMeta[]         // All generated routes

  // --- Enriched in 3.2.0 ---
  readonly caches: PluginCachesAPI         // Transform, routes, memory
  readonly diagnostics: PluginDiagnosticsAPI
  readonly paths: PluginPathsAPI
  readonly virtualModules: PluginVirtualModulesAPI
  readonly middleware: PluginMiddlewareAPI  // Register transform middleware
  readonly server: PluginServerAPI         // Register HTTP middleware
  readonly hmr: PluginHmrAPI               // Hook into HMR events
}

Base fieldsLink

FieldTypeDescription
configBoltdocsConfigRead-only resolved configuration object.
loggerPluginLoggerStructured logging — info(), warn(), error(), debug().
storePluginStoreNamespaced key-value store for inter-plugin communication.
metaPluginMetaCurrent plugin identity (name, version, boltdocsVersion).
docsDirstringAbsolute path to the docs/ directory.
rootDirstringAbsolute path to the project root.
outDirstringBuild output directory (e.g. dist/).
routesRouteMeta[]All generated documentation routes.

Enriched namespaces (3.2.0+)Link

FieldPageDescription
cachesCachesTransform cache, routes cache, and in-memory FIFO cache.
diagnosticsDiagnosticsStructured diagnostic channel with severity levels.
pathsPathsSafe path resolution inside the workspace boundary.
virtualModulesVirtual ModulesDeclare virtual modules for Vite resolution.
middlewareMiddlewareRegister transform middleware at runtime.
serverServerRegister HTTP middleware and lifecycle callbacks.
hmrHMRHook into dev-server file watching and send custom events.

Putting it all togetherLink

A real-world plugin that caches an expensive transform, reports progress, resolves a path, and registers a virtual module:

import { createPlugin } from 'boltdocs'

export default createPlugin({
  name: 'my-smart-plugin',
  hooks: {
    async beforeBuild(ctx) {
      // Register a virtual module for runtime
      ctx.virtualModules.add('virtual:my-smart-plugin/config', () =>
        JSON.stringify({ mode: 'production' }),
      )
    },
    async transformMdx(ctx, { code, filePath }) {
      const cache = ctx.caches.memory<string>('my-smart-plugin', { max: 200 })

      const cached = cache.get(filePath)
      if (cached) return { code: cached }

      ctx.diagnostics.report('info', 'TRANSFORM_START', `Transforming ${filePath}`)

      const transformed = code.replace(/foo/g, 'bar')

      cache.set(filePath, transformed)
      return { code: transformed }
    },
    afterBuild(ctx) {
      const diagPath = ctx.paths.resolveDocs('diagnostics.json')
      ctx.logger.info(`Diagnostics snapshot at: ${diagPath}`)
    },
  },
})

See alsoLink

Last updated on July 27, 2026

Was this page helpful?