Reference
Architecture
How doctreen is put together — RouteRegistry, adapter flow, zero-runtime-deps UI.
DocTreen is a framework-agnostic API documentation library built on a middleware-injection pattern.
Core components
RouteRegistry— framework-agnostic route store. Adapters populate it; the UI reads from it.normalizeConfig— normalises the user's config object;enableddefaults toNODE_ENV !== 'production'.shouldExclude— filter for theexcludelist (strings + RegExp).*and/*are excluded by default.
Adapter contract
Every adapter follows the same four steps:
- Take the framework instance
- Discover routes (eager or lazy)
- Call
registry.add(routeEntry) - Serve the UI at
docsPath(default/docs)
Zero runtime dependencies in the UI
The docs UI is shipped as inline HTML / CSS / JS strings. No CDN, no extra package. The Postman and OpenAPI export buttons run as in-browser IIFEs.
This is why a single npm install doctreen is enough — no companion @nestjs/swagger-style ecosystem.
Lazy vs eager discovery
| Adapter | Mode | When routes are read |
|---|---|---|
| Express | Lazy | app._router.stack (v4) / app.router.stack (v5) on the first /docs hit. Solves the "middleware-before-routes" ordering problem. |
| Fastify | Eager | Via the onRoute hook at registration time. Adapter must be installed before routes. |
| Hono | Lazy | app.routes on the first docs request. |
| Koa | Lazy | router.stack on the first docs request. |
| NestJS | Eager | app.container.getModules() for metadata discovery, called before app.listen(). |
Schema priority order
- Explicit schema via
defineRoute<T>(...)/@DocRoute({ ... }) - Framework-native schema (Fastify JSON Schema; nothing for the others)
- JSDoc parsing (Express / Hono / Koa)
The same priority feeds the docs UI, the OpenAPI export, and the schema drift comparator.