Guide · Open source
How to use rrweb: record and replay web sessions
Updated · written with AI from the project's own documentation and checked against our catalogue data
rrweb is an open-source, MIT-licensed TypeScript project that stands for 'record and replay the web'. It captures a page's initial state, then records DOM changes and user interactions so a browser session can be played back later, much like a video. This guide explains how its parts fit together, how to get the source, and where it fits for developers and teams debugging user-reported issues.
rrwebrrweb-io/rrweb · ★ 20.3k · MIT Install options & downloads Quick start
- 1Clone the repository. Run git clone on the rrweb GitHub repository to get the source. Node.js is the listed prerequisite.
- 2Read the contributing guide. Open CONTRIBUTING.md for the current setup, testing and pull request workflow.
- 3Pick the package you need. Use rrweb-snapshot for static copies, record for capturing sessions, replay or rrweb-player for playback.
- 4Review the guide and recipes. Use the official rrweb guide and recipes on the website for current API usage.
- 5Plan privacy masking. Decide which fields and pages to mask before recording real users, using the documentation.
- 6Test with the REPL tool. Use the REPL testing tool described in the guide to check recordings and replays.
What rrweb does and how its parts fit together
rrweb works in two halves. A snapshot of the page is taken first, then changes are recorded as they happen. Playback rebuilds the initial snapshot and replays the recorded events in order.
The project is split into four principal packages. rrweb-snapshot converts the DOM into a serializable structure and can rebuild it. record builds on an initial snapshot to capture mutations and user interactions. replay rebuilds the snapshot and plays back the events. rrweb-player is a GUI on top of replay with pause, fast-forward and drag-to-seek.
- rrweb-snapshot: serialize and rebuild the DOM; can also produce a static HTML 'screenshot' with JavaScript deactivated
- record: capture HTML changes and user interactions; multiple page loads can be chained into one recording
- replay: rebuild the initial snapshot and replay the event list or stream
- rrweb-player: playback UI with pause, fast-forward and drag to any point
Get the rrweb source code
The README's install instruction is to clone the repository. Prerequisites listed for this project are Node.js. The README points to a separate contribution guide for the latest setup, testing and pull request workflow, so follow that file once you have the code.
git clone https://github.com/rrweb-io/rrweb.gitUse the packages in your own project
The packages are the intended integration point for developers adding session replay to a web product. Choose the package that matches your job: record in the page you want to capture, replay or rrweb-player where you watch sessions back.
Read the official guide and recipes on the rrweb website before wiring things up. The README links both, and the guide is the best place for current API usage. Check the installed package's documentation for exact function names rather than relying on memory.
- Recording side: use record with an initial snapshot
- Playback side: use replay or rrweb-player with the recorded events
- Standalone snapshots: use rrweb-snapshot if you only need a static copy of the page
Plan privacy masking before you record
Session replay captures what users see and do, so sensitive pages need planning first. The README excerpt provided does not explain privacy masking, so check the rrweb guide and record package documentation for how to exclude or mask fields before going live.
Treat this as a required step, not an afterthought, for any page with personal or financial data.
Contribute or run the test tooling
rrweb is written in TypeScript so the record and replay sides share a strongly typed data structure. Integration and unit tests are part of the project, and a REPL testing tool is provided. The README links to 'Using the REPL tool' in the guide for how to use it.
- Read the Typescript handbook link in the README if you are new to declaration files
- Internal design docs cover serialization, incremental snapshot, replay and sandbox
What people use it for
- Adding session replay to a web product so developers can watch what a user did before an error
- Debugging a user-reported issue by replaying the page changes and interactions leading up to it
- Building custom replay tooling on an open-source base using the separate packages
- Creating a static HTML snapshot of a page with JavaScript deactivated, using rrweb-snapshot
Frequently asked questions
Is rrweb free to use?
rrweb is released under the MIT licence, as stated in the repository. Check the LICENSE file in the repo for the full terms before using it in a commercial product.
What do I need to install rrweb?
The README lists Node.js as the prerequisite and gives git clone https://github.com/rrweb-io/rrweb.git as the install step. Follow CONTRIBUTING.md for setup details.
Is rrweb a finished analytics product?
No. The README centres on developer packages. A separate hosted rrweb cloud backend is mentioned briefly in the README, but the core project is a set of libraries you integrate yourself.
What is the difference between rrweb-snapshot and rrweb-player?
rrweb-snapshot serializes and rebuilds the DOM, and can produce a static HTML screenshot with JavaScript deactivated. rrweb-player is a GUI built on the replay package with pause, fast-forward and drag controls.
What are alternatives to rrweb?
Projects compared to rrweb in this directory include OpenReplay, PostHog and Sentry Session Replay. Those are more finished products, while rrweb is a set of building blocks.
Can rrweb record sensitive pages safely?
The README excerpt does not explain privacy masking. Plan masking and review what is captured before recording any page with personal or financial data.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
rrweb suits developers who want to add session replay to a product or build their own replay tooling on an MIT-licensed TypeScript base. Teams that want a hosted analytics product with no coding, or that need privacy controls explained up front, should compare OpenReplay, PostHog or Sentry Session Replay first.
Install options & downloads