@vetwo/docs-builder

The framework-agnostic core of the @vetwo/docs-* ecosystem: project & package discovery, typed configuration loading, a plugin & lifecycle-hook system, content-hash based incremental generation, and a small Markdown template engine.

This package contains zero framework-specific code. Next.js output comes from @vetwo/docs-next, Fumadocs output from @vetwo/docs-fumadocs, API extraction from @vetwo/docs-typedoc, and Turborepo task wiring from @vetwo/docs-turbo — each of those is a plugin built on top of the API documented below.

Install

npm install @vetwo/docs-builder
pnpm add @vetwo/docs-builder
bun add @vetwo/docs-builder

Quick start

Create docs.config.ts at your project root:

import { defineConfig } from "@vetwo/docs-builder";

export default defineConfig({
  site: { name: "My Project", url: "https://example.com" },
  outDir: "docs-dist",
});

Run the pipeline:

import { createDocsBuilder } from "@vetwo/docs-builder";

const builder = createDocsBuilder({
  plugins: [
    /* e.g. typedocPlugin(), nextPlugin(), fumadocsPlugin() from the integration packages */
  ],
});

const result = await builder.build({
  cwd: process.cwd(),
  outDir: "docs-dist",
  incremental: true,
  clean: false,
});

console.log(`Wrote ${result.written.length} files, discovered ${result.discovery.packages.length} packages`);

@vetwo/docs-cli wraps this in docs build / docs dev / docs generate commands, so most users never call this API directly — but it's the stable surface every integration and the CLI itself is built on.

How discovery works

ProjectDiscovery looks for, in order: turbo.json (Turborepo), nx.json (Nx), pnpm-workspace.yaml, then package.json#workspaces (npm/Yarn), then a Bun lockfile, falling back to standalone. Whatever workspace globs it finds (defaulting to packages/*, apps/*, libs/* for Turborepo/Nx) are resolved to every package.json beneath them, recursively, excluding node_modules, dist, .turbo, and .next. Adding a new package to your repo requires no configuration change — it is picked up on the next run.

Writing a plugin

import type { DocsPlugin } from "@vetwo/docs-builder";

export function myPlugin(): DocsPlugin {
  return {
    name: "my-plugin",
    hooks: {
      afterDiscover(context) {
        context.logger.info(`saw ${context.discovery.packages.length} packages`);
      },
      afterGenerate(context) {
        for (const pkg of context.discovery.packages) {
          context.files.push({
            relativePath: `packages/${pkg.name}.md`,
            contents: `# ${pkg.name}\n`,
            producedBy: "my-plugin",
          });
        }
      },
    },
  };
}

Hooks fire in this order for every build() call:

beforeDiscover -> afterDiscover
beforeGenerate -> afterGenerate
beforeBuild    -> afterBuild
beforeWrite    -> afterWrite

Plugins registered together run in registration order for each hook, so a later plugin can rely on an earlier plugin having already pushed its files or populated context.shared for that same hook.

Incremental generation

Every GeneratedFile is hashed (SHA-256) and compared against .docs-cache/cache.json. When incremental: true, unchanged files are skipped entirely — this is what keeps hundreds-of-packages monorepos fast. Pass clean: true to wipe outDir before writing (useful for docs build in CI).

API reference

| Export | Purpose | | --- | --- | | createDocsBuilder(options) | Construct a DocsBuilder with plugins/logger options. | | DocsBuilder#build(options) | Run the full pipeline, return a BuildResult. | | DocsBuilder#use(plugin) | Register an additional plugin. | | defineConfig(config) | Identity helper for authoring docs.config.ts with types. | | docsConfigSchema | The Zod schema backing DocsConfig. | | ProjectDiscovery | Standalone discovery runner ({ root, kind, packages, workspaceGlobs }). | | PluginManager / HookBus | Lower-level plugin registration/execution primitives. | | FileCache / FileWriter | Incremental cache and disk-writing primitives. | | TemplateEngine | {{placeholder}} interpolation + YAML frontmatter helper. | | Logger / Diagnostics | Leveled logging and non-fatal diagnostics collection. |

See src/index.ts for the exhaustive list of exported types and errors (DiscoveryError, ConfigError, PluginError, GenerationError, all extending DocsBuilderError).

License

MIT © vetwo

Docs_Builder