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

npm install --save-dev @rayburst/cli

Usage

Vite Projects

Add the Rayburst plugin to your vite.config.ts:

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

Configuration Options

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

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

export function App() {
  return <Button onClick={() => alert('Hello')} />
}

Rayburst detects:

• App component (node)
• Button component usage (edge: App → Button)
• JSX relationships
• File structure

Console Output

$ 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

Programmatic API

You can also use Rayburst programmatically:

import { analyzeProject, writeLocalAnalysis } from '@rayburst/cli'

// Analyze a project
const analysis = await analyzeProject('/path/to/project')

// Write results
await writeLocalAnalysis('/path/to/project', analysis)

Custom Integration

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

Plugin Not Running

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

No Analysis Generated

Check:

1. .rayburst/ directory exists
2. Console for error messages
3. Project has TypeScript/JavaScript files

Analysis Fails

Common causes:

• Invalid tsconfig.json
• TypeScript compilation errors
• Missing package.json

Enable verbose logging:

rayburstPlugin({
  enabled: process.env.DEBUG === 'true'
})

CI/CD

The plugin is automatically disabled in CI environments (when CI=true). To force enable:

rayburstPlugin({
  enabled: true  // Always enabled
})

Migration from Old Versions

If you were using rayburst watch command:

Before:

# Terminal 1
npm run dev

# Terminal 2
rayburst watch

After:

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

# 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