Referencia de la API de Plugins
Referencia completa de la API de Plugins de Boltdocs — PluginContext, caches, diagnostics, resolución de rutas y módulos virtuales. Cubre todos los campos y métodos expuestos a los hooks del lifecycle.
El objeto PluginContext que recibe cada hook del lifecycle incluye
siete namespaces enriquecidos que otorgan a los plugins acceso seguro
y tipado a la maquinaria interna del core: caches, diagnostics,
paths, virtual modules, middleware, server
y hmr.
Esta sección es la referencia oficial de la API. Léela junto con la descripción general del Sistema de Plugins para conocer la arquitectura y ejemplos.
Cada namespace tiene su propia página — usa el sidebar o las tarjetas a continuación para navegar.
PluginContext
Objeto de contexto base pasado a cada hook del lifecycle.
Caches
Cachés de transformación, rutas y memoria.
Diagnostics
Reporte estructurado de diagnósticos.
Paths
Resolución segura de rutas en el workspace.
Virtual Modules
Declaraciones de módulos virtuales en runtime.
Middleware
Pipeline de middleware de transformación.
Server
Middleware HTTP y ciclo de vida del servidor.
HMR
Observación de archivos y eventos HMR personalizados.
Lifecycle Hooks
Hooks de build/dev, cadenas de transformación y señales.
PluginContext
Cada hook del lifecycle recibe un PluginContext como primer argumento:
interface PluginContext {
readonly config: BoltdocsConfig
readonly logger: PluginLogger
readonly store: PluginStore
readonly meta: PluginMeta
readonly docsDir: string
readonly rootDir: string
readonly outDir: string
readonly routes: RouteMeta[]
// --- Nuevo en 3.2.0 ---
readonly caches: PluginCachesAPI
readonly diagnostics: PluginDiagnosticsAPI
readonly paths: PluginPathsAPI
readonly virtualModules: PluginVirtualModulesAPI
readonly middleware: PluginMiddlewareAPI // Registrar middleware transform
readonly server: PluginServerAPI // Registrar middleware HTTP
readonly hmr: PluginHmrAPI // Hooks de HMR
}
Campos base
| Campo | Tipo | Descripción |
|---|---|---|
config | BoltdocsConfig | Objeto de configuración resuelto y de solo lectura. |
logger | PluginLogger | Logging estructurado — info(), warn(), error(), debug(). |
store | PluginStore | Almacén clave-valor con namespace para comunicación entre plugins. |
meta | PluginMeta | Identidad del plugin actual (name, version, boltdocsVersion). |
docsDir | string | Ruta absoluta al directorio docs/. |
rootDir | string | Ruta absoluta a la raíz del proyecto. |
outDir | string | Directorio de salida del build (ej. dist/). |
routes | RouteMeta[] | Todas las rutas de documentación generadas. |
Namespaces enriquecidos (3.2.0+)
| Campo | Página | Descripción |
|---|---|---|
caches | Caches | Caché de transformación, rutas y FIFO en memoria. |
diagnostics | Diagnostics | Canal de diagnóstico estructurado con niveles de severidad. |
paths | Paths | Resolución segura de rutas dentro del workspace. |
virtualModules | Virtual Modules | Declara módulos virtuales para resolución por Vite. |
middleware | Middleware | Registra middleware de transformación en runtime. |
server | Server | Registra middleware HTTP y callbacks del ciclo de vida. |
hmr | HMR | Conéctate al file-watching del dev server y envía eventos. |
Ejemplo completo
Un plugin real que cachea una transformación costosa, reporta progreso, resuelve una ruta y registra un módulo virtual:
import { createPlugin } from 'boltdocs'
export default createPlugin({
name: 'mi-plugin-inteligente',
hooks: {
async beforeBuild(ctx) {
ctx.virtualModules.add('virtual:mi-plugin/config', () =>
JSON.stringify({ mode: 'production' }),
)
},
async transformMdx(ctx, { code, filePath }) {
const cache = ctx.caches.memory<string>('mi-plugin', { max: 200 })
const cached = cache.get(filePath)
if (cached) return { code: cached }
ctx.diagnostics.report('info', 'TRANSFORM_START', `Transformando ${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(`Snapshot de diagnósticos en: ${diagPath}`)
},
},
})
Ver también
- Descripción general del Sistema de Plugins — arquitectura, conceptos, inicio rápido
- @bdocs/unist-utils — Utilidades AST para remark/rehype
- Boltdocs 3.2.0 changelog — notas de la versión