DOCSEARCHbyAlgolia
Submit Docs

rrweb

repository·main·Indexed 12 days ago

https://github.com/rrweb-io/rrweb

A tool for recording and replaying user interactions on the web to create digital twins of user sessions for debugging and analysis. It includes a suite of packages such as @rrweb/record, @rrweb/replay, @rrweb/packer for event compression, and @rrweb/browser-client for streaming recordings to a Cloud-compatible API. It also supports advanced features like live canvas streaming via WebRTC plugins.

Tokens
71.7K
Snippets
221
Records
322
Agent score
97%

What's inside rrweb

  1. What is rrweb?

    main
    rrweb ('record and replay the web') is a tool designed to record and replay user interactions on the web. It allows developers to capture a user's session and reconstruct it later for debugging, user research, or analytics.

  2. Overview of @rrweb/packer

    main

    The @rrweb/packer package is used to compress rrweb events on the frontend before they are transmitted over the network.

    Key Characteristics:

    • Compression Method: It uses fflate for zlib compression.
    • Granularity: It compresses each rrweb event separately as it is emitted.
    • Bundle Impact: Adding the encoder to your recording side adds approximately 17KB (minified) to your bundle (this size decreases after gzip).
    • Replay/Decompression: Decompression during the replay phase is handled separately via the @rrweb/packer/unpack entry point.

  3. Overview of @rrweb/types

    main

    The @rrweb/types package provides the shared TypeScript definitions used across the entire rrweb ecosystem. These types are used to enforce correctness and define the data API between different rrweb packages (such as recording, packing, and replaying).

    The most critical type in the ecosystem is the Event type, which represents the fundamental unit of data captured during a session. For a detailed breakdown of the event structure, refer to the Events documentation.

  6. Choose the right rrweb package for your use case

    main

    rrweb is organized as a monorepo. Depending on whether you need to record sessions, replay them, or both, you should choose the appropriate package:

    Recording and Replaying

    • @rrweb/all: A convenience package that includes @rrweb/record, @rrweb/replay, and @rrweb/packer. Note that it does not include any plugins.
    • @rrweb/record: Use this for the recording logic within your frontend application or webpage.
    • @rrweb/replay: Use this to rebuild and replay recorded events inside an iframe.
    • rrweb (Legacy): The original package containing both record and replay. It is deprecated in favor of using @rrweb/record + @rrweb/replay or the @rrweb/all convenience package.

    Specialized Tools

    • rrweb-player: A UI package built on top of @rrweb/replay that provides a feature-rich playback interface out of the box.
    • @rrweb/packer: Provides basic per-event compression for data before network transmission.
    • rrvideo: A tool to transform rrweb session recordings into video files.
    • web-extension: A browser extension for recording and replaying web pages.

    Core Utilities and DOM

    • rrweb-snapshot: Used to snapshot the DOM into a stateful, serializable data structure (the basis for FullSnapshot events).
    • rrdom: A virtual DOM library used to fast-forward DOM mutations during replay.
    • rrdom-nodejs: A Node.js implementation of rrdom for server-side processing of rrweb data.
    • @rrweb/types: Shared TypeScript definitions.
    • @rrweb/utils: Shared utility functions.

  7. Common rrweb usage scenarios

    main

    rrweb provides several specialized patterns for different use cases. Depending on your requirements, you may implement one or more of the following:

    • Record and Replay: The standard workflow for collecting user behaviors and replaying them later.
    • Asynchronous Event Loading: For large event datasets, use pagination to load events incrementally rather than in a single request.
    • Real-time Replay (Live Mode): Replay events in real-time, useful for real-time collaboration.
    • Custom Events: Record and play back non-DOM events alongside standard rrweb events.
    • UI Interaction during Replay: Programmatically enable or disable the ability to interact with the UI while a replay is running.
    • Custom Replayer: Build a custom UI if the default Replayer or rrweb-player components do not meet your needs.
    • Video Conversion: Convert rrweb's text-based event data into video formats using external tools.
    • Storage Optimization: Techniques to reduce the amount of data recorded in applications that generate excessive rrweb events.
    • Canvas Recording: Specialized options for recording and replaying <canvas> elements, which are not recorded by default.
    • Console Recording: Use plugins to record and replay console output to aid in debugging.
    • Plugin Extension: Use the Plugin API to extend rrweb's functionality without modifying core packages.

  8. Explore rrweb usage scenarios and recipes

    main

    rrweb provides various implementation patterns depending on your requirements. Common use cases include:

    • Record and Replay: The standard workflow for capturing user behavior and replaying it later.
    • Asynchronous Data Loading: Using pagination to load large recording datasets incrementally to reduce network overhead.
    • Live Mode (Real-time Replay): Streaming recorded data continuously for live monitoring or real-time collaboration.
    • Custom Events: Injecting specific meaningful data points into the recording timeline during the capture process.
    • UI Interaction during Replay: Enabling user interaction with the replayed DOM when the default non-interactive mode is insufficient.
    • Custom Replayer UI: Building a bespoke player interface when the default Replayer or rrweb-player components do not meet design needs.
    • Video Export: Converting rrweb's text-based recording data into video formats.
    • Storage Optimization: Implementing strategies to manage and reduce the size of recorded data.
    • Canvas Support: Configuring rrweb to observe and record content within <canvas> elements.
    • Console Recording/Replay: Using plugins to capture and replay console outputs for debugging purposes.
    • Plugin API: Extending rrweb functionality via a plugin system that keeps the core package decoupled.

  9. Overview of @rrweb/all

    main

    The @rrweb/all package is a convenience bundle that includes multiple rrweb packages in a single installation. It is intended for simplified setups, demos, or tooling where you want access to the recorder, replayer, and packer simultaneously.

    Included Packages:

    • rrweb
    • @rrweb/record
    • @rrweb/replay
    • @rrweb/packer

    When to use alternatives: In most production environments, the recorder and replayer are deployed to different pages or applications. In these cases, it is recommended to use specific packages instead of the all-in-one bundle to reduce bundle size:

    • Use @rrweb/record on pages that need to record sessions.
    • Use @rrweb/replay (or rrweb-player for a UI) on pages that need to replay sessions.

  10. What is rrdom?

    main
    rrdom is a standalone virtual DOM library used by rrweb to replay DOM mutations. It allows for the creation of a virtual DOM tree and the application of patches to the real DOM. In the context of rrweb, it is primarily used to optimize replay performance, particularly during seeking operations.

  11. How rrweb replay works

    main

    rrweb follows a design principle of minimizing processing on the recording side to reduce impact on the recorded page. To achieve this, the replay engine performs specialized processing to reconstruct the state.

    Key mechanisms include:

    • High-precision timing: Uses a calibrated timer based on requestAnimationFrame rather than setTimeout to ensure incremental snapshots are applied with sub-frame accuracy, even if the main thread is busy.
    • Missing node handling: Uses a "missing node pool" to manage nodes that cannot be immediately inserted into the DOM due to serialization order (e.g., when a neighbor node hasn't been recorded yet).
    • Hover simulation: Since JavaScript cannot trigger CSS :hover states, rrweb simulates them by injecting special selectors (like .:hover) and applying them to elements and their ancestors during mouse-up/move events.
    • Arbitrary seek/start: Allows replaying from any point in time by executing all snapshots prior to the target start time synchronously, followed by asynchronous execution of the remaining snapshots.

  12. Rebuild snapshots using checkout

    main

    By default, replaying requires all incremental events. To reduce storage requirements or capture only recent history (e.g., during an error), you can use the checkout mechanism to periodically create full snapshots.

    • checkoutEveryNth: Rebuilds a snapshot every N events.
    • checkoutEveryNms: Rebuilds a snapshot every N milliseconds.

    When a snapshot is rebuilt, the emit callback receives isCheckout as a second argument, which will be true.

    let eventsMatrix = [[]];

record({
  emit(event, isCheckout) {
    if (isCheckout) {
      eventsMatrix.push([]);
    }
    const lastEvents = eventsMatrix[eventsMatrix.length - 1];
    lastEvents.push(event);
  },
  checkoutEveryNth: 200, // Rebuild snapshot every 200 events
});