code-graph

Interactive code dependency graph and file tree visualization components for Fumadocs + Next.js. Drop them into any MDX page to generate live, navigable views of your codebase — no external service required.

What's included:

• DependencyGraph — Mermaid flowchart built from full AST analysis, with pan/zoom, search, hover tooltips, and remote repo ZIP support
• FileTreeView — searchable, filterable file table with export/import/JSDoc metadata and GitHub deep links
• TypeTable — collapsible property tables for type documentation
• AST engine — TypeScript/JS parser extracting imports, exports, functions, types, and signatures

Installation

npm install code-graph

Import the CSS once in your app root (e.g. app/layout.tsx):

import "code-graph/dist/index.css";

Peer dependencies

npm install react react-dom next fumadocs-core

Components

DependencyGraph

Server component. Scans directories with the AST engine and renders an interactive Mermaid flowchart.

import { DependencyGraph } from "code-graph";

export default function Page() {
  return (
    <DependencyGraph
      paths={["../packages/core", "../packages/utils"]}
      ignore={["node_modules", "dist", "*.test.ts"]}
      ignoreFile="../.treeignore"
      showLegend={true}
      showNpmImports={false}
      showTypes={false}
      showPrivateFunctions={false}
      showExportedFunctions={false}
    />
  );
}

| Prop | Type | Default | Description | |------|------|---------|-------------| | paths | string[] | required | Directories to analyze (absolute or relative to cwd) | | descriptions | Record<string, string> | {} | Manual descriptions keyed by relative path | | ignore | string[] | [] | File/folder names or patterns to exclude | | ignoreFile | string | — | Path to a .treeignore file (gitignore-style) | | showLegend | boolean | true | Show toggle control buttons | | showNpmImports | boolean | false | Display external npm dependency nodes | | showTypes | boolean | false | Display type definition nodes | | showPrivateFunctions | boolean | false | Display internal (non-exported) function nodes | | showExportedFunctions | boolean | false | Display exported function nodes | | instructions | React.ReactNode | built-in help | Custom help panel content |

Features:

• Color-coded nodes: entry points (green), core modules (blue), types (purple), utils (gray), npm deps (orange)
• Pan & zoom with drag and Ctrl+scroll
• Click a node to scroll to its file tree entry
• Hover tooltips with JSDoc, exports, and signatures
• Real-time search with node highlight
• Toggle visibility of npm / types / private / exported nodes
• Remote repo analysis: paste a GitHub URL or ZIP to analyze any repo without cloning

FileTreeView

Server component. Generates a filterable table of your file tree with code-analysis metadata.

import { FileTreeView } from "code-graph";

export default function Page() {
  return (
    <FileTreeView
      paths={["../packages/my-lib"]}
      ghBase="https://github.com/user/repo/tree/master/packages/my-lib"
      descriptions={{
        "my-lib": "Core library",
        "my-lib/index.ts": "Main entry point",
      }}
      ignore={["node_modules", "dist"]}
      inferDescriptions={true}
      defaultImportFilter="all"
      defaultInternalFilter="all"
      defaultExportFilter="functions"
      defaultCollapseDepth={4}
    />
  );
}

| Prop | Type | Default | Description | |------|------|---------|-------------| | paths | string[] | required | Directories or files to scan | | ghBase | string | required | GitHub base URL for file deep-links | | descriptions | Record<string, string> | {} | Manual descriptions keyed by relative path | | ignore | string[] | [] | File/folder names or patterns to exclude | | ignoreFile | string | — | Path to a .treeignore file | | inferDescriptions | boolean | true | Auto-extract descriptions from leading JSDoc/comments | | defaultImportFilter | "all" \| "local" \| "npm" | — | Initial import filter | | defaultInternalFilter | "all" \| "declared-types" \| "exported-types" \| "functions" \| "classes" | — | Initial internals filter | | defaultExportFilter | "all" \| "functions" \| "classes" \| "constants" | — | Initial export filter | | defaultCollapseDepth | number | — | Initial tree collapse depth |

Features:

• Fuzzy search (Fuse.js) across names, imports, exports, JSDoc, and signatures
• 3 independent filter dropdowns (imports, types/internals, exports)
• Sort by import / type / export count
• Collapse depth slider
• Rich badge tooltips with Markdown-parsed descriptions, signatures, and type properties
• Clickable file badges linking to GitHub source lines
• package.json detection with dependency listing

TypeTable

Client component for rendering collapsible type/property tables in documentation pages.

import { TypeTable } from "code-graph";

export default function Page() {
  return (
    <TypeTable
      type={{
        name: { type: "string", description: "The node name", required: true },
        children: { type: "TypeNode[]", description: "Nested children", required: false },
      }}
    />
  );
}

Programmatic API

The AST engine is available as a standalone Node.js API:

import {
  generateFileTree,
  analyzeFileContent,
  parseIgnoreFile,
} from "code-graph";

generateFileTree

Scans a directory and returns a tree of FileTreeNode objects.

const tree = generateFileTree(
  "/absolute/path/to/src",
  { "index.ts": "Main entry" }, // descriptions
  new Set(["node_modules", "dist"]), // ignorePatterns
  true // inferDescriptions from JSDoc
);

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | packagesDir | string | required | Root directory to scan | | descriptions | Record<string, string> | {} | Manual descriptions by relative path | | ignorePatterns | Set<string> | new Set() | File/folder names to skip | | inferDescriptions | boolean | false | Extract descriptions from source comments |

analyzeFileContent

Analyzes source text in memory — no filesystem read needed.

import { analyzeFileContent } from "code-graph";

const analysis = analyzeFileContent("index.ts", sourceText);
// { localImports, npmImports, exports, functions, types, ... }

parseIgnoreFile

Parses a .gitignore-style file into a Set<string> of patterns.

import { parseIgnoreFile } from "code-graph";

const patterns = parseIgnoreFile("/path/to/.treeignore");
const tree = generateFileTree("/path/to/src", {}, patterns);

Types

FileTreeNode

interface FileTreeNode {
  name: string;
  type: "file" | "folder";
  path: string;             // relative to scanned root
  description?: string;
  analysis?: FileAnalysis;
  children?: FileTreeNode[];
  packageDependencies?: string[];  // from package.json
  packageExports?: AnalysisItem[];
}

FileAnalysis

interface FileAnalysis {
  localImports: string[];
  localImportSymbols: { source: string; valueNames: string[]; typeNames: string[] }[];
  npmImports: string[];
  exports: AnalysisItem[];
  functions: AnalysisItem[];
  types: AnalysisItem[];
}

AnalysisItem

interface AnalysisItem {
  name: string;
  kind?: "function" | "class" | "constant" | "type";
  line?: number;
  jsdoc?: string;
  signature?: string;
  properties?: TypeProperty[];
}

Dependencies

| Package | Purpose | |---------|---------| | @typescript-eslint/typescript-estree | AST parsing for TS/JS | | mermaid | Graph rendering | | fuse.js | Fuzzy search | | jszip | Remote ZIP repo analysis | | marked | JSDoc → Markdown in tooltips | | @radix-ui/react-tooltip | Badge tooltips | | lucide-react | Icons | | svg-toolbelt | SVG pan/zoom |