xuguopeng/rrweb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: revamp installation docs for esm and umd (#1788)

Browse Source 
* docs: revamp installation docs for esm and umd

Document recommended install paths across the main guides and package
READMEs for rrweb, @rrweb/all, @rrweb/record, @rrweb/replay, and
rrweb-player.

Clarify three usage modes: bundler/npm, browser no-build with
import maps and +esm, and legacy UMD fallback.

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Apply formatting changes

* Apply suggestion from @eoghanmurray

Co-authored-by: Eoghan Murray <eoghan@getthere.ie>

* Apply formatting changes

* docs(all): streamline README usage section

Move the guide link next to the import example and remove the
duplicated Usage section to keep docs concise and easier to scan.

* docs(readme): update gzip size badges in zh-cn readme

* docs(plugins): update readme imports to scoped esm packages

Replace `rrweb` default imports and `rrweb.Replayer` usage with
`@rrweb/record` `record` and `@rrweb/replay` `Replayer` in plugin
usage examples.

Also update canvas WebRTC plugin imports to scoped `@rrweb/*`
package names to keep docs aligned with current package structure.

* docs: update docs to prefer scoped esm packages

replace `rrweb` default import examples with `@rrweb/record` and
`@rrweb/replay` across recipes and guides in en/zh-CN.

clarify package selection for new integrations, add `@rrweb/all`
convenience guidance, and refresh CDN/style import snippets for ESM and legacy UMD compatibility.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Eoghan Murray <eoghan@getthere.ie>
This commit is contained in:
Justin Halsall
2026-04-01 12:00:00 +08:00
committed by GitHub
parent 1b6a8be870
commit aab4c553cb
37 changed files with 667 additions and 217 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
packages/all/README.md
View File

@@ -1,6 +1,15 @@
# @rrweb/all
Convenience package that includes a bundle of rrweb packages.
For most new integrations, prefer `@rrweb/record` + `@rrweb/replay` first, and use `@rrweb/all` when you want a single-package setup.
| Use case | Package choice |
| --------------------------------------------------- | --------------------------------- |
| Most new apps (explicit record/replay dependencies) | `@rrweb/record` + `@rrweb/replay` |
| Quick setup with one import | `@rrweb/all` |
| Legacy compatibility | `rrweb` |
In most production setups, recorder and replayer are deployed to different pages/apps. Use `@rrweb/record` on recorded pages and `@rrweb/replay` (or `rrweb-player`) on replay pages. Use `@rrweb/all` when you intentionally want one package for convenience (for example demos, tooling, or simplified setups).
Includes the following packages:
@@ -11,19 +20,47 @@ Includes the following packages:
## Installation
### 1) Bundler / npm
```bash
npm install @rrweb/all
```
## Usage
```js
import { record, replay, pack, unpack } from '@rrweb/all';
// use record, replay, pack, unpack as you would with the individual packages.
import { record, Replayer, pack, unpack } from '@rrweb/all';
import '@rrweb/all/dist/style.css';
```
See the [guide](../../guide.md) for more info on rrweb.
For API details and examples, see the [guide](../../guide.md).
### 2) Browser Without Bundler (ESM + import maps)
```html
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@rrweb/all@latest/dist/style.css"
/>
<script type="importmap">
{
"imports": {
"@rrweb/all": "https://cdn.jsdelivr.net/npm/@rrweb/all@latest/+esm"
}
}
</script>
<script type="module">
import { record, Replayer, pack, unpack } from '@rrweb/all';
</script>
```
### 3) Legacy Direct `<script>` Include (UMD fallback)
Use this only for compatibility with non-module environments.
```html
<script src="https://cdn.jsdelivr.net/npm/@rrweb/all@latest/umd/all.min.js"></script>
```
The legacy UMD global is `rrweb`, so you will need to prefix the example APIs, e.g. `rrweb.record`, `new rrweb.Replayer(...)`, `rrweb.pack`, and `rrweb.unpack`, rather than using these functions directly.
## Sponsors

12
packages/plugins/rrweb-plugin-canvas-webrtc-record/Readme.md
View File

@@ -13,8 +13,8 @@ https://user-images.githubusercontent.com/4106/186701616-fd71a107-5d53-423c-ba09
```js
// Record side
import rrweb from 'rrweb';
import { RRWebPluginCanvasWebRTCRecord } from 'rrweb-plugin-canvas-webrtc-record';
import { record } from '@rrweb/record';
import { RRWebPluginCanvasWebRTCRecord } from '@rrweb/rrweb-plugin-canvas-webrtc-record';
const webRTCRecordPlugin = new RRWebPluginCanvasWebRTCRecord({
signalSendCallback: (msg) => {
@@ -24,7 +24,7 @@ const webRTCRecordPlugin = new RRWebPluginCanvasWebRTCRecord({
},
});
rrweb.record({
record({
emit: (event) => {
// send these events to the `replayer.addEvent(event)`, how you do that is up to you
// you can send them to a server for example which can then send them to the replayer
@@ -42,8 +42,8 @@ rrweb.record({
```js
// Replay side
import rrweb from 'rrweb';
import { RRWebPluginCanvasWebRTCReplay } from 'rrweb-plugin-canvas-webrtc-replay';
import { Replayer } from '@rrweb/replay';
import { RRWebPluginCanvasWebRTCReplay } from '@rrweb/rrweb-plugin-canvas-webrtc-replay';
const webRTCReplayPlugin = new RRWebPluginCanvasWebRTCReplay({
canvasFoundCallback(canvas, context) {
@@ -59,7 +59,7 @@ const webRTCReplayPlugin = new RRWebPluginCanvasWebRTCReplay({
},
});
const replayer = new rrweb.Replayer([], {
const replayer = new Replayer([], {
UNSAFE_replayCanvas: true, // turn canvas replay on!
liveMode: true, // live mode is needed to stream events to the replayer
plugins: [webRTCReplayPlugin.initPlugin()],

8
packages/plugins/rrweb-plugin-canvas-webrtc-replay/Readme.md
View File

@@ -13,7 +13,7 @@ https://user-images.githubusercontent.com/4106/186701616-fd71a107-5d53-423c-ba09
```js
// Record side
import rrweb from 'rrweb';
import { record } from '@rrweb/record';
import { RRWebPluginCanvasWebRTCRecord } from '@rrweb/rrweb-plugin-canvas-webrtc-record';
const webRTCRecordPlugin = new RRWebPluginCanvasWebRTCRecord({
@@ -24,7 +24,7 @@ const webRTCRecordPlugin = new RRWebPluginCanvasWebRTCRecord({
},
});
rrweb.record({
record({
emit: (event) => {
// send these events to the `replayer.addEvent(event)`, how you do that is up to you
// you can send them to a server for example which can then send them to the replayer
@@ -42,7 +42,7 @@ rrweb.record({
```js
// Replay side
import rrweb from 'rrweb';
import { Replayer } from '@rrweb/replay';
import { RRWebPluginCanvasWebRTCReplay } from '@rrweb/rrweb-plugin-canvas-webrtc-replay';
const webRTCReplayPlugin = new RRWebPluginCanvasWebRTCReplay({
@@ -59,7 +59,7 @@ const webRTCReplayPlugin = new RRWebPluginCanvasWebRTCReplay({
},
});
const replayer = new rrweb.Replayer([], {
const replayer = new Replayer([], {
UNSAFE_replayCanvas: true, // turn canvas replay on!
liveMode: true, // live mode is needed to stream events to the replayer
plugins: [webRTCReplayPlugin.initPlugin()],

4
packages/plugins/rrweb-plugin-sequential-id-record/README.md
View File

@@ -12,10 +12,10 @@ npm install @rrweb/rrweb-plugin-sequential-id-record
## Usage
```js
import rrweb from 'rrweb';
import { record } from '@rrweb/record';
import { getRecordSequentialIdPlugin } from '@rrweb/rrweb-plugin-sequential-id-record';
rrweb.record({
record({
emit: function emit(event) {
// send events to server
},

4
packages/plugins/rrweb-plugin-sequential-id-replay/README.md
View File

@@ -12,10 +12,10 @@ npm install @rrweb/rrweb-plugin-sequential-id-replay
## Usage
```js
import rrweb from 'rrweb';
import { Replayer } from '@rrweb/replay';
import { getReplaySequentialIdPlugin } from '@rrweb/rrweb-plugin-sequential-id-replay';
const replayer = new rrweb.Replayer(events, {
const replayer = new Replayer(events, {
plugins: [
getReplaySequentialIdPlugin({
// make sure this is the same as the record side

31
packages/record/README.md
View File

@@ -5,10 +5,41 @@ See the [guide](../../guide.md) for more info on rrweb.
## Installation
### 1) Bundler / npm (Recommended)
```bash
npm install @rrweb/record
```
```js
import { record } from '@rrweb/record';
```
### 2) Browser Without Bundler (ESM + import maps)
```html
<script type="importmap">
{
"imports": {
"@rrweb/record": "https://cdn.jsdelivr.net/npm/@rrweb/record@latest/+esm"
}
}
</script>
<script type="module">
import { record } from '@rrweb/record';
</script>
```
### 3) Legacy Direct `<script>` Include (UMD fallback)
Use this only for compatibility with non-module environments.
```html
<script src="https://cdn.jsdelivr.net/npm/@rrweb/record@latest/umd/record.min.js"></script>
```
The legacy UMD global is `rrwebRecord`.
## Usage
```js

41
packages/replay/README.md
View File

@@ -5,14 +5,55 @@ See the [guide](../../guide.md) for more info on rrweb.
## Installation
### 1) Bundler / npm (Recommended)
```bash
npm install @rrweb/replay
```
```js
import { Replayer } from '@rrweb/replay';
import '@rrweb/replay/dist/style.css';
```
### 2) Browser Without Bundler (ESM + import maps)
```html
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@rrweb/replay@latest/dist/style.css"
/>
<script type="importmap">
{
"imports": {
"@rrweb/replay": "https://cdn.jsdelivr.net/npm/@rrweb/replay@latest/+esm"
}
}
</script>
<script type="module">
import { Replayer } from '@rrweb/replay';
</script>
```
### 3) Legacy Direct `<script>` Include (UMD fallback)
Use this only for compatibility with non-module environments.
```html
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@rrweb/replay@latest/dist/style.css"
/>
<script src="https://cdn.jsdelivr.net/npm/@rrweb/replay@latest/umd/replay.min.js"></script>
```
The legacy UMD global is `rrwebReplay`.
## Usage
```js
import { Replayer } from '@rrweb/replay';
import '@rrweb/replay/dist/style.css';
const replayer = new Replayer(events, {
// options

39
packages/rrweb-player/README.md
View File

@@ -12,25 +12,46 @@ rrweb-player uses rrweb's Replayer under the hood, but as Replayer doesn't inclu
## Installation
rrweb-player can also be included with `<script>`：
### 1) Bundler / npm (Recommended)
```shell
npm install rrweb-player
```
```js
import rrwebPlayer from 'rrweb-player';
import 'rrweb-player/dist/style.css';
```
### 2) Browser Without Bundler (ESM + import maps)
```html
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/rrweb-player@latest/dist/style.css"
/>
<script src="https://cdn.jsdelivr.net/npm/rrweb-player@latest/umd/rrweb-player.js"></script>
<script type="importmap">
{
"imports": {
"rrweb-player": "https://cdn.jsdelivr.net/npm/rrweb-player@latest/+esm"
}
}
</script>
<script type="module">
import rrwebPlayer from 'rrweb-player';
</script>
```
Or installed by using NPM：
### 3) Legacy Direct `<script>` Include (UMD fallback)
```shell
npm install --save rrweb-player
```
Use this only for compatibility with non-module environments.
```js
import rrwebPlayer from 'rrweb-player';
import 'rrweb-player/dist/style.css';
```html
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/rrweb-player@latest/dist/style.css"
/>
<script src="https://cdn.jsdelivr.net/npm/rrweb-player@latest/umd/rrweb-player.min.js"></script>
```
## Usage

75
packages/rrweb/README.md
View File

@@ -19,12 +19,85 @@ rrweb refers to 'record and replay the web', which is a tool for recording and r
[**🍳 Recipes 🍳**](../../docs/recipes/index.md)
## Installation
`rrweb` is kept mainly for backward compatibility. For new integrations, prefer package-specific entrypoints (`@rrweb/record` and `@rrweb/replay`) first, or use `@rrweb/all` as a convenience package.
### 1) Bundler / npm (Recommended)
For new projects:
```shell
npm install @rrweb/record @rrweb/replay
```
```js
import { record } from '@rrweb/record';
import { Replayer } from '@rrweb/replay';
import '@rrweb/replay/dist/style.css';
```
Convenience single-package option:
```shell
npm install @rrweb/all
```
```js
import { record, Replayer, pack, unpack } from '@rrweb/all';
import '@rrweb/all/dist/style.css';
```
Legacy compatibility package:
```shell
npm install rrweb
```
```js
import { record, Replayer } from 'rrweb';
import 'rrweb/dist/style.css';
```
### 2) Browser Without Bundler (ESM + import maps)
```html
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@rrweb/replay@latest/dist/style.css"
/>
<script type="importmap">
{
"imports": {
"@rrweb/record": "https://cdn.jsdelivr.net/npm/@rrweb/record@latest/+esm",
"@rrweb/replay": "https://cdn.jsdelivr.net/npm/@rrweb/replay@latest/+esm"
}
}
</script>
<script type="module">
import { record } from '@rrweb/record';
import { Replayer } from '@rrweb/replay';
</script>
```
### 3) Legacy Direct `<script>` Include (UMD fallback)
Use this only for compatibility with non-module environments; modern browsers support the importmap method [since 2023](https://caniuse.com/?search=import+map)
```html
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/rrweb@latest/dist/style.css"
/>
<script src="https://cdn.jsdelivr.net/npm/rrweb@latest/umd/rrweb.min.js"></script>
```
## Project Structure
**[rrweb](https://github.com/rrweb-io/rrweb)** mainly includes two funtions:
- **Record**: The record function is used to record all the mutations in the DOM
- **Replay**: The replay function is to replay the recorded mutations one by one according to the corresponding timestamp.
- **Replayer**: The replay function is to replay the recorded mutations one by one according to the corresponding timestamp.
## Roadmap