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

* 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>

docs/recipes/canvas.md

@@ -6,7 +6,9 @@ There are some options for recording and replaying Canvas.
 Enable recording Canvas：
 
 ```js
-rrweb.record({
+import { record } from '@rrweb/record';
+
+record({
   emit(event) {},
   recordCanvas: true,
 });
@@ -15,7 +17,9 @@ rrweb.record({
 Alternatively enable image snapshot recording of Canvas at a maximum of 15 frames per second：
 
 ```js
-rrweb.record({
+import { record } from '@rrweb/record';
+
+record({
   emit(event) {},
   recordCanvas: true,
   sampling: {
@@ -32,7 +36,9 @@ rrweb.record({
 Enable replaying Canvas：
 
 ```js
-const replayer = new rrweb.Replayer(events, {
+import { Replayer } from '@rrweb/replay';
+
+const replayer = new Replayer(events, {
   UNSAFE_replayCanvas: true,
 });
 replayer.play();

docs/recipes/canvas.zh_CN.md

@@ -5,7 +5,9 @@ Canvas 是一种特殊的 HTML 元素，默认情况下其内容不会被 rrweb
 录制时包含 Canvas 内的内容：
 
 ```js
-rrweb.record({
+import { record } from '@rrweb/record';
+
+record({
   emit(event) {},
   // 对 canvas 进行录制
   recordCanvas: true,
@@ -15,7 +17,9 @@ rrweb.record({
 或者启用每秒 15 帧的 Canvas 图像快照记录：
 
 ```js
-rrweb.record({
+import { record } from '@rrweb/record';
+
+record({
   emit(event) {},
   recordCanvas: true,
   sampling: {
@@ -32,7 +36,9 @@ rrweb.record({
 回放时对 Canvas 进行回放：
 
 ```js
-const replayer = new rrweb.Replayer(events, {
+import { Replayer } from '@rrweb/replay';
+
+const replayer = new Replayer(events, {
   UNSAFE_replayCanvas: true,
 });
 replayer.play();

docs/recipes/console.md

@@ -8,10 +8,10 @@ This feature aims to provide developers with more information about the bug scen
 You can enable the logger using default option like this:
 
 ```js
-import rrweb from 'rrweb';
+import { record } from '@rrweb/record';
 import { getRecordConsolePlugin } from '@rrweb/rrweb-plugin-console-record';
 
-rrweb.record({
+record({
   emit: function emit(event) {
     // you should use console.log in this way to avoid errors.
     const defaultLog = console.log['__rrweb_original__']
@@ -30,10 +30,10 @@ You should call console.log.\_\_rrweb_original\_\_() instead.
 You can also customize the behavior of logger like this:
 
 ```js
-import rrweb from 'rrweb';
+import { record } from '@rrweb/record';
 import { getRecordConsolePlugin } from '@rrweb/rrweb-plugin-console-record';
 
-rrweb.record({
+record({
   emit: function emit(event) {
     // you should use console.log in this way to avoid errors.
     const defaultLog = console.log['__rrweb_original__']
@@ -70,10 +70,10 @@ All options are described below:
 If recorded events include data of console log type, we will automatically play them.
 
 ```js
-import rrweb from 'rrweb';
+import { Replayer } from '@rrweb/replay';
 import { getReplayConsolePlugin } from '@rrweb/rrweb-plugin-console-replay';
 
-const replayer = new rrweb.Replayer(events, {
+const replayer = new Replayer(events, {
   plugins: [
     getReplayConsolePlugin({
       level: ['info', 'log', 'warn', 'error'],

docs/recipes/console.zh_CN.md

@@ -7,10 +7,10 @@
 可以通过如下代码使用默认的配置选项
 
 ```js
-import rrweb from 'rrweb';
+import { record } from '@rrweb/record';
 import { getRecordConsolePlugin } from '@rrweb/rrweb-plugin-console-record';
 
-rweb.record({
+record({
   emit: function emit(event) {
     // 如果要使用console来输出信息，请使用如下的写法
     const defaultLog = console.log['__rrweb_original__']
@@ -29,10 +29,10 @@ rweb.record({
 你也可以定制录制 console 的选项
 
 ```js
-import rrweb from 'rrweb';
+import { record } from '@rrweb/record';
 import { getRecordConsolePlugin } from '@rrweb/rrweb-plugin-console-record';
 
-rrweb.record({
+record({
   emit: function emit(event) {
     // 如果要使用console来输出信息，请使用如下的写法
     const defaultLog = console.log['__rrweb_original__']
@@ -69,10 +69,10 @@ rrweb.record({
 如果 replayer 传入的 events 中包含了 console 类型的数据，我们将自动播放这些数据。
 
 ```js
-import rrweb from 'rrweb';
+import { Replayer } from '@rrweb/replay';
 import { getReplayConsolePlugin } from '@rrweb/rrweb-plugin-console-replay';
 
-const replayer = new rrweb.Replayer(events, {
+const replayer = new Replayer(events, {
   plugins: [
     getReplayConsolePlugin({
       level: ['info', 'log', 'warn', 'error'],

docs/recipes/cross-origin-iframes.md

@@ -8,7 +8,9 @@ Since if you allow recording cross origin iframes, any malicious website can emb
 Enable recording cross-origin iframes in your parent page:
 
 ```js
-rrweb.record({
+import { record } from '@rrweb/record';
+
+record({
   emit(event) {}, // all events will be emitted here, including events from cross origin iframes
   recordCrossOriginIframes: true,
 });
@@ -17,7 +19,9 @@ rrweb.record({
 Enable replaying cross-origin iframes in your child page:
 
 ```js
-rrweb.record({
+import { record } from '@rrweb/record';
+
+record({
   emit(event) {}, // this is required for rrweb, but the child page will not emit any events
   recordCrossOriginIframes: true,
 });

docs/recipes/cross-origin-iframes.zh_CN.md

@@ -8,7 +8,9 @@
 在父页面中启用录制跨域 iframe:
 
 ```js
-rrweb.record({
+import { record } from '@rrweb/record';
+
+record({
   emit(event) {}, // 所有事件都将在此处发出，包括来自跨源 iframe 的事件
   recordCrossOriginIframes: true,
 });
@@ -17,7 +19,9 @@ rrweb.record({
 在您的子页面中启用重放跨域 iframe:
 
 ```js
-rrweb.record({
+import { record } from '@rrweb/record';
+
+record({
   emit(event) {}, // 这是 rrweb 所必需的，但子页面不会发出任何事件
   recordCrossOriginIframes: true,
 });

docs/recipes/custom-event.md

@@ -5,19 +5,21 @@ You may need to record some custom events along with the rrweb events, and let t
 After starting the recording, we can call the `record.addCustomEvent` API to add a custom event.
 
 ```js
+import { record } from '@rrweb/record';
+
 // start recording
-rrweb.record({
+record({
   emit(event) {
     ...
   }
 })
 
 // record some custom events at any time
-rrweb.record.addCustomEvent('submit-form', {
+record.addCustomEvent('submit-form', {
   name: 'Adam',
   age: 18
 })
-rrweb.record.addCustomEvent('some-error', {
+record.addCustomEvent('some-error', {
   error
 })
 ```
@@ -29,7 +31,9 @@ During the replay, we can add an event listener to custom events, or configure t
 **Listen to custom events**
 
 ```js
-const replayer = new rrweb.Replayer(events);
+import { Replayer } from '@rrweb/replay';
+
+const replayer = new Replayer(events);
 
 replayer.on('custom-event', (event) => {
   console.log(event.tag, event.payload);

docs/recipes/custom-event.zh_CN.md

@@ -5,19 +5,21 @@
 开始录制后，我们就可以通过 `record.addCustomEvent` API 添加自定义事件：
 
 ```js
+import { record } from '@rrweb/record';
+
 // 开始录制
-rrweb.record({
+record({
   emit(event) {
     ...
   }
 })
 
 // 在开始录制后的任意时间点记录自定义事件，例如：
-rrweb.record.addCustomEvent('submit-form', {
+record.addCustomEvent('submit-form', {
   name: '姓名',
   age: 18
 })
-rrweb.record.addCustomEvent('some-error', {
+record.addCustomEvent('some-error', {
   error
 })
 ```
@@ -29,7 +31,9 @@ rrweb.record.addCustomEvent('some-error', {
 **获取对应事件**
 
 ```js
-const replayer = new rrweb.Replayer(events);
+import { Replayer } from '@rrweb/replay';
+
+const replayer = new Replayer(events);
 
 replayer.on('custom-event', (event) => {
   console.log(event.tag, event.payload);

docs/recipes/customize-replayer.md

@@ -1,13 +1,13 @@
 # Customize the Replayer
 
-When rrweb's Replayer and the [rrweb-player](../../packages/rrweb-player/) UI do not fit your need, you can customize your replayer UI.
+When `Replayer` and the [rrweb-player](../../packages/rrweb-player/) UI do not fit your need, you can customize your replayer UI.
 
 There are several ways to do this:
 
 1. Use [rrweb-player](../../packages/rrweb-player/), and customize its CSS.
 2. Use [rrweb-player](../../packages/rrweb-player/), and set `showController: false` to hide the controller UI. With this config, you can implement your controller UI.
 3. Use the `insertStyleRules` options to inject some CSS into the replay iframe.
-4. Develop a new replayer UI with rrweb's Replayer.
+4. Develop a new replayer UI with `Replayer`.
 
 ## Implement Your Controller UI
 
@@ -69,6 +69,6 @@ rrwebPlayer.addEventListener('ui-update-progress', (event) => {
 });
 ```
 
-## Develop a new replayer UI with rrweb's Replayer.
+## Develop a new replayer UI with `Replayer`.
 
 Please refer [rrweb-player](https://github.com/rrweb-io/rrweb/tree/master/packages/rrweb-player/).

docs/recipes/customize-replayer.zh_CN.md

@@ -1,13 +1,13 @@
 # 自定义回放 UI
 
-当 rrweb Replayer 和 [rrweb-player](../../packages/rrweb-player/) 的 UI 不能满足需求时，可以通过自定义回放 UI 制作属于你自己的回放器。
+当 `Replayer` 和 [rrweb-player](../../packages/rrweb-player/) 的 UI 不能满足需求时，可以通过自定义回放 UI 制作属于你自己的回放器。
 
 你可以通过以下几种方式从不同角度自定义回放 UI：
 
 1. 使用 [rrweb-player](../../packages/rrweb-player/) 时，通过覆盖 CSS 样式表定制 UI。
 2. 使用 [rrweb-player](../../packages/rrweb-player/) 时，通过 `showController: false` 隐藏控制器 UI，重新实现控制器 UI。
 3. 通过 `insertStyleRules` 在回放页面（iframe）内定制 CSS 样式。
-4. 基于 rrweb Replayer 开发自己的回放器 UI。
+4. 基于 `Replayer` 开发自己的回放器 UI。
 
 ## 实现控制器 UI
 
@@ -69,6 +69,6 @@ rrwebPlayer.addEventListener('ui-update-progress', (event) => {
 });
 ```
 
-## 基于 rrweb Replayer 开发自己的回放器 UI
+## 基于 `Replayer` 开发自己的回放器 UI
 
 可以参照 [rrweb-player](https://github.com/rrweb-io/rrweb/tree/master/packages/rrweb-player/) 的方式进行开发。

docs/recipes/index.md

@@ -42,7 +42,7 @@ By default, the UI could not interact during replay. But you can use API to enab
 
 ### Customize The Replayer
 
-When rrweb's Replayer and the rrweb-player UI do not fit your need, you can customize your own replayer UI.
+When `Replayer` and the rrweb-player UI do not fit your need, you can customize your own replayer UI.
 
 [link](./customize-replayer.md)
 

docs/recipes/index.zh_CN.md

@@ -42,7 +42,7 @@
 
 ### 自定义回放 UI
 
-当 rrweb Replayer 和 rrweb-player 的 UI 不能满足需求时，可以通过自定义回放 UI 制作属于你自己的回放器。
+当 `Replayer` 和 rrweb-player 的 UI 不能满足需求时，可以通过自定义回放 UI 制作属于你自己的回放器。
 
 [链接](./customize-replayer.zh_CN.md)
 

docs/recipes/interaction.md

@@ -3,7 +3,9 @@
 By default, the UI could not interact during replay. But you can use API to enable/disable this programmatically.
 
 ```js
-const replayer = new rrweb.Replayer(events);
+import { Replayer } from '@rrweb/replay';
+
+const replayer = new Replayer(events);
 
 // enable user interact with the UI
 replayer.enableInteract();

docs/recipes/interaction.zh_CN.md

@@ -3,7 +3,9 @@
 回放时的 UI 默认不可交互，但在特定场景下也可以通过 API 允许用户与回放场景进行交互。
 
 ```js
-const replayer = new rrweb.Replayer(events);
+import { Replayer } from '@rrweb/replay';
+
+const replayer = new Replayer(events);
 
 // 允许用户在回放的 UI 中进行交互
 replayer.enableInteract();

docs/recipes/live-mode.md

@@ -2,10 +2,12 @@
 
 If you want to replay the events in a real-time way, you can use the live mode API. This API is also useful for some real-time collaboration usage.
 
-When you are using rrweb's Replayer to do a real-time replay, you need to configure `liveMode: true` and call the `startLive` API to enable the live mode.
+When you use `Replayer` for real-time replay, configure `liveMode: true` and call `startLive()` to enable live mode.
 
 ```js
-const replayer = new rrweb.Replayer([], {
+import { Replayer } from '@rrweb/replay';
+
+const replayer = new Replayer([], {
   liveMode: true,
 });
 replayer.startLive();
@@ -22,7 +24,9 @@ function onReceive(event) {
 If you have an ongoing recording that already has events, and wish to initiate play from a 'live' time, it's also possible to use the `play` function, supplied with an offset which corresponds to the current time:
 
 ```js
-const replayer = new rrweb.Replayer(EXISTING_EVENTS, {
+import { Replayer } from '@rrweb/replay';
+
+const replayer = new Replayer(EXISTING_EVENTS, {
   liveMode: true,
 });
 replayer.play(Date.now() - EXISTING_EVENTS[0].timestamp);

docs/recipes/live-mode.zh_CN.md

@@ -2,10 +2,12 @@
 
 如果希望持续、实时地看到录制的数据，达到类似直播的效果，则可以使用实时回放 API。这个方式也适用于一些实时协同的场景。
 
-使用 rrweb Replayer 进行实时回放时，需要传入 `liveMode: true` 配置，并通过 `startLive` API 启动直播模式。
+使用 `Replayer` 进行实时回放时，需要传入 `liveMode: true` 配置，并通过 `startLive` API 启动直播模式。
 
 ```js
-const replayer = new rrweb.Replayer([], {
+import { Replayer } from '@rrweb/replay';
+
+const replayer = new Replayer([], {
   liveMode: true,
 });
 

docs/recipes/optimize-storage.md

@@ -26,7 +26,9 @@ Use the sampling config in the recording can reduce the storage size by dropping
 **Scenario 1**
 
 ```js
-rrweb.record({
+import { record } from '@rrweb/record';
+
+record({
   emit(event) {},
   sampling: {
     // do not record mouse movement
@@ -46,7 +48,9 @@ rrweb.record({
 **Scenario 2**
 
 ```js
-rrweb.record({
+import { record } from '@rrweb/record';
+
+record({
   emit(event) {},
   sampling: {
     // Configure which kinds of mouse interaction should be recorded
@@ -76,7 +80,7 @@ You can use it by passing it as the `packFn` in the recording.
 ```js
 import { pack } from '@rrweb/packer';
 
-rrweb.record({
+record({
   emit(event) {},
   packFn: pack,
 });
@@ -86,8 +90,9 @@ And you need to pass packer.unpack as the `unpackFn` in replaying.
 
 ```js
 import { unpack } from '@rrweb/packer';
+import { Replayer } from '@rrweb/replay';
 
-const replayer = new rrweb.Replayer(events, {
+const replayer = new Replayer(events, {
   unpackFn: unpack,
 });
 ```

docs/recipes/optimize-storage.zh_CN.md

@@ -26,7 +26,9 @@
 **示例 1**
 
 ```js
-rrweb.record({
+import { record } from '@rrweb/record';
+
+record({
   emit(event) {},
   sampling: {
     // 不录制鼠标移动事件
@@ -46,7 +48,9 @@ rrweb.record({
 **示例 2**
 
 ```js
-rrweb.record({
+import { record } from '@rrweb/record';
+
+record({
   emit(event) {},
   sampling: {
     // 定义不录制的鼠标交互事件类型，可以细粒度的开启或关闭对应交互录制
@@ -74,9 +78,9 @@ rrweb 提供了一个基于 fflate 的简单压缩函数，在 [@rrweb/packer](.
 ```js
 import { pack } from '@rrweb/packer';
 
-rrweb.record({
+record({
   emit(event) {},
-  packFn: rrweb.pack,
+  packFn: pack,
 });
 ```
 
@@ -84,9 +88,10 @@ rrweb.record({
 
 ```js
 import { unpack } from '@rrweb/packer';
+import { Replayer } from '@rrweb/replay';
 
-const replayer = new rrweb.Replayer(events, {
-  unpackFn: rrweb.unpack,
+const replayer = new Replayer(events, {
+  unpackFn: unpack,
 });
 ```
 

docs/recipes/pagination.md

@@ -5,7 +5,9 @@ When the size of the recorded events increased, load them in one request is not
 rrweb's API for loading async events is quite simple:
 
 ```js
-const replayer = new rrweb.Replayer(events);
+import { Replayer } from '@rrweb/replay';
+
+const replayer = new Replayer(events);
 
 replayer.addEvent(NEW_EVENT);
 ```
@@ -15,7 +17,9 @@ When calling the `addEvent` API to add a new event, rrweb will resolve its times
 If you need to load several events, you can do a loop like this:
 
 ```js
-const replayer = new rrweb.Replayer(events);
+import { Replayer } from '@rrweb/replay';
+
+const replayer = new Replayer(events);
 
 for (const event of NEW_EVENTS) {
   replayer.addEvent(event);

docs/recipes/pagination.zh_CN.md

@@ -5,7 +5,9 @@
 rrweb 中用于实现异步加载数据的 API 非常简单直观：
 
 ```js
-const replayer = new rrweb.Replayer(events);
+import { Replayer } from '@rrweb/replay';
+
+const replayer = new Replayer(events);
 
 replayer.addEvent(NEW_EVENT);
 ```
@@ -15,7 +17,9 @@ replayer.addEvent(NEW_EVENT);
 如果需要异步加载多个数据，只需这样使用：
 
 ```js
-const replayer = new rrweb.Replayer(events);
+import { Replayer } from '@rrweb/replay';
+
+const replayer = new Replayer(events);
 
 for (const event of NEW_EVENTS) {
   replayer.addEvent(event);

docs/recipes/plugin.md

@@ -38,6 +38,8 @@ Both record and replay plugins have a type interface.
 #### record plugin
 
 ```ts
+import { record } from '@rrweb/record';
+
 const exampleRecordPlugin: RecordPlugin<{ foo: string }> = {
   name: 'my-scope/example@1',
   observer(cb, options) {
@@ -54,7 +56,7 @@ const exampleRecordPlugin: RecordPlugin<{ foo: string }> = {
   },
 };
 
-rrweb.record({
+record({
   emit: emit(event) {},
   plugins: [exampleRecordPlugin],
 });
@@ -79,6 +81,8 @@ In this example, the record plugin will emit events like this:
 #### replay plugin
 
 ```ts
+import { Replayer } from '@rrweb/replay';
+
 const exampleReplayPlugin: ReplayPlugin = {
   handler(event, isSync, context) {
     if (event.type === EventType.Plugin) {
@@ -90,7 +94,7 @@ const exampleReplayPlugin: ReplayPlugin = {
   },
 };
 
-const replayer = new rrweb.Replayer(events, {
+const replayer = new Replayer(events, {
   plugins: [exampleReplayPlugin],
 });
 ```

docs/recipes/plugin.zh_CN.md

@@ -38,6 +38,8 @@ export type ReplayPlugin = {
 #### 录制侧插件
 
 ```ts
+import { record } from '@rrweb/record';
+
 const exampleRecordPlugin: RecordPlugin<{ foo: string }> = {
   name: 'my-scope/example@1',
   observer(cb, options) {
@@ -54,7 +56,7 @@ const exampleRecordPlugin: RecordPlugin<{ foo: string }> = {
   },
 };
 
-rrweb.record({
+record({
   emit: emit(event) {},
   plugins: [exampleRecordPlugin],
 });
@@ -79,6 +81,8 @@ rrweb.record({
 #### 回放侧插件
 
 ```ts
+import { Replayer } from '@rrweb/replay';
+
 const exampleReplayPlugin: ReplayPlugin = {
   handler(event, isSync, context) {
     if (event.type === EventType.Plugin) {
@@ -90,7 +94,7 @@ const exampleReplayPlugin: ReplayPlugin = {
   },
 };
 
-const replayer = new rrweb.Replayer(events, {
+const replayer = new Replayer(events, {
   plugins: [exampleReplayPlugin],
 });
 ```

docs/recipes/record-and-replay.md

@@ -5,7 +5,9 @@ Record and Replay is the most common use case, which is suitable for any scenari
 You only need a simple API call to record the website:
 
 ```js
-const stopFn = rrweb.record({
+import { record } from '@rrweb/record';
+
+const stopFn = record({
   emit(event) {
     // save the event
   },
@@ -21,11 +23,13 @@ But you should guarantee:
 
 You can use the `stopFn` to stop the recording.
 
-The replay is also as simple as putting events into rrweb's Replayer.
+Replay is also as simple as passing events into `Replayer`.
 
 ```js
+import { Replayer } from '@rrweb/replay';
+
 const events = GET_YOUR_EVENTS;
 
-const replayer = new rrweb.Replayer(events);
+const replayer = new Replayer(events);
 replayer.play();
 ```

docs/recipes/record-and-replay.zh_CN.md

@@ -5,7 +5,9 @@
 仅需一个函数调用就可以录制当前页面：
 
 ```js
-const stopFn = rrweb.record({
+import { record } from '@rrweb/record';
+
+const stopFn = record({
   emit(event) {
     // 保存获取到的 event 数据
   },
@@ -19,11 +21,13 @@ const stopFn = rrweb.record({
 
 如果需要手动停止录制，可以调用返回的 `stopFn` 函数。
 
-回放时只需要获取一段录制数据，并传入 rrweb 提供的 Replayer：
+回放时只需要获取一段录制数据，并传入 `Replayer`：
 
 ```js
+import { Replayer } from '@rrweb/replay';
+
 const events = GET_YOUR_EVENTS;
 
-const replayer = new rrweb.Replayer(events);
+const replayer = new Replayer(events);
 replayer.play();
 ```