rrweb/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

rrweb is a web session recording and replay library. It records user interactions on web pages (DOM mutations, mouse movements, input events, etc.) and can replay them faithfully. The project is a TypeScript monorepo managed by Yarn workspaces and Turborepo.

Common Commands

# Install dependencies (use yarn, NOT npm)
yarn install

# Build all packages
yarn build:all

# Watch mode for all packages (auto-rebuild on changes)
yarn dev

# Run all tests across the monorepo
yarn test

# Run tests for a specific package (run from package directory)
cd packages/rrweb && yarn test          # builds then runs tests
cd packages/rrweb && yarn retest        # runs tests without rebuild (faster)
cd packages/rrweb-snapshot && yarn test

# Watch mode tests for a specific package
cd packages/rrweb && yarn test:watch

# Update test snapshots
cd packages/rrweb && yarn test:update   # or retest:update for no rebuild

# Lint
yarn lint

# Format
yarn format

# Type check all packages
yarn check-types

# REPL tool (interactive testing in browser)
yarn repl

Architecture

Package Dependency Graph

The core data flow is: snapshot captures DOM → record observes mutations → replay reconstructs events.

@rrweb/types          (shared type definitions, no deps)
@rrweb/utils          (shared utilities)
rrweb-snapshot        (DOM serialization/deserialization, depends on types/utils)
rrdom / rrdom-nodejs  (virtual DOM for Node.js environments)
rrweb                 (main package: record + replay, depends on all above)
  ├── src/record/     (DOM mutation observers, event capture, canvas recording)
  └── src/replay/     (event replay engine, timer, canvas replay, style injection)
rrweb-player          (Svelte-based player UI)
@rrweb/all            (convenience package combining record + replay)
@rrweb/packer         (pack/unpack utilities for rrweb event data)

Plugin System

Plugins live in packages/plugins/ and follow a record/replay pair pattern:

• rrweb-plugin-console-record / rrweb-plugin-console-replay — console logging
• rrweb-plugin-canvas-webrtc-record / rrweb-plugin-canvas-webrtc-replay — canvas via WebRTC
• rrweb-plugin-sequential-id-record / rrweb-plugin-sequential-id-replay — sequential IDs

Build System

• Turbo orchestrates builds via turbo.json with task dependency graph
• Each package uses Vite in library mode (vite.config.default.ts shared config)
• Output formats: ES modules (.js), CommonJS (.cjs), UMD (.umd.cjs), plus TypeScript declarations (.d.ts / .d.cts)
• DISABLE_WORKER_INLINING=true env var disables worker inlining for Chrome extension builds
• Test runner is Vitest (some older packages still use Jest)
• Tests in packages/rrweb use Puppeteer for browser-based integration tests; set PUPPETEER_HEADLESS=true for headless mode

Key Source Paths

• packages/rrweb/src/record/ — recording logic (mutation observer, iframe/shadow-dom managers, canvas observers)
• packages/rrweb/src/replay/ — replay engine (timer, state machine via @xstate/fsm, canvas replay, style injection)
• packages/rrweb/src/entries/record.ts / replay.ts — separate entry points for record-only or replay-only bundles
• packages/rrweb-snapshot/src/snapshot.ts — DOM → serializable data structure
• packages/rrweb-snapshot/src/rebuild.ts — serialized data → DOM reconstruction
• packages/types/src/ — shared event types (eventWithTime, EventType, IncrementalSource)

ESLint Configuration

• Uses @typescript-eslint with type-checked rules
• camelCase rule allows rr_, legacy_, UNSAFE_, __rrweb_ prefixed identifiers
• TSDoc syntax is enforced via eslint-plugin-tsdoc
• Browser compatibility checked via eslint-plugin-compat