handoff-docgen

handoff-docgen is a Node.js + TypeScript package for generating React component documentation with:

• baseline metadata from react-docgen-typescript
• deep recursive type mapping via TypeScript Compiler API
• deterministic JSON output for CI and downstream tooling

Install

npm install handoff-docgen

CLI Usage

handoff-docgen --dir ./src/components --out ./dist/docs.generated.json --tsconfig ./tsconfig.json

Options:

• --dir directory to scan for .tsx components
• --out output JSON file path
• --tsconfig tsconfig used by both docgen and deep mapper
• --max-depth recursion depth cap (default 7)
• --path-mode output path mode: relative (default) or absolute
• --project-root base path used for relative path mode (defaults to tsconfig directory)
• --exclude-dir directory name to skip during scanning (repeatable)

Programmatic Usage

import { createGenerator, generateDocs } from "handoff-docgen";

// One-off generation
const docs = await generateDocs({
  componentDirectory: "./src/components",
  tsconfigPath: "./tsconfig.json",
  maxDepth: 7,
  pathMode: "relative",
  excludeDirectories: ["dist", "build"]
});

// Reusable generator instance (great for repeated runs)
const generator = createGenerator({
  componentDirectory: "./src/components",
  tsconfigPath: "./tsconfig.json",
  maxDepth: 7
});

const nextDocs = await generator.generate();
const docsForAnotherDir = await generator.generate({
  componentDirectory: "./src/marketing-components"
});

handoff-docgen intentionally focuses on generation, not storage. Persist to disk (JSON, DB, API) in your host app/CLI based on your pipeline needs.

Example custom file persistence in host app:

import { mkdir, writeFile } from "node:fs/promises";
import path from "node:path";
import { generateDocs } from "handoff-docgen";

const docs = await generateDocs({
  componentDirectory: "./src/components",
  tsconfigPath: "./tsconfig.json"
});

const out = path.resolve("./dist/docs.generated.json");
await mkdir(path.dirname(out), { recursive: true });
await writeFile(out, JSON.stringify(docs, null, 2), "utf8");

Module Support

handoff-docgen supports both ESM and CommonJS consumers.

ESM:

import { generateDocs } from "handoff-docgen";

CommonJS:

const { generateDocs } = require("handoff-docgen");

If your TypeScript project compiles with "module": "commonjs", the CommonJS require form is supported.

Output Highlights

Each prop includes:

• docgen baseline (docgenType, required, defaultValue, description)
• deep mapping (deepType, typeRefs, warnings)
• parsed JSDoc annotations (annotations)

Deep mapper handles:

• interfaces/type aliases
• unions/intersections
• arrays/sets/maps/records
• enums/literals
• cycle detection and depth truncation

Build & Typecheck

npm run build
npm run typecheck
npm run test:consumers

API Surface

• generateDocs(options) - one-off generation, returns GeneratedDocs
• createGenerator(options) - returns reusable generator with generate(overrides?)
• CLI handoff-docgen - generate + write JSON file for shell workflows