Rayburst - Automatic code analysis for TypeScript/JavaScript projects via Vite plugin
npm install @rayburst/cliAutomatic code analysis for TypeScript/JavaScript projects. Rayburst runs in the background during development and generates dependency graphs that you can visualize in the Rayburst web application.
- Automatic Analysis: Runs automatically when you start your dev server - no manual commands needed
- Real-time Updates: Watches for file changes and updates analysis instantly
- TypeScript/JavaScript Support: Full analysis of TS, TSX, JS, and JSX files
- React Components: Detects React components and their dependencies
- Function Tracking: Maps function calls and relationships
- Git Integration: Tracks branches, commits, and changes
- Zero Configuration: Works out of the box with sensible defaults
``bash`
npm install --save-dev @rayburst/cli
Add the Rayburst plugin to your vite.config.ts:
`typescript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { rayburstPlugin } from '@rayburst/cli/vite'
export default defineConfig({
plugins: [
rayburstPlugin(), // Add this line
react(),
],
})
`
That's it! Now when you run npm run dev, Rayburst will automatically:.rayburst/analysis.json
1. Run initial code analysis
2. Generate
3. Watch for file changes
4. Update analysis in real-time
`typescript
rayburstPlugin({
// Disable the plugin (e.g., for testing)
enabled: true,
// Debounce delay for file changes (ms)
debounceMs: 1500,
// Custom output path
outputPath: '.rayburst/analysis.json',
})
`
The plugin generates a .rayburst/ directory in your project root:
``
my-project/
├── .rayburst/
│ └── analysis.json # Analysis data (nodes, edges, dependencies)
├── .gitignore # Auto-updated to ignore .rayburst/
├── src/
├── vite.config.ts
└── package.json
The .rayburst/ directory is automatically added to your .gitignore.
The generated analysis.json contains:
- Nodes: Components, functions, state declarations
- Edges: Dependencies between nodes
- Branches: Git branch information
- Files: Modification timestamps
Once analysis is complete, open the Rayburst web application in Chrome or Edge:
1. Click "Add Project" button
2. Select your project folder
3. The app will load .rayburst/analysis.json automatically
4. Explore your codebase visually with interactive dependency graphs
The web app uses the File System Access API (Chrome/Edge only) to read your local analysis data.
`typescript
// src/App.tsx
import { Button } from './components/Button'
export function App() {
return
Rayburst detects:
- App component (node)Button
- component usage (edge: App → Button)
- JSX relationships
- File structure
`bash
$ npm run dev
[Rayburst] Starting code analysis...
[Rayburst] Initial analysis complete: 42 nodes, 68 edges
How It Works
Rayburst uses a Vite plugin that:
1. Hooks into Vite's lifecycle: Runs when dev server starts
2. Uses ts-morph: Analyzes TypeScript/JavaScript AST
3. Watches files: Leverages Vite's built-in file watcher
4. Incremental updates: Only re-analyzes changed files
5. Generates graphs: Produces node/edge data structures
Requirements
- Vite: 4.x, 5.x, 6.x, or 7.x
- TypeScript: Project must have
tsconfig.json
- package.json: Required for project metadataBrowser Compatibility
The analysis data can be viewed in the Rayburst web app, which requires:
- Chrome 86+ or Edge 86+ (for File System Access API)
Advanced Usage
$3
You can also use Rayburst programmatically:
`typescript
import { analyzeProject, writeLocalAnalysis } from '@rayburst/cli'// Analyze a project
const analysis = await analyzeProject('/path/to/project')
// Write results
await writeLocalAnalysis('/path/to/project', analysis)
`$3
`typescript
import {
analyzeProject,
ensureRayburstDir,
writeLocalAnalysis
} from '@rayburst/cli'async function customAnalysis() {
const projectPath = process.cwd()
// Ensure .rayburst directory exists
await ensureRayburstDir(projectPath)
// Run analysis
const result = await analyzeProject(projectPath)
// Save results
await writeLocalAnalysis(projectPath, result)
console.log(
Analyzed ${result.planData.nodes.length} nodes)
}
`Troubleshooting
$3
Make sure:
1. Plugin is added to
vite.config.ts
2. You're running in dev mode (npm run dev, not npm run build)
3. Project has tsconfig.json$3
Check:
1.
.rayburst/ directory exists
2. Console for error messages
3. Project has TypeScript/JavaScript files$3
Common causes:
- Invalid
tsconfig.json
- TypeScript compilation errors
- Missing package.jsonEnable verbose logging:
`typescript
rayburstPlugin({
enabled: process.env.DEBUG === 'true'
})
`CI/CD
The plugin is automatically disabled in CI environments (when
CI=true). To force enable:`typescript
rayburstPlugin({
enabled: true // Always enabled
})
`Migration from Old Versions
If you were using
rayburst watch command:Before:
`bash
Terminal 1
npm run devTerminal 2
rayburst watch
`After:
`typescript
// vite.config.ts
export default defineConfig({
plugins: [rayburstPlugin(), react()],
})
``bash
Just one terminal
npm run dev # Rayburst runs automatically!
``Contributions welcome! Please read our contributing guidelines.
MIT