react-docs-ai

Enterprise-grade AI-powered frontend documentation and release intelligence platform for React projects.

Table of Contents

• What It Does
• How It Works
• Prerequisites
• Installation
• Step 1 — Configure Your AI Provider
  • Option A: AiDE (Enterprise Internal)
  • Option B: OpenAI
  • Option C: Azure OpenAI
  • Option D: Custom / Proprietary Provider
  • Option E: Ollama (Local LLMs)
• Step 2 — Add to Your Project
• CLI Commands
  • generate
  • watch
  • release
• Registering Providers Dynamically
• Using the Programmatic API
• Environment Variable Reference
• Output Structure
• CI/CD Integration
  • GitHub Actions
  • GitLab CI
  • Azure DevOps
• What Gets Generated
• Architecture Overview
• Troubleshooting

What It Does

react-docs-ai automatically:

• Analyzes React/TypeScript components using TypeScript AST (ts-morph)
• Infers props, hooks, state, API calls, routing, forms, workflows, and accessibility patterns
• Generates enterprise-grade markdown documentation via your AI provider (AiDE, OpenAI, etc.)
• Watches files for changes and regenerates docs on save
• Produces release notes, QA test scenarios, and changelogs from git history
• Detects accessibility issues and performance anti-patterns statically
• Integrates into CI/CD pipelines (GitHub Actions, GitLab CI, Azure DevOps)

How It Works

React Component File
        ↓
  ComponentAnalyzer (ts-morph AST)
        ↓
  ComponentMetadata (props, hooks, API calls, workflows, a11y...)
  ↓
  PromptBuilder + Rules Engine (JSON rules injected)
    ↓
  AI Provider (AiDE / OpenAI / Custom)
        ↓
  MarkdownGenerator → FileWriter
        ↓
  docs/ComponentName.md
  workflow/ComponentName.workflow.md

Prerequisites

• Node.js >= 18.0.0
• npm >= 9.0.0
• An AI provider (AiDE API key or OpenAI API key)

Installation

In your existing React project

npm install react-docs-ai --save-dev

As a standalone tool (global)

npm install -g react-docs-ai

Clone and run from source

git clone https://github.com/enterprise/react-docs-ai.git
cd react-docs-ai
npm install
npm run build

Step 1 — Configure Your AI Provider

Copy the environment template into your project root:

cp node_modules/react-docs-ai/.env.example .env
# or if cloned from source:
cp .env.example .env

Then fill in your provider credentials. Only one provider needs to be configured.

Option A: AiDE (Enterprise Internal)

AiDE is the default and primary provider. Use this if your organization has an internal AiDE deployment.

# .env

AI_PROVIDER=aide

AIDE_API_URL=https://aide.internal.yourcompany.com/api/v1
AIDE_API_KEY=your-aide-api-key-here
AIDE_MODEL=aide-default          # Model name configured by your AI team
AIDE_TIMEOUT_MS=30000   # Request timeout (default: 30s)
AIDE_MAX_TOKENS=8192             # Max tokens per request
AIDE_TEMPERATURE=0.2          # Lower = more deterministic output

AiDE API contract expected by this tool:

| Endpoint | Method | Description | |----------|--------|-------------| | /generate | POST | Generate content from a prompt | | /health | GET | Health check (returns { "status": "ok" }) |

If your AiDE deployment uses different endpoint paths, update AIDE_API_URL to point to the correct base path.

AiDE requires custom headers? Use the customHeaders option when registering programmatically — see Registering Providers Dynamically.

Option B: OpenAI

# .env

AI_PROVIDER=openai

OPENAI_API_KEY=sk-your-openai-key-here
OPENAI_MODEL=gpt-4o              # Recommended for code analysis
OPENAI_MAX_TOKENS=8192
OPENAI_TEMPERATURE=0.2

Option C: Azure OpenAI

Azure OpenAI uses the OpenAI provider with a custom base URL:

# .env

AI_PROVIDER=openai

OPENAI_API_KEY=your-azure-api-key
OPENAI_BASE_URL=https://YOUR_RESOURCE.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT/
OPENAI_MODEL=gpt-4o
AZURE_OPENAI_DEPLOYMENT=your-deployment-name
AZURE_OPENAI_API_VERSION=2024-02-15-preview

Option D: Custom / Proprietary Provider

If your organization uses a proprietary LLM not listed above, implement a custom provider and register it programmatically before running any commands. See Registering Providers Dynamically below.

Option E: Ollama (Local LLMs)

Run documentation generation completely offline with no API key required. Ollama serves local LLMs (llama3.2, codellama, mistral, deepseek-coder, etc.) via a local REST API.

Setup (one time):

# 1. Install Ollama from https://ollama.com
# 2. Pull a model
ollama pull llama3.2   # Fast, good quality (recommended)
# or
ollama pull codellama  # Code-optimised
# or
ollama pull mistral           # Strong reasoning

Configure .env:

AI_PROVIDER=ollama

OLLAMA_BASE_URL=http://localhost:11434   # Default Ollama address
OLLAMA_MODEL=llama3.2        # Must match a pulled model
OLLAMA_TIMEOUT_MS=120000           # Generous — first request loads the model
OLLAMA_MAX_TOKENS=4096
OLLAMA_TEMPERATURE=0.2
OLLAMA_KEEP_ALIVE=5m # Keep model hot between requests

Start Ollama (if not running as a service):

ollama serve

Verify:

curl http://localhost:11434/api/tags
# Should list your pulled models

Note: First-run latency can be 10–60s while the model loads into memory. Subsequent requests are fast. Use OLLAMA_KEEP_ALIVE=-1 to keep the model loaded permanently during a session.

Remote Ollama: If Ollama runs on a remote machine or in Docker, set OLLAMA_BASE_URL to its address:

OLLAMA_BASE_URL=http://192.168.1.50:11434
# or
OLLAMA_BASE_URL=http://ollama-service:11434

Step 2 — Add to Your Project

Add these scripts to your project's package.json:

{
  "scripts": {
    "docs:generate": "react-docs-ai generate src/",
    "docs:watch":    "react-docs-ai watch src/",
    "docs:release":  "react-docs-ai release"
}
}

Then run:

# Generate docs for all components in src/
npm run docs:generate

# Watch mode — auto-regenerate docs when files change
npm run docs:watch

# Generate release notes from git history before a release
npm run docs:release

CLI Commands

generate

Analyze and generate documentation for one or more React components.

# Single component file
npx react-docs-ai generate src/components/Button.tsx

# Entire directory (recursively finds all .ts/.tsx/.js/.jsx)
npx react-docs-ai generate src/components/

# From project root — scans src/ by default
npx react-docs-ai generate

# With explicit options
npx react-docs-ai generate src/ \
  --output ./docs \
  --provider openai \
  --platform "My App Platform" \
  --no-workflow \
  --no-ai \
  --verbose

Options:

| Flag | Default | Description | |------|---------|-------------| | --output, -o | ./docs | Output directory for generated docs | | --provider | $AI_PROVIDER env | Override AI provider for this run (aide, openai) | | --platform | $PLATFORM_NAME env | Platform name shown in doc headers | | --no-workflow | — | Skip workflow diagram generation | | --no-ai | — | Run static analysis only, skip AI generation | | --verbose, -v | — | Show detailed analysis output |

Output per component:

• docs/{ComponentName}.md — Full component README
• workflow/{ComponentName}.workflow.md — Workflow diagrams and narratives

watch

Watch mode — automatically regenerates docs when files change.

# Watch the src/ directory (default)
npx react-docs-ai watch

# Watch a specific directory
npx react-docs-ai watch src/components/

# With options
npx react-docs-ai watch src/ \
  --output ./docs \
  --debounce 2000 \
  --provider aide \
--no-workflow

Options:

| Flag | Default | Description | |------|---------|-------------| | --output, -o | ./docs | Output directory for generated docs | | --debounce | 1000 | Milliseconds to wait after a file change before regenerating | | --provider | $AI_PROVIDER env | Override AI provider | | --no-workflow | — | Skip workflow generation | | --no-ai | — | Static analysis only |

Files automatically ignored by watch mode:

• node_modules/
• dist/, build/
• *.test.*, *.spec.*, *.stories.*
• *.d.ts declaration files

Graceful shutdown: Press Ctrl+C — the watcher closes cleanly and exits.

release

Generate release intelligence from git history.

# Basic release (compares HEAD against main branch)
npx react-docs-ai release

# Compare against a specific branch
npx react-docs-ai release --base-branch develop

# Compare from a specific commit
npx react-docs-ai release --from abc1234 --to HEAD

# With options
npx react-docs-ai release \
  --output ./release \
  --base-branch main \
  --max-commits 100 \
  --provider aide

Options:

| Flag | Default | Description | |------|---------|-------------| | --output, -o | ./release | Output directory for release artifacts | | --base-branch | main | Branch to compare against | | --from | — | Starting commit SHA | | --to | HEAD | Ending commit SHA | | --max-commits | 50 | Maximum commits to analyze | | --provider | $AI_PROVIDER env | Override AI provider |

Output:

• release/RELEASE_NOTES.md — AI-generated release notes with risk level
• release/QA_TEST_SCENARIOS.md — Structured QA test cases
• release/CHANGELOG.md — Conventional changelog
• release/MIGRATION_NOTES.md — Breaking change migration guide

Registering Providers Dynamically

You can register a custom AI provider at runtime without modifying platform code. This is the recommended approach for:

• Proprietary enterprise LLMs
• Internal API gateways wrapping existing models
• Test/mock providers for CI pipelines
• Providers requiring non-standard authentication

Pattern: Bootstrap Script

Create a bootstrap file in your project that sets up the provider before running documentation generation:

// scripts/docs-with-custom-provider.ts

import {
  registerProvider,
  getProvider,
  BaseAIProvider,
  AIProviderConfig,
  AIGenerateOptions,
  AIGenerateResult,
  AIProviderHealth,
  AIProviderCapabilities,
} from 'react-docs-ai';

// ─── Implement your custom provider ───────────────────────────
class MyEnterpriseProvider extends BaseAIProvider {
  readonly name = 'my-llm';

  constructor(config: AIProviderConfig) {
    super(config);
  }

  async generate(prompt: string, options?: AIGenerateOptions): Promise<AIGenerateResult> {
// Call your internal LLM API here
    const response = await fetch(`${this.config.baseUrl}/v1/chat`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.config.apiKey}`,
        'Content-Type': 'application/json',
     'X-Team-ID': process.env['TEAM_ID'] ?? '',
      },
      body: JSON.stringify({
        model: this.config.model,
        prompt,
        max_tokens: this.config.maxTokens ?? 8192,
    }),
    });

    const data = await response.json() as { content: string; tokens: number };

    return {
      content: data.content,
      provider: this.name,
      model: this.config.model,
      usage: {
        promptTokens: 0,
      completionTokens: data.tokens,
        totalTokens: data.tokens,
      },
    };
  }

  async healthCheck(): Promise<AIProviderHealth> {
    try {
      const res = await fetch(`${this.config.baseUrl}/health`);
      return { healthy: res.ok, provider: this.name };
    } catch (e) {
      return { healthy: false, provider: this.name, error: String(e) };
    }
  }

  getCapabilities(): AIProviderCapabilities {
    return {
      maxContextTokens: 32000,
      supportsStreaming: false,
      supportsJsonMode: false,
      supportsSystemPrompt: true,
    };
  }
}

// ─── Register before any docs generation ──────────────────────
registerProvider('my-llm', () => new MyEnterpriseProvider({
  name: 'my-llm',
  baseUrl: process.env['MY_LLM_API_URL'] ?? '',
  apiKey:  process.env['MY_LLM_API_KEY'] ?? '',
  model:   process.env['MY_LLM_MODEL'] ?? 'enterprise-llm-v2',
  maxTokens: 8192,
  temperature: 0.2,
}));

// ─── Set env to select your provider ──────────────────────────
process.env['AI_PROVIDER'] = 'my-llm';

// ─── Now verify the provider is reachable ──────────────────────
const provider = getProvider();
provider.healthCheck().then(health => {
  if (!health.healthy) {
    console.error('❌ Provider health check failed:', health.error);
    process.exit(1);
  }
  console.log('✅ Provider ready:', health.provider);
});

Run your bootstrap before generate:

ts-node scripts/docs-with-custom-provider.ts && npx react-docs-ai generate src/

Or call generate programmatically after registration (see next section).

Overriding an Existing Provider at Runtime

To override the AiDE provider with different credentials (e.g., per-environment configuration):

import { registerProvider, getProvider, AideProvider } from 'react-docs-ai';

// Override 'aide' with a custom-configured instance
registerProvider('aide', () => new AideProvider({
  name: 'aide',
  baseUrl: process.env['AIDE_API_URL_PROD'],   // Different URL per environment
  apiKey: process.env['AIDE_API_KEY_PROD'],
  model: 'aide-advanced',
  maxTokens: 16384,
  temperature: 0.1,
  maxRetries: 5,
  retryDelayMs: 2000,
customHeaders: {
    'X-Org-ID': process.env['ORG_ID'] ?? '',
    'X-Service-Name': 'react-docs-ai',
  },
}));

process.env['AI_PROVIDER'] = 'aide';
const provider = getProvider(true); // true = force new, bypass singleton cache

Using the Programmatic API

You can use react-docs-ai as a library inside your own Node.js scripts or build tools.

Analyze a single component

import { ComponentAnalyzer } from 'react-docs-ai';

const analyzer = new ComponentAnalyzer();

const result = await analyzer.analyzeFile({
  filePath: './src/components/Button.tsx',
  options: {
    includeAccessibility: true,
    includePerformance: true,
    includeWorkflows: true,
    projectRoot: process.cwd(),
  },
});

if (result.success && result.metadata) {
  console.log('Component:', result.metadata.name);
  console.log('Type:', result.metadata.componentType);
  console.log('Props:', result.metadata.props.length);
  console.log('Hooks:', result.metadata.hooks.length);
  console.log('API calls:', result.metadata.apiCalls.length);
  console.log('A11y issues:', result.metadata.accessibilityObservations.length);
}

Analyze multiple files

import { ComponentAnalyzer } from 'react-docs-ai';
import { glob } from 'glob';

const analyzer = new ComponentAnalyzer();
const files = await glob('src/**/*.tsx');

const results = await analyzer.analyzeFiles(
  files.map(filePath => ({
    filePath,
    options: { projectRoot: process.cwd() },
  }))
);

for (const result of results) {
  if (result.success) {
    console.log(`✅ ${result.filePath} — ${result.metadata?.name}`);
  } else {
    console.log(`❌ ${result.filePath} — ${result.error}`);
  }
}

Generate documentation programmatically

import {
  ComponentAnalyzer,
  PromptBuilder,
  MarkdownGenerator,
FileWriter,
  getProvider,
  registerProvider,
  OpenAIProvider,
} from 'react-docs-ai';

// 1. Optionally configure provider dynamically
registerProvider('openai', () => new OpenAIProvider({
  name: 'openai',
  apiKey: process.env['OPENAI_API_KEY'] ?? '',
  model: 'gpt-4o',
  maxTokens: 8192,
  temperature: 0.2,
}));
process.env['AI_PROVIDER'] = 'openai';

// 2. Analyze component
const analyzer = new ComponentAnalyzer();
const result = await analyzer.analyzeFile({
  filePath: './src/components/UserLoginForm.tsx',
  options: { projectRoot: process.cwd() },
});

if (!result.success || !result.metadata) {
  throw new Error(result.error);
}

// 3. Build AI prompt
const promptBuilder = new PromptBuilder();
const prompt = promptBuilder.buildComponentPrompt(result.metadata);

// 4. Call AI provider
const provider = getProvider();
const aiResult = await provider.generate(prompt, {
  taskType: 'component-analysis',
  maxTokens: 8192,
});

// 5. Generate and save markdown
const generator = new MarkdownGenerator();
const markdown = generator.generateComponentDoc(result.metadata, aiResult.content);

const writer = new FileWriter();
await writer.write('./docs/UserLoginForm.md', markdown);

console.log('✅ Documentation generated: docs/UserLoginForm.md');

Health check before generating

import { getProvider } from 'react-docs-ai';

const provider = getProvider();
const health = await provider.healthCheck();

if (!health.healthy) {
  console.error(`Provider ${health.provider} is not reachable: ${health.error}`);
  console.error(`Latency: ${health.latencyMs}ms`);
  process.exit(1);
}

console.log(`✅ ${health.provider} is healthy (${health.latencyMs}ms)`);

Environment Variable Reference

All configuration is via environment variables. Copy .env.example and fill in your values.

Core Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | AI_PROVIDER | No | aide | Active provider: aide or openai | | PLATFORM_NAME | No | react-docs-ai | Shown in doc headers and sent as X-Client-Name to AiDE | | DOCS_OUTPUT_DIR | No | ./docs | Component documentation output directory | | RELEASE_OUTPUT_DIR | No | ./release | Release artifacts output directory | | WORKFLOW_OUTPUT_DIR | No | ./workflow | Workflow diagram output directory | | LOG_LEVEL | No | info | Logging level: debug, info, warn, error |

AiDE Provider

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | AIDE_API_URL | Yes (if aide) | — | AiDE internal API base URL | | AIDE_API_KEY | Yes (if aide) | — | AiDE API Bearer token | | AIDE_MODEL | No | aide-default | Model identifier | | AIDE_TIMEOUT_MS | No | 30000 | Request timeout in ms | | AIDE_MAX_TOKENS | No | 8192 | Max tokens per response | | AIDE_TEMPERATURE | No | 0.2 | Generation temperature (0.0–1.0) |

OpenAI / Azure OpenAI Provider

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | OPENAI_API_KEY | Yes (if openai) | — | OpenAI API key | | OPENAI_MODEL | No | gpt-4o | Model identifier | | OPENAI_BASE_URL | No | — | Override base URL (for Azure OpenAI) | | OPENAI_MAX_TOKENS | No | 8192 | Max tokens per response | | OPENAI_TEMPERATURE | No | 0.2 | Generation temperature | | AZURE_OPENAI_DEPLOYMENT | No | — | Azure deployment name | | AZURE_OPENAI_API_VERSION | No | — | Azure API version |

Analysis Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | ANALYZE_EXTENSIONS | No | .ts,.tsx,.js,.jsx | File extensions to analyze | | IGNORE_PATTERNS | No | node_modules/**,dist/**,... | Patterns to skip | | MAX_FILE_SIZE_KB | No | 500 | Skip files larger than this |

Git / Release Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | RELEASE_COMMIT_DEPTH | No | 50 | Number of commits to analyze | | RELEASE_BASE_BRANCH | No | main | Branch to diff against |

Rules Engine

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | ENABLE_ACCESSIBILITY_RULES | No | true | Inject accessibility rules into prompts | | ENABLE_ARCHITECTURE_RULES | No | true | Inject architecture rules into prompts | | ENABLE_NAMING_RULES | No | true | Inject naming convention rules into prompts |

Output Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | GENERATE_MERMAID_DIAGRAMS | No | true | Include Mermaid diagrams in workflow docs | | GENERATE_ASCII_DIAGRAMS | No | true | Include ASCII workflow diagrams | | FORMAT_OUTPUT | No | true | Auto-format output markdown with Prettier |

Output Structure

After running generate or watch, your project will have:

your-react-project/
├── docs/
│   ├── Button.md    ← Component README with props, workflow, a11y
│   ├── UserLoginForm.md
│   └── DataGrid.md
│
├── workflow/
│   ├── Button.workflow.md         ← Workflow diagrams + narratives
│   ├── UserLoginForm.workflow.md
│   └── DataGrid.workflow.md
│
└── release/        ← Created by `react-docs-ai release`
    ├── RELEASE_NOTES.md
    ├── QA_TEST_SCENARIOS.md
 ├── CHANGELOG.md
    └── MIGRATION_NOTES.md

CI/CD Integration

GitHub Actions

Create .github/workflows/docs-generate.yml:

name: Generate Documentation

on:
  pull_request:
    paths:
    - 'src/**/*.ts'
      - 'src/**/*.tsx'

jobs:
  generate-docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

- run: npm ci

      - name: Generate documentation
  env:
          AI_PROVIDER: aide
          AIDE_API_URL: ${{ secrets.AIDE_API_URL }}
       AIDE_API_KEY: ${{ secrets.AIDE_API_KEY }}
   PLATFORM_NAME: my-app
 run: npx react-docs-ai generate src/

      - name: Commit generated docs
        run: |
    git config --local user.email "[email protected]"
          git config --local user.name "docs-bot"
          git add docs/ workflow/
          git diff --staged --quiet || git commit -m "docs: auto-generated component documentation"
          git push

Create .github/workflows/docs-release.yml:

name: Release Intelligence

on:
  push:
    branches: [main]

jobs:
  release-docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
     with:
          fetch-depth: 0   # Full history for git analysis

 - uses: actions/setup-node@v4
        with:
 node-version: '20'
          cache: 'npm'

 - run: npm ci

      - name: Generate release notes
        env:
          AI_PROVIDER: aide
          AIDE_API_URL: ${{ secrets.AIDE_API_URL }}
   AIDE_API_KEY: ${{ secrets.AIDE_API_KEY }}
          RELEASE_BASE_BRANCH: main
   RELEASE_COMMIT_DEPTH: 50
        run: npx react-docs-ai release

      - name: Upload release artifacts
    uses: actions/upload-artifact@v4
     with:
          name: release-docs
path: release/

GitLab CI

See .gitlab-ci.example.yml in the repository root for a complete GitLab CI pipeline example including:

• Docs generation on merge requests
• Release notes on merge to main
• Artifact upload

Azure DevOps

See azure-pipelines.example.yml for a complete Azure DevOps pipeline including:

• PR-based doc generation
• Release artifact publishing
• Secret variable group configuration

What Gets Generated

Component Documentation — docs/Button.md

# Button

## Purpose
The Button component is a reusable, accessible interactive element...

## Business Context
Used across every workflow requiring user interaction — form submissions,
dialog triggers, navigation actions, and data mutations...

## Props
| Prop | Type | Required | Description |
|------|------|----------|-------------|
| label | string | ✓ | Accessible button label text |
| onClick | () => void | ✓ | Callback on click |
| isLoading | boolean | — | Shows loading state |
| isDisabled | boolean | — | Prevents interaction |
| variant | "primary" | "secondary" | "danger" | — | Visual style |

## Workflow
1. User encounters the button in context
2. Focuses via Tab or mouse
3. Clicks or presses Enter/Space
4. onClick handler invoked
5. Parent sets isLoading=true during async operation

## Accessibility Notes
- ✅ Semantic <button> element — keyboard accessible natively
- ✅ aria-disabled mirrors disabled state for screen readers
- ✅ aria-busy announces loading state

## Performance Observations
- Stateless component — no memoization concerns
- Consider React.memo() in high-frequency render contexts

Workflow Diagrams — workflow/UserLoginForm.workflow.md

Includes:

• ASCII step-by-step workflow narrative
• Mermaid flowchart diagram
• Integration point list (APIs, callbacks, localStorage)
• Error flow documentation

Release Notes — release/RELEASE_NOTES.md

# Release Summary
Enhanced form validation and accessibility improvements.

**Date:** 2026-05-19
**Branch:** feature/auth-improvements
**Risk Level:** MEDIUM

## Features
- UserLoginForm: Real-time field validation on blur

## Breaking Changes
- Button: `disabled` prop renamed to `isDisabled`

## QA Focus Areas
1. Verify all Button consumers updated to isDisabled
2. Test UserLoginForm field validation combinations

Architecture Overview

CLI Commands (generate | watch | release)
         │
 ▼
ComponentAnalyzer ──────── ts-morph Project (single instance)
    │   │
    ├── PropsAnalyzer           ├── TypeScript/TSX files
    ├── HooksAnalyzer      └── JS/JSX files (text-based fallback)
    ├── ApiAnalyzer
    └── AccessibilityAnalyzer
       │
  ▼
  ComponentMetadata (props, hooks, apiCalls, workflows, a11y, ...)
         │
   ▼
  PromptBuilder ←── Rules Engine (accessibility/architecture/naming JSON)
         │
      ▼
  AIProvider.generate()
    ├── AideProvider    (axios, retry logic, enterprise headers)
    ├── OpenAIProvider  (official SDK, Azure OpenAI support)
    └── CustomProvider  (registerProvider() — plug in your own)
    │
    ▼
  MarkdownGenerator → FileWriter → docs/ workflow/ release/

Key design principles:

• All AI calls go through the AIProvider interface — never call providers directly
• ComponentMetadata is the canonical contract between analyzer and generators
• Sub-analyzer failures produce warnings, never crash the pipeline (safeRun() pattern)
• Provider is selected via AI_PROVIDER env var; registered providers are cached as singletons

Troubleshooting

AIDE_API_URL is required error

You have AI_PROVIDER=aide but haven't set AIDE_API_URL. Either:

• Set AIDE_API_URL in your .env
• Or switch to AI_PROVIDER=openai and set OPENAI_API_KEY

Unknown AI provider: "xyz" error

The value of AI_PROVIDER doesn't match any registered provider. Available built-in providers: aide, openai. For custom providers, register them via registerProvider() before running.

AiDE health check fails but generation works

The health check calls GET /health on your AiDE base URL. If your deployment doesn't expose this endpoint, the health check will fail but generation will still work. This is safe to ignore — the health check is advisory only.

Docs not updating in watch mode

Check that:

1. The file is in the watched directory (default: src/)
2. The file extension is .ts, .tsx, .js, or .jsx
3. The file is not in an ignored path (node_modules, dist, build, *.test.*, *.spec.*, *.stories.*, *.d.ts)
4. The debounce timer has elapsed (default 1000ms after last file write)

TypeScript errors when importing

Ensure your project's tsconfig.json has "esModuleInterop": true. If using moduleResolution: "bundler", add "allowSyntheticDefaultImports": true.

chalk is not a function or similar ESM errors

Do not upgrade chalk to v5, ora to v6+, or chokidar to v5 — these are ESM-only packages incompatible with the CommonJS module system used by react-docs-ai. Stick with the pinned versions: chalk@4, ora@5, chokidar@3.

Large files are skipped

Files over MAX_FILE_SIZE_KB (default: 500 KB) are skipped. Increase this limit in your .env if needed:

MAX_FILE_SIZE_KB=1000

License

MIT — Enterprise Platform Team