CodeViz

Interactive 2D codebase visualization with hierarchical semantic zoom


CodeViz is a React component library for visualizing codebases as interactive 2D maps. It provides developers with an intuitive, map-like interface for understanding code structure, dependencies, and relationships at multiple levels of abstraction.

Features

- Hierarchical Visualization - Directories as nested containment regions (scopes)
- Semantic Zoom - 5 discrete zoom levels showing different information density
- Multi-Language Support - TypeScript, JavaScript, Python via tree-sitter parsing
- Dependency Visualization - Import and call graph relationships as edges
- Overlay System - Cursors, badges, annotations for collaboration
- Theme Support - Light and dark themes with full customization
- Dual Renderers - React Flow (default) or Sigma.js (WebGL) for large graphs
- High Performance - Supports codebases up to 10,000+ files with Sigma renderer

Quick Start

``bash
npm install codeviz
`

`tsx
import { CodeMapComponent, useLayout, analyzeCodebase } from 'codeviz';

function App() {
const [codeGraph, setCodeGraph] = useState(null);

useEffect(() => {
analyzeCodebase('./src').then(result => {
setCodeGraph(result.codeGraph);
});
}, []);

const { codeMap, isComputing } = useLayout(codeGraph);

if (isComputing || !codeMap) {
return

;
}

return (
codeMap={codeMap}
theme="dark"
onNodeClick={(node) => console.log('Clicked:', node)}
/>
);
}
`

Installation

`bash


npm

npm install codeviz

yarn

yarn add codeviz

pnpm

pnpm add codeviz
`

$3

CodeViz requires React 18+:

`bash
npm install react react-dom
`

Usage

$3

Use analyzeCodebase to scan and parse source files:

`tsx
import { analyzeCodebase } from 'codeviz';

const result = await analyzeCodebase('./src', {
extensions: ['.ts', '.tsx', '.js', '.jsx'],
ignorePatterns: ['node_modules', 'dist', '*.test.ts'],
maxDepth: 10,
});

// result.codeGraph contains:
// - files: FileNode[]
// - directories: DirectoryNode[]
// - symbols: SymbolNode[]
// - imports: ImportEdge[]
// - calls: CallEdge[]
`

$3

Transform a CodeGraph into positioned CodeMap:

`tsx
import { useLayout, computeLayout } from 'codeviz';

// React hook (recommended)
const { codeMap, isComputing, error } = useLayout(codeGraph, {
algorithm: 'force-directed',
clusteringEnabled: true,
});

// Or imperative API
const codeMap = await computeLayout(codeGraph, layoutConfig);
`

$3

`tsx
import { CodeMapComponent } from 'codeviz';

codeMap={codeMap}
theme="dark"

// Interaction callbacks
onNodeClick={(node) => handleNodeClick(node)}
onNodeHover={(node) => handleNodeHover(node)}
onScopeToggle={(scopeId, expanded) => handleScopeToggle(scopeId, expanded)}
onViewportChange={(viewport) => handleViewportChange(viewport)}
onZoomLevelChange={(level) => handleZoomLevelChange(level)}

// Selection (controlled)
selectedNodes={['file-1', 'file-2']}
onSelectionChange={(nodeIds) => setSelectedNodes(nodeIds)}
/>
`

$3

Add cursors, badges, and annotations:

`tsx
import { useOverlayPort, CodeMapComponent } from 'codeviz';

function CollaborativeMap({ codeMap }) {
const { port, overlays } = useOverlayPort();

// Add a cursor overlay
const cursorId = port.bind({
type: 'cursor',
position: { type: 'absolute', x: 100, y: 200 },
color: '#6366f1',
label: 'Alice',
});

// Add a badge to a node
port.bind({
type: 'badge',
position: { type: 'node', nodeId: 'file-1', anchor: 'top-right' },
variant: 'count',
value: 3,
});

// Update cursor position
port.update(cursorId, {
position: { type: 'absolute', x: 150, y: 250 },
});

return (
codeMap={codeMap}
overlayPort={port}
onOverlayClick={(id, overlay) => console.log('Overlay clicked:', id)}
/>
);
}
`

Sigma Renderer (WebGL)

For large codebases (1,000+ files), use the Sigma.js renderer for better performance:

`tsx
import { CodeMap } from 'codeviz';

codeMap={codeMap}
codeGraph={codeGraph} // Required for nexus view
renderer="sigma" // Use WebGL renderer
view="structure" // "structure" or "nexus"
theme="dark"
onNodeClick={(nodeId, node) => console.log('Clicked:', nodeId)}
/>
`

$3

| Mode | Description | Data Source | Best For |
|------|-------------|-------------|----------|
| structure | File system hierarchy with scopes | CodeMap | Understanding project organization |
| nexus | Flat relationship graph | CodeGraph | Exploring dependencies and imports |

$3

| Scenario | Recommended Renderer |
|----------|---------------------|
| < 500 nodes | React Flow (richer interactions) |
| 500 - 2,000 nodes | Either (test both) |
| 2,000+ nodes | Sigma (WebGL performance) |
| Need nested scopes | React Flow |
| Need force-directed layout | Sigma |

$3

`tsx
import { SigmaRenderer } from 'codeviz';

// Direct Sigma renderer access (advanced)
graph={graphologyGraph}
view="nexus"
theme={darkTheme}

// Selection
selectedNodeId={selectedNode}
onSelectedNodeChange={setSelectedNode}

// Highlights (e.g., from AI/search)
highlightedNodeIds={['file-1', 'file-2']}

// Controls
showControls={true}
controlsPosition="bottom-right"

// Overlays work with Sigma too
overlays={overlays}
onOverlayClick={handleOverlayClick}
/>
`

$3

`tsx
import { useRef } from 'react';
import { SigmaRenderer, SigmaRendererHandle } from 'codeviz';

function MyComponent() {
const sigmaRef = useRef(null);

const handleFocus = () => {
sigmaRef.current?.focusNode('file-1');
};

const handleFitAll = () => {
sigmaRef.current?.fitToNodes(['file-1', 'file-2', 'file-3']);
};

return (
<>

Focus Node
sigmaRef.current?.zoomIn()}>Zoom In
sigmaRef.current?.resetView()}>Reset

);
}
`

Zoom Levels

CodeViz uses 5 semantic zoom levels:

| Level | Name | Zoom Range | Content |
|-------|------|------------|---------|
| 0 | Overview | 0 - 0.25 | Top directories only, aggregated edges |
| 1 | Modules | 0.25 - 0.5 | Subdirectories + large files (>200 LOC) |
| 2 | Files | 0.5 - 1.0 | All files + exported symbols |
| 3 | Symbols | 1.0 - 2.0 | All symbols + call graph edges |
| 4 | Code | 2.0+ | Code preview panels, all details |

Configuration

$3

`tsx
import { computeLayout, DEFAULT_LAYOUT_CONFIG } from 'codeviz';

const layoutConfig = {
...DEFAULT_LAYOUT_CONFIG,

// Clustering
clusteringEnabled: true,
clusteringResolution: 1.0,

// Force-directed layout
forceIterations: 100,
forceGravity: 0.1,
forceRepulsion: 1.0,

// Sizing
nodeSizeBase: 40,
nodeSizeScale: 1.5,
scopePadding: { top: 40, right: 20, bottom: 20, left: 20 },
};

const codeMap = await computeLayout(codeGraph, layoutConfig);
`

$3

`tsx
import { CodeMapComponent, darkTheme, mergeTheme } from 'codeviz';

const customTheme = mergeTheme(darkTheme, {
colors: {
nodes: {
file: { background: '#1e293b', border: '#334155' },
},
scopes: {
depth0: '#0f172a',
depth1: '#1e293b',
depth2: '#334155',
},
},
});


`

API Overview

$3

| Component | Description |
|-----------|-------------|
| CodeMapComponent | Main visualization component (React Flow renderer) |
| CodeMap | Unified component supporting both renderers |
| SigmaRenderer | WebGL-based Sigma.js renderer |
| ThemeProvider | Theme context provider |
| OverlayLayer | Overlay rendering layer |
| GraphControls | Zoom/pan controls for Sigma renderer |

$3

| Hook | Description |
|------|-------------|
| useLayout | Compute layout from CodeGraph |
| useOverlayPort | Manage overlay state |
| useTheme | Access current theme |

$3

| Function | Description |
|----------|-------------|
| analyzeCodebase | Scan and parse source files |
| computeLayout | Transform CodeGraph to CodeMap |
| createOverlayPort | Create imperative overlay controller |

$3

`tsx
import type {
// Input types
CodeGraph,
FileNode,
DirectoryNode,
SymbolNode,

// Output types
CodeMap,
MapNode,
MapScope,
MapEdge,

// Configuration
LayoutConfig,
ZoomLevelConfig,
Theme,

// Overlays
Overlay,
CursorOverlay,
BadgeOverlay,
AnnotationOverlay,
} from 'codeviz';
`

Storybook

Explore components interactively:

`bash
npm run storybook
`

Visit http://localhost:6006 to see:
- CodeMap with sample data
- Theme comparisons (light/dark)
- Overlay demonstrations
- Hook integration examples

Development

`bash


Install dependencies

npm install

Run tests

npm test

Run tests once

npm run test:run

Type checking

npm run typecheck

Build library

npm run build

Start Storybook

npm run storybook
`

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run tests (npm test)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature`)
6. Open a Pull Request

License

MIT License - see LICENSE for details.

Acknowledgments

Built with:
- React Flow - React library for node-based UIs
- Sigma.js - WebGL graph visualization
- tree-sitter - Incremental parsing system
- graphology - Graph data structure
- ELK - Eclipse Layout Kernel
- Lucide - Icon library