ConsoleRocks

ConsoleRocks is a lightweight, reliable error tracking and session replay library for web applications. It captures console errors, uncaught exceptions, and network failures, along with a video-like replay of the user's session leading up to the error.

Features

• 📹 Session Replay: Records the last 15 seconds (configurable) of user interactions (DOM mutations, mouse movements, etc.).
• 🪲 Error Capture: Automatically catches:
  • console.error calls
  • Uncaught exceptions (window.onerror)
  • Unhandled promise rejections (unhandledrejection)
• 🌐 Network Monitoring: Logs fetch and XMLHttpRequest details (URL, method, status, duration).
• 🚀 Reliable Delivery: Uses fetch with keepalive: true to ensure error reports are sent even if the tab is closed or the app crashes.
• ⚡ Performance Optimized: Uses a lazy rolling buffer and efficient compression (lz-string) to minimize impact on the main thread.

Installation

npm install console-rocks
# or
yarn add console-rocks
# or
pnpm add console-rocks

Usage

Initialize ConsoleRocks at the entry point of your application (e.g., main.ts, App.tsx, or index.js).

import { ConsoleRocks } from 'console-rocks';

const rocks = new ConsoleRocks('YOUR_API_KEY', {
  captureDurationMs: 15000, // Record the last 15 seconds before an error
  debounceMs: 1000,         // Prevent duplicate error reports within 1 second
  debug: false              // Enable verbose logging for development
});

Script Tag Auto-Initialization

For vanilla JS projects, you can simply include the script with data- attributes:

<script 
  src="https://unpkg.com/console-rocks-lib/dist/console-rocks.umd.cjs"
  data-api-key="YOUR_API_KEY"
  data-capture-duration="15000"
  data-debug
></script>

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | captureDurationMs | number | 10000 | Duration (in ms) of the session recording to upload with the error. | | debounceMs | number | 1000 | Time (in ms) to ignore duplicate errors. | | debug | boolean | false | If true, logs internal ConsoleRocks events to the console. |

How It Works

1. Recording: ConsoleRocks starts a background recorder (using rrweb) that maintains a rolling buffer of the DOM state and user interactions.
2. Detection: When an error occurs (e.g., console.error is called), ConsoleRocks intercepts it.
3. Capture: It retrieves the last captureDurationMs of events from the buffer and compresses them.
4. Reporting: The error details, metadata (viewport, user agent), and the compressed recording are sent to the configured API endpoint (https://api.console.rocks/v1/errors).

Development

Setup

npm install

Build

npm run build

Format

npm run format

License

MIT