Rayburst

Automatic 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.

Features

- 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

Installation

``bash
npm install --save-dev @rayburst/cli
`

Usage

$3

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:
1. Run initial code analysis
2. Generate .rayburst/analysis.json
3. Watch for file changes
4. Update analysis in real-time

$3

`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',
})
`

Output

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.

Analysis Data

The generated analysis.json contains:

- Nodes: Components, functions, state declarations
- Edges: Dependencies between nodes
- Branches: Git branch information
- Files: Modification timestamps

Viewing Your Analysis

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.

Example Output

`typescript
// src/App.tsx
import { Button } from './components/Button'

export function App() {
return alert('Hello')} />
}
`

Rayburst detects:
- App component (node)
- Button component usage (edge: App → Button)
- JSX relationships
- File structure

Console Output

`bash
$ npm run dev

[Rayburst] Starting code analysis...
[Rayburst] Initial analysis complete: 42 nodes, 68 edges

When you edit a file:


[Rayburst] File changed: src/App.tsx
[Rayburst] Analysis updated:
Added: 1 nodes, 2 edges
Modified: 1 nodes
`

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 metadata

Browser 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.json

Enable 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 dev

Terminal 2

rayburst watch
`

After:
`typescript
// vite.config.ts
export default defineConfig({
plugins: [rayburstPlugin(), react()],
})
`

`bash


Just one terminal


npm run dev # Rayburst runs automatically!
``

Contributing

Contributions welcome! Please read our contributing guidelines.

License

MIT

Links

- Documentation
- GitHub Repository
- Issue Tracker