🎬 Webrec

Lightweight browser library to capture console logs, network requests, and user interactions for debugging and crash reporting.

Why?

Browsers have console.log, but no way to retrieve logs programmatically. When your app crashes, wouldn't it be nice to:

• 📋 Export the last 100 console logs
• 🖱️ See what the user clicked before the error
• 🌐 View recent network requests
• 💾 Attach this context to bug reports

That's what Webrec does. It keeps a fixed-size history of events in memory, ready to be exported when needed.

Features

• ✅ Lightweight - Zero dependencies
• ✅ Framework agnostic - Works with React, Vue, Angular, vanilla JS
• ✅ Privacy-first - Data stays in memory, never sent anywhere (unless you want it to)
• ✅ Extensible - Plugin system for custom functionality
• ✅ TypeScript support - Full type definitions included

Install

npm install webrec

Quick Start

import webrec from 'webrec';

// Start recording
webrec.start({
  console: { enabled: true },
  network: { enabled: true },
  interactions: { enabled: true },
  errors: { enabled: true }
});

// ... later, when an error occurs or user reports a bug ...
const report = await webrec.export();
console.log(report);
// Or download it
webrec.download({ filename: 'debug-report.json' });

Configuration

You can configure Webrec by passing an options object to start().

webrec.start({
  // Maximum number of events to keep in memory (default: 1000)
  maxEvents: 500,
  
  // Use a preset: 'minimal', 'balanced', or 'verbose'
  preset: 'balanced',

  console: {
    enabled: true,
    methods: ['log', 'info', 'warn', 'error'], // Capture specific methods
    captureStack: true, // Capture stack trace for logs
  },

  interactions: {
    enabled: true,
    clicks: true, // Track clicks
    navigation: true, // Track route changes (pushState, popstate)
  },

  network: {
    enabled: true,
    fetch: true, // Track fetch requests
    xhr: true, // Track XMLHttpRequest
    captureHeaders: false, // Capture response headers
    captureBody: false, // Capture response body (use with caution)
  },

  errors: {
    enabled: true,
    unhandledErrors: true, // Track window.onerror
    unhandledRejections: true, // Track unhandled promise rejections
  }
});

API Reference

webrec.start(config?)

Starts capturing events. If already started, this does nothing.

webrec.stop()

Stops capturing events. Existing events are kept in memory.

webrec.getReport()

Returns a Promise that resolves to a Report object containing all captured events, metadata, and statistics.

webrec.export(format?)

Returns a Promise that resolves to a string representation of the report. Default format is 'json'. Plugins can add support for other formats like 'html', 'csv', etc.

webrec.exportText()

Returns a Promise that resolves to a human-readable text representation of the report.

webrec.download(options?)

Triggers a browser download of the report.

• options.filename: Name of the file (default: webrec-{timestamp}.json)
• options.format: 'json' or 'txt' (default: 'json')

webrec.clear()

Clears all recorded events.

webrec.use(plugin, options?)

Registers a plugin. See Plugins below.

Event Listeners

For simple use cases where you just want to react to events (like logging to an external service), you can use the built-in listeners. These are simpler than creating a full plugin.

// Listen for network requests
webrec.onNetwork((event) => {
  console.log('Network request:', event.url);
});

// Listen for console logs
webrec.onLog((log) => {
  if (log.level === 'error') {
    sendToMyService(log);
  }
});

// Listen for user interactions
webrec.onInteraction((interaction) => {
  console.log('User clicked:', interaction.target);
});

// Listen for errors
webrec.onError((error) => {
  console.error('Captured error:', error.message);
});

When to use Listeners vs Plugins:

• Use Listeners when you just want to "subscribe" to events and do something with them (side effects). It's quick and easy.
• Use Plugins when you need to modify events, filter them out (prevent recording), hook into lifecycle events (onStart, onStop), or package functionality for reuse.

Plugins

Webrec has a powerful plugin system. You can create plugins to hook into lifecycle events, modify data, or add custom functionality.

const myPlugin = {
  name: 'my-plugin',
  version: '1.0.0',
  hooks: {
    onStart(config) {
      console.log('Webrec started!');
    },
    onEvent(event) {
      // Modify or filter events
      if (event.type === 'CONSOLE_LOG' && event.message.includes('secret')) {
        return false; // Drop this event
      }
      return event;
    }
  }
};

webrec.use(myPlugin);

Available Hooks

• onStart(config)
• onStop()
• onEvent(event)
• onLog(logEvent)
• onInteraction(interactionEvent)
• onNetwork(networkEvent)
• onError(errorEvent)
• onReportGenerate(report)
• onExport(data)

Development

Setup

npm install

Run Tests

npm test

Build

npm run build

License

MIT