A 3D visualization tool for exploring Git repository evolution over time. Watch your codebase grow, change, and evolve with an interactive force-directed graph showing files and directories as connected nodes in 3D space.
- EMBEDDING.md - Complete guide for using the npm package in your React app
- LLM_INTEGRATION.md - Comprehensive guide for AI assistants and LLM agents
- WORKER_DEPLOYMENT.md - Step-by-step instructions for deploying the Cloudflare Worker
- CHANGELOG.md - Version history and release notes
- worker/README.md - Technical API reference for the worker
Install the package in your React application:
npm install react-github-timeline
# or
pnpm add react-github-timelineThen import and use the component:
import { RepoTimeline } from 'react-github-timeline';
function App() {
return (
<div style={{ width: '100vw', height: '100vh' }}>
<RepoTimeline repoPath="facebook/react" />
</div>
);
}GitHub's API has a rate limit of 60 requests/hour for unauthenticated requests. For better performance, pass a GitHub personal access token:
<RepoTimeline
repoPath="facebook/react"
githubToken="ghp_your_token_here" // 5,000 requests/hour
/>How to get a token:
- Go to GitHub → Settings → Developer settings → Personal access tokens
- Generate new token (classic)
- No scopes needed for public repositories
- Copy the token and pass it to the component
<RepoTimeline
repoPath="facebook/react"
githubToken={import.meta.env.VITE_GITHUB_TOKEN}
/>📖 Full embedding guide - Installation, props, TypeScript, and advanced usage
For local development or to contribute to this project:
- Clone the repository
- Install dependencies:
pnpm install - Start dev server:
pnpm dev - Open browser to
http://localhost:5173
See the Contributing section below for more details.
This project automatically deploys to GitHub Pages via GitHub Actions. To enable:
- Go to repository Settings → Pages
- Under Build and deployment, set Source to GitHub Actions
- Push to main branch to trigger deployment
The site will be available at https://[username].github.io/github-timeline/
- 3D Force-Directed Graph: Files and directories are visualized as nodes connected by springs, creating an organic, physics-based layout
- Time Travel: Scrub through your repository's commit history to see how the structure evolved
- Real GitHub Integration: Analyze any public GitHub repository by entering
owner/repo - Cloudflare Worker Caching: Fast loading with globally cached PR data, avoiding GitHub rate limits
- Interactive Playback: Multiple speeds (1x to 1800x), forward/backward playback, and smooth transitions
- Incremental Loading: Watch the visualization build progressively as data loads
- Interactive Controls: Pan, zoom, and rotate the 3D view with your mouse
- File Size Visualization: Node sizes reflect file sizes (logarithmic scale)
- Real-time Physics: Watch the graph settle into its natural layout with spring physics
- Smart Caching: IndexedDB caching (with localStorage fallback) for instant subsequent loads
- Vite: Fast build tool and dev server
- React: UI framework
- TypeScript: Type-safe development
- Three.js: 3D rendering engine
- React Three Fiber: React renderer for Three.js
- React Three Drei: Useful helpers for R3F
- Tailwind CSS: Utility-first styling
- Vitest: Fast unit testing with coverage
- Biome: Fast linter and formatter
- pnpm: Efficient package manager
- Cloudflare Workers: Edge computing for API caching
- Cloudflare D1: SQLite database for PR data storage
- GitHub API: Source of repository data
pnpm installpnpm dev # Start demo app dev serverOpen your browser to http://localhost:5173
pnpm build # Build library for npm
pnpm build:demo # Build demo app for GitHub Pagespnpm test # Run tests in watch mode
pnpm test:coverage # Run tests with coverage report
pnpm test:ui # Run tests with interactive UICoverage thresholds are set at 50% for statements, branches, functions, and lines.
pnpm lint # Check code quality
pnpm lint:fix # Auto-fix issues
pnpm format # Format code with Biomepnpm size # Check bundle sizes against limits
pnpm size:why # Analyze what's included in bundlesThe project enforces bundle size limits to ensure the npm package stays lightweight:
- ESM: ~16 KB gzipped (limit: 18 KB)
- UMD: ~16 KB gzipped (limit: 17.5 KB)
These limits are checked automatically during:
- Local builds (
pnpm build) - CI/CD pipeline (GitHub Actions)
- The build will fail if bundle sizes exceed limits
pnpm preview # Preview demo buildgithub-timeline/
├── src/
│ ├── lib/ # NPM package exports
│ │ ├── index.ts # Main library entry point
│ │ └── types.ts # Public API types
│ ├── demo/ # Demo app (GitHub Pages)
│ │ ├── App.tsx # Demo app root
│ │ ├── main.tsx # Demo app entry point
│ │ ├── RepoInput.tsx # Repository input form
│ │ └── RepoWrapper.tsx # Demo app wrapper
│ ├── components/
│ │ ├── FileNode3D.tsx # Individual file/directory node
│ │ ├── FileEdge3D.tsx # Connection between nodes
│ │ ├── RepoGraph3D.tsx # Main 3D graph component
│ │ ├── TimelineScrubber.tsx # Commit timeline controls
│ │ ├── RepoTimeline.tsx # Main container component
│ │ ├── GitHubAuthButton.tsx # GitHub authentication
│ │ ├── RateLimitDisplay.tsx # Rate limit indicator
│ │ └── TestScene.tsx # Test visualization scene
│ ├── services/
│ │ ├── gitService.ts # Main Git service orchestration
│ │ ├── githubApiService.ts # GitHub API integration
│ │ └── storageService.ts # IndexedDB/localStorage caching
│ ├── utils/
│ │ ├── forceSimulation.ts # Physics simulation for graph layout
│ │ ├── fileTreeBuilder.ts # Build file trees from PR data
│ │ └── fileStateTracker.ts # Track file state across PRs
│ ├── data/
│ │ └── demoCommits.ts # Demo data for fallback
│ ├── config.ts # Application configuration
│ ├── types.ts # TypeScript type definitions
│ └── index.css # Global styles
├── dist/ # NPM package build output
│ ├── index.js # ESM bundle
│ ├── index.umd.js # UMD bundle
│ ├── index.d.ts # TypeScript declarations
│ └── style.css # Bundled styles
├── demo-dist/ # Demo app build output (GitHub Pages)
├── worker/ # Cloudflare Worker (optional)
│ ├── src/
│ │ └── index.ts # Worker API endpoints
│ ├── migrations/ # D1 database migrations
│ ├── wrangler.toml # Worker configuration
│ └── package.json
├── index.html
├── package.json
├── vite.config.ts # Library build config
├── vite.demo.config.ts # Demo build config
└── tailwind.config.js
The visualization uses a custom force-directed graph algorithm with three types of forces:
- Spring Forces: Connected nodes (parent/child relationships) attract each other
- Repulsion Forces: All nodes repel each other to prevent overlap
- Centering Force: Gentle pull toward the origin to keep the graph centered
- User enters repository (
owner/repo) - Metadata fetch: Quick metadata endpoint loads PR list and time range
- Data source selection:
- Cloudflare Worker (preferred): Fetches cached PR data from global D1 database
- IndexedDB/localStorage cache: Loads previously fetched data instantly
- GitHub API (fallback): Direct API calls with rate limiting
- Incremental loading: PRs processed one-by-one, visualization updates in real-time
- File state tracking: Each PR's file changes are applied cumulatively
- Tree building: File paths converted to hierarchical node/edge structure
- Force simulation: Physics calculates optimal 3D positions for nodes
- Three.js rendering: 3D scene rendered with React Three Fiber
- Time travel: Scrubber controls let you navigate through commits
- Blue octahedrons (diamonds): Directories (fixed size)
- Green spheres: Files (size scales logarithmically with file size)
- White tubes: Parent-child relationships in file tree
- Virtual root: "/" node connects all root-level files
- Transitions: Smooth animations show size changes, additions, deletions
Edit src/utils/forceSimulation.ts:
new ForceSimulation(nodesCopy, edges, {
strength: 0.05, // Spring strength
distance: 30, // Target distance between connected nodes
iterations: 300, // Simulation steps
});Edit colors in src/components/FileNode3D.tsx and src/components/FileEdge3D.tsx
Edit initial camera position in src/components/RepoGraph3D.tsx:
camera={{ position: [0, 0, 200], fov: 75 }}For better performance and to avoid GitHub rate limits, you can deploy the included Cloudflare Worker. The worker provides:
- Global caching of PR data across all users
- Background updates to keep cache fresh
- 5,000+ requests/hour (vs 60 unauthenticated GitHub API)
- <100ms response times for cached repos
- Free tier covers most usage
See WORKER_DEPLOYMENT.md for complete step-by-step setup instructions.
- ✅
Real Git integration(Completed - GitHub API + Worker) - ✅
Animation transitions between commits(Completed) - File content diffing
- Dependency graph visualization (import/export relationships)
- Author-based coloring
- Commit message search
- Export visualizations as video/GIF
- Multiple repository comparison
- Custom layout algorithms (hierarchical, circular, etc.)
- Performance optimizations for very large repos (>10k PRs)
- Branch visualization
- Interactive file diff viewer
This project joins a rich ecosystem of repository visualization tools. Here are some other great projects in this space:
-
Gource (12.4k ⭐) - The gold standard for repository visualization. Creates beautiful animated trees showing developers working on files over time. Desktop app supporting Git, SVN, Mercurial, Bazaar, and CVS. Perfect for creating presentation videos of your project's evolution.
-
git-story - Python CLI tool that creates MP4 video animations of Git commit history. Great for generating videos of your repository's development.
-
City Blocks - Visualizes repositories as 3D cities where file sizes and commit frequency are represented as buildings. Unique metaphor for understanding codebase structure.
-
GitHub Next Repo Visualizer - React + D3.js visualization using circular pack layout. Creates SVG diagrams showing file structure with color-coded file types.
-
GitDiagram - AI-powered tool that transforms repositories into interactive architecture diagrams using Claude AI.
react-github-timeline focuses on:
- 🌐 Embeddable React component - Not a standalone app, but a component you can embed in your own React applications
- 📊 Time-based evolution - Shows how files change over time with playback controls, not just current state
- 🎮 Interactive 3D physics - Real-time force-directed graph with d3-force-3d simulation
- 🔌 GitHub-native - Direct GitHub API integration with built-in caching and rate limit handling
- 📦 npm package - Easy to install and integrate:
npm install react-github-timeline
We're inspired by these projects and grateful for the visualization work that came before us!
MIT
Contributions welcome! Please open an issue or PR.