Programmatic API

Autodocs exports its core functions for use as a library. Install it as a dependency:

npm install @cueframe/autodocs

import { init, generate, dev, build, deploy, loadConfig } from '@cueframe/autodocs';

All exports are ESM-only ("type": "module" in package.json). TypeScript types are included.

init(cwd)

Initializes a project directory for autodocs. Creates autodocs.config.json, docs/index.mdx, and docs/meta.json. Adds .autodocs/ to .gitignore.

import { init } from '@cueframe/autodocs';

await init(process.cwd());

Behavior:

• Checks that Node.js >= 18 is installed
• Scans PATH for claude, codex, and gemini — throws if none are found
• Skips creating files that already exist (config, docs/index.mdx, docs/meta.json)
• Suggests installing tree if not found (optional, improves codebase exploration)

Parameters:

Throws if no AI CLI is found or Node.js version is below 18.

generate(options?)

Generates documentation by invoking an AI CLI to read source code and write MDX files.

import { generate } from '@cueframe/autodocs';

// Default: incremental generation using the auto-detected CLI
await generate();

// Force regeneration with a specific CLI
await generate({
  force: true,
  cli: 'claude',
  cwd: '/path/to/project',
});

Pipeline:

1. Loads config from autodocs.config.json
2. Hashes all source files (SHA-256, 16 hex chars) and compares to .autodocs/cache/source-cache.json
3. If no files changed and force is false, returns early
4. Builds a prompt from the skill file, config, existing docs context, and change context
5. Spawns cli-agents with JSON streaming and displays real-time progress via ora
6. On success, caches new file hashes

GenerateOptions

interface GenerateOptions {
  force?: boolean;  // Regenerate all docs, ignoring the hash cache
  cli?: string;     // AI CLI to use: "claude", "codex", or "gemini"
  cwd?: string;     // Project root directory (default: process.cwd())
}

Throws if config is missing, cli-agents binary is not found, or the subprocess fails.

dev(cwd?)

Starts a local Fumadocs dev server at http://localhost:3000. Scaffolds the Fumadocs app in .autodocs/ and runs next dev.

import { dev } from '@cueframe/autodocs';

await dev(process.cwd());

Note: This function calls process.exit() when the dev server stops, using the server's exit code.

Parameters:

build(cwd?)

Builds the documentation site for production deployment. Scaffolds the Fumadocs app and runs next build.

import { build } from '@cueframe/autodocs';

await build(process.cwd());

The build output is placed in .autodocs/.next/.

Parameters:

Throws if the Next.js build fails.

deploy(options?)

Builds the docs site and deploys it to Vercel. Runs a full build first, then handles Vercel linking and deployment.

import { deploy } from '@cueframe/autodocs';

// Production deploy (default)
await deploy({ cwd: process.cwd() });

// Preview deploy
await deploy({ cwd: process.cwd(), prod: false });

Behavior:

1. Calls build(cwd) to scaffold and build the Next.js site
2. If no .vercel/ directory exists in the project root, runs vercel link --yes to connect to a Vercel project
3. Copies the .vercel/ config from the project root into .autodocs/.vercel/
4. Runs vercel deploy --prod --yes (or without --prod for preview deploys)

DeployOptions

interface DeployOptions {
  cwd?: string;   // Project root directory (default: process.cwd())
  prod?: boolean;  // Deploy as production (default: true)
}

Throws if the build fails, Vercel linking fails, or the deployment fails.

Prerequisites: Requires the Vercel CLI (npm install -g vercel) and an authenticated session (vercel login).

loadConfig(cwd)

Loads and validates autodocs.config.json from the given directory. Returns the merged config with defaults applied.

import { loadConfig } from '@cueframe/autodocs';

const config = loadConfig(process.cwd());
console.log(config.output);  // "docs"
console.log(config.theme);   // "black"

Validation performed:

• Checks that the config file exists
• Parses JSON (throws on invalid JSON with a helpful message)
• Validates all glob patterns in include and exclude using picomatch
• Validates that theme is one of the 11 allowed values

Throws if the config file is missing, JSON is invalid, globs are malformed, or the theme is unrecognized.

AutodocsConfig

interface AutodocsConfig {
  output: string;        // Default: "docs"
  include: string[];     // Default: ["src/**"]
  exclude: string[];     // Default: ["**/test*", "**/bench*", "**/target/**", "**/node_modules/**", "**/dist/**"]
  theme: Theme;          // Default: "black"
  title?: string;        // Default: "Documentation"
  github?: {
    user: string;
    repo: string;
    branch?: string;     // Default: "main"
  };
  sections?: string[];   // Default: ["guide", "api"]
  instructions?: string;
}

VALID_THEMES

Array of the 11 valid theme names:

import { VALID_THEMES } from '@cueframe/autodocs';

// ['black', 'neutral', 'vitepress', 'dusk', 'catppuccin',
//  'ocean', 'purple', 'solar', 'emerald', 'ruby', 'aspen']

Theme

Type alias for valid theme strings:

import type { Theme } from '@cueframe/autodocs';

const theme: Theme = 'ocean';

Helper functions

These are also exported but are primarily for internal use: