llm-docgen

Generate LLM-optimized documentation for React and Stencil components.

Features

• 🔍 Smart Component Discovery: Automatically finds React and Stencil components in any project structure
• 🎯 Multi-Framework Support: Works with both React and Stencil components with auto-detection
• 📋 Advanced Parsing: Extracts props, methods, events, slots, and JSDoc comments from TypeScript files
• 📝 Dual Output Format: Generates both individual component files AND a single consolidated file by default
• 🧠 Framework-Aware Examples: Generates appropriate HTML or JSX examples based on component type
• 🎛️ Flexible Configuration: Works with single packages or monorepos, custom source directories
• 📦 NPX Ready: Use immediately without installation via npx llm-docgen
• 🏗️ Project Agnostic: Works with any React or Stencil project structure

Quick Start

# Generate docs for current directory (creates both individual files AND single consolidated file)
npx llm-docgen

# Custom output directory
npx llm-docgen --output ./documentation

# Generate only single consolidated file
npx llm-docgen --single

# Specific source directories
npx llm-docgen --src components lib shared

# Filter components and verbose output
npx llm-docgen --grep Button --verbose

# Force Stencil component parsing
npx llm-docgen --type stencil

# Auto-detect framework (default)
npx llm-docgen --type auto

Installation

# Global installation
npm install -g llm-docgen

# Or use directly with npx (recommended)
npx llm-docgen

Usage

Basic Usage

# Auto-discover components in current directory (generates both formats)
npx llm-docgen

# Generate docs with custom options
npx llm-docgen --output ./docs --src components --verbose

# Generate only single consolidated file
npx llm-docgen --single --single-file-name "all-components.md"

Options

-o, --output <dir>           Output directory for generated docs (default: "./docs")
-s, --src <dirs...>          Source directories to search (e.g., src lib components)
-r, --root <dir>             Root directory to search from (default: current directory)
-p, --pattern <pattern>      File pattern to match (default: **/*.{tsx,ts})
-e, --exclude <patterns...>  Patterns to exclude
-g, --grep <pattern>         Filter components by name or file path pattern
-t, --type <framework>       Component framework type: react, stencil, auto (default: auto)
--include-examples           Include usage examples in documentation
--include-source-code        Include full source code in documentation
--group-by-category          Group components by category (default: true)
--no-group-by-category       Disable grouping by category
--single                     Generate only the single consolidated file (skip individual files)
--single-file-name <name>    Name for the single file (default: "all-components.md")
--verbose                    Enable verbose logging
--clean                      Clean output directory before generation

Example React Component

import React from 'react';

export interface ButtonProps {
  /** The button content */
  children: React.ReactNode;
  /** Button variant style */
  variant?: 'primary' | 'secondary' | 'outline';
  /** Whether the button is disabled */
  disabled?: boolean;
}

/**
 * A flexible button component with multiple variants
 */
export const Button: React.FC<ButtonProps> = ({
  children,
  variant = 'primary',
  disabled = false
}) => {
  return (
    <button 
      className={`btn btn--${variant}`} 
      disabled={disabled}
    >
      {children}
    </button>
  );
};

Example Stencil Component

import { Component, Prop, Event, EventEmitter, Method, h } from '@stencil/core';

/**
 * @salla/admin-ui-components
 * A customizable button component that supports various themes and states.
 * @slot - Default slot for the button label content.
 * @slot loader - Slot to provide custom loader content.
 */
@Component({
  tag: 's-button',
  styleUrl: 's-button.scss',
  shadow: true,
})
export class SButton {
  /** Button theme: default | primary | secondary */
  @Prop() theme?: 'default' | 'primary' | 'secondary' = 'default';

  /** Button size: sm | md | lg */
  @Prop() size?: 'sm' | 'md' | 'lg' = 'md';

  /** Whether the button is disabled */
  @Prop() disabled?: boolean = false;

  /** Event emitted when button is clicked */
  @Event() buttonClick: EventEmitter<void>;

  /** Method to disable the button programmatically */
  @Method()
  async disable() {
    this.disabled = true;
  }

  render() {
    return (
      <button class={`btn btn--${this.theme} btn--${this.size}`} disabled={this.disabled}>
        <slot />
      </button>
    );
  }
}

Generated Output

The tool generates (by default):

• Individual component docs: Detailed markdown files for each component
• Single consolidated file: All components in one comprehensive file with table of contents
• Category organization: Components grouped by inferred categories
• Props tables: Comprehensive prop documentation with types and descriptions
• File path information: Relative paths, file sizes, and modification dates
• Index files: Navigation and summary files
• Machine-readable: JSON index for programmatic consumption

Project Structure Support

Works with any project structure:

# Standard React project
src/components/
lib/components/
components/

# Monorepo
packages/ui/src/
packages/components/lib/

# Custom structure  
shared/ui/
modules/components/

Output Format

Generated documentation includes:

React Components:

• Component name and description
• Props table with types, requirements, and descriptions
• JSX usage examples with proper React syntax
• Export information

Stencil Components:

• Component name, description, and tag name
• Props table with types, requirements, and descriptions
• Methods table with parameters and return types
• Events table with event types and descriptions
• Slots documentation for content projection
• HTML usage examples with proper Stencil syntax
• JavaScript event listener examples

Both Frameworks:

• File information (relative path, file size, modification date)
• Framework type and category information
• Table of contents with navigation links (single file)
• Summary statistics and file path overview (single file)
• Source code inclusion (optional)
• Machine-readable JSON index

Changelog

v1.1.0 (2025-08-11) - Stencil Framework Support 🚀

🎯 Major New Features

• 🔧 Full Stencil Component Support: Complete parsing and documentation generation for Stencil components
• 🤖 Framework Auto-Detection: Automatically detects React vs Stencil components based on imports and decorators
• 🎛️ Manual Framework Control: New --type flag to force specific framework parsing (react, stencil, auto)

🆕 Stencil-Specific Features

• Props Extraction: Parse @Prop decorators with type information, default values, and JSDoc comments
• Methods Documentation: Extract @Method decorated public methods with parameters and return types
• Events Documentation: Parse @Event decorators and EventEmitter types
• Slots Documentation: Extract slots from JSDoc comments and render methods
• HTML Examples: Generate proper HTML/JavaScript examples instead of JSX for Stencil components
• Web Component Syntax: Use kebab-case tag names and native DOM event patterns

🔍 Enhanced Parsing

• Decorator Detection: Recognize @Component, @Prop, @Method, @Event decorators
• Interface Resolution: Resolve prop types from external interfaces (e.g., sButtonInterface["theme"])
• Slot Extraction: Parse both JSDoc @slot comments and <slot> elements in render methods
• JSDoc Processing: Improved JSDoc comment parsing for all component metadata

🧠 Smart Framework Detection

• Import Analysis: Check for @stencil/core imports
• Decorator Patterns: Detect Stencil decorator usage patterns
• Fallback Logic: Default to React when framework is unclear
• File Extension Support: Handle .tsx files for both frameworks

📝 Documentation Enhancements

• Framework Indicators: Show framework type and tag name in component info
• Method Tables: Dedicated sections for Stencil component methods
• Event Tables: Comprehensive event documentation with types
• Slot Tables: Document content projection capabilities
• Syntax Highlighting: Use html for Stencil examples, tsx for React
• Multi-Framework Titles: Dynamic titles based on detected frameworks

🔧 Technical Improvements

• New StencilParser Class: Dedicated AST parser for Stencil components
• FrameworkDetector Utility: Centralized framework detection logic
• Enhanced Type System: Extended interfaces for Stencil-specific features
• Example Generator Updates: Framework-aware example generation
• Markdown Generator Updates: Support for Stencil documentation sections

🧪 Validation & Testing

• Real-World Testing: Validated with actual Stencil components from production codebases
• Multi-Component Support: Tested with complex Stencil components containing multiple props, methods, events, and slots
• Auto-Detection Verification: Confirmed accurate framework detection across different component types

📦 Package Updates

• Updated Description: Now mentions both React and Stencil support
• New Keywords: Added stencil, web-components to package keywords
• Version Bump: Updated to v1.1.0 following semantic versioning

🏗️ Architecture

• Modular Design: Clean separation between React and Stencil parsing logic
• Extensible Framework: Foundation laid for potential future framework support
• Backward Compatibility: All existing React functionality remains unchanged
• Performance Optimized: Minimal overhead for framework detection

v1.0.1 (Previous) - Foundation Release

• Initial React component documentation generation
• TypeScript AST parsing for props and types
• Dual output format (individual + consolidated files)
• NPX-ready installation and usage
• Flexible project structure support

License

MIT