Documentation

Integrate Rootly in under 2 minutes.

What Rootly Does

Rootly captures unexpected production crashes and surfaces them directly inside your IDE.

Rootly focuses on unhandled production crashes — not logging, performance metrics, or client-side monitoring.

Rootly Runtime SDK works in Node.js environments (server-side only).

Never crashes your app
Fails silently on errors
Designed for minimal performance impact
Deduplicates noisy errors
Rate limits excessive reports
Auto-detects commit SHA

Quick Start

1Install the SDK

Add the Rootly Runtime SDK to your Node.js application:

npm install rootly-runtime

2Initialize in your code

Add this to your application entry point (e.g., index.ts or server.ts):

import { init } from 'rootly-runtime';

// Required: Initialize with your API key
init({
  apiKey: process.env.ROOTLY_API_KEY!
});

Captured automatically:

  • • uncaughtException - Unhandled errors
  • • unhandledRejection - Unhandled promise rejections
  • • Express 5xx errors (when using middleware)
  • • Manual capture() calls
  • • wrap()-wrapped functions

Intentionally not captured: 4xx errors, handled try/catch blocks, frontend errors

Beta Notice

Rootly is in active development. While we strive for reliable error capture, some errors may not be captured consistently across all platforms and scenarios. We do not guarantee 100% error detection.

3Get Your API Key

Create a project in your dashboard to get your API key. Add it to your environment variables:

# .env
ROOTLY_API_KEY=your_api_key_here
Get Your API Key

4See it in action

Test with a simple crash endpoint:

app.get('/crash', () => {
  throw new Error("Database connection failed");
});

How it works:

  1. 1.Error happens in production
  2. 2.SDK sends payload to backend
  3. 3.Backend creates incident
  4. 4.IDE extension polls and shows it
  5. 5.Click to jump to exact line in code

IDE Extension

The Rootly VS Code extension displays production errors directly in your editor. Click on any error to jump to the exact line of code that caused it.

Rootly VS Code Extension

Real-time Notifications

Get notified instantly when errors occur in production

Jump to Code

Click "Go to Error Location" to open the exact file and line

Full Stack Traces

View complete error details and stack traces in the sidebar

GitHub Integration

Authenticate with GitHub to access your project incidents

Install from VS Code Marketplace

Platform Support

Supported Platforms

Render

Node.js deployments

Railway

Node.js deployments

GitHub Actions

CI/CD pipelines

Vercel

Serverless functions

Traditional Node.js

Standard servers

Custom

Any Node.js environment

Beta Testing Phase

Rootly is currently in active development and beta testing. Error capture reliability varies across platforms and error types.

  • •Some errors may not be captured consistently
  • •Manual capture() is most reliable across all platforms
  • •We do not guarantee 100% error detection
  • •Continuous improvements are being made to enhance reliability

Automatic Commit SHA Detection

Rootly automatically detects your deployment commit SHA from environment variables. No configuration required on popular platforms.

Vercel
VERCEL_GIT_COMMIT_SHA
GitHub Actions
GITHUB_SHA
Render
RENDER_GIT_COMMIT
Custom
COMMIT_SHA

The commit SHA enables IDE jump-to-code functionality by matching errors to exact file versions.

Built-in Protection

Rootly automatically deduplicates repeated errors and rate limits excessive reports to protect your app and backend.

Deduplication

Identical errors within a 10-second window are automatically deduplicated to prevent noise.

Rate Limiting

Maximum 20 errors per minute to prevent overwhelming your backend during cascading failures.

SDK Features (v1.2.3)

Production Hardening

  • •Environment normalization with NODE_ENV fallback
  • •Severity support (error/warning/info)
  • •Recursive capture protection
  • •Stable fingerprinting algorithm

Performance Optimized

  • •Hard memory cap (500 max fingerprints)
  • •Optimized rate limiter (O(n) performance)
  • •Graceful shutdown request draining
  • •Zero dependencies

Automatic Capture

  • •Uncaught exceptions
  • •Unhandled promise rejections
  • •Express 5xx errors (middleware)
  • •Function wrapping (wrap API)

Production Safety

  • •Fail-silent (never crashes app)
  • •Error deduplication (10s window)
  • •Rate limiting (20 errors/60s)
  • •Auto-detects commit SHA

Optional Configuration

Environment

Specify your environment (defaults to NODE_ENV):

init({
  apiKey: process.env.ROOTLY_API_KEY!,
  environment: 'production' // or 'preview'
});

Debug Mode

Enable debug logging to stderr for troubleshooting:

init({
  apiKey: process.env.ROOTLY_API_KEY!,
  debug: true // Shows dedup, rate limiting, send events
});

Manual Error Capture

Capture handled errors with custom context and severity:

import { capture } from 'rootly-runtime';

try {
  // Your code...
} catch (error) {
  capture(error, { 
    user_id: '123',
    action: 'checkout' 
  }, 'error'); // severity: 'error' | 'warning' | 'info'
}

Express Middleware

Automatically capture 5xx errors in Express apps:

import { expressErrorHandler } from 'rootly-runtime';

// Add BEFORE your final error handler
app.use(expressErrorHandler());

app.use((err, req, res, next) => {
  res.status(500).json({ error: err.message });
});

Important: This middleware captures only 5xx errors. It does NOT capture 4xx errors (validation, auth, etc.).

Architecture

Rootly closes the loop between production failures and your editor.

Runtime SDK (v1.2.3)

NPM package with zero dependencies. Captures errors with deduplication, rate limiting, and graceful shutdown. Fail-silent design never crashes your app.

Backend Service

Node.js API that receives error telemetry, parses stack traces, and correlates errors to exact file locations and line numbers.

Web Dashboard

Project setup and management interface. Connect your GitHub repositories and generate API keys for your applications.

IDE Extension

VS Code/Cursor extension that polls for incidents and displays them directly in your editor at the exact line where errors occurred.

API Reference

init(options)

Initialize the SDK. Must be called before other functions.

interface InitOptions {
  apiKey: string;        // Required: Your Rootly API key
  environment?: string;  // Optional: 'production' or 'preview' (default: NODE_ENV)
  debug?: boolean;       // Optional: Enable debug logging (default: false)
}
capture(error, context?, severity?)

Manually capture an error with optional context and severity.

capture(
  error: Error,
  extraContext?: object,
  severity?: 'error' | 'warning' | 'info'
): void

// Example
capture(new Error('Payment failed'), { 
  user_id: '123',
  amount: 99.99 
}, 'error');
wrap(fn)

Wrap a function to automatically capture errors. Works with sync and async functions.

wrap<T>(fn: T): T

// Example
const safeFunction = wrap(async (userId: string) => {
  const user = await fetchUser(userId);
  return user;
});
expressErrorHandler()

Express middleware for capturing 5xx errors. Place before your final error handler.

app.use(expressErrorHandler());

// Captures errors when res.statusCode >= 500
// Ignores 4xx errors (validation, auth, etc.)
// Always calls next(err) to continue error chain

Security

Data Isolation

Users can ONLY access data for projects they own. All queries are scoped to the authenticated user's projects.

API Key Security

API keys are shown only once during project creation. They are hashed before storage and validated using constant-time comparison to prevent timing attacks.

SDK Safety

The SDK is fail-silent and never crashes your application. All operations are wrapped in try-catch blocks. Network failures are silent.

Need Help?

Check out our GitHub repository for more examples and community support.

Get StartedView on GitHub