docs: revamp installation docs for esm and umd (rrweb-io#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>

Author: 3 people

.changeset/docs-install-guidance.md

@@ -0,0 +1,4 @@
+---
+---
+
+Docs-only update: clarify package recommendation order (`@rrweb/record` + `@rrweb/replay` first, `@rrweb/all` as convenience), and fix example typos.

README.zh_CN.md

@@ -11,8 +11,8 @@
 
 [![Join the chat at slack](https://img.shields.io/badge/slack-@rrweb-teal.svg?logo=slack)](https://join.slack.com/t/rrweb/shared_invite/zt-siwoc6hx-uWay3s2wyG8t5GpZVb8rWg)
 [![Reddit](https://img.shields.io/badge/reddit-r/rrweb-teal.svg?logo=reddit)](https://www.reddit.com/r/rrweb)
-![total gzip size](https://img.badgesize.io/https://cdn.jsdelivr.net/npm/rrweb@latest/umd/rrweb.min.js?compression=gzip&label=total%20gzip%20size)
-![recorder gzip size](https://img.badgesize.io/https://cdn.jsdelivr.net/npm/@rrweb/record@latest/umd/record.min.js?compression=gzip&label=recorder%20gzip%20size)
+![recorder gzip size](https://img.badgesize.io/https://cdn.jsdelivr.net/npm/@rrweb/record@latest/umd/record.min.js?compression=gzip&label=recorder%20gzip%20size&max=200000&softmax=100000)
+![replayer gzip size](https://img.badgesize.io/https://cdn.jsdelivr.net/npm/@rrweb/replay@latest/umd/replay.min.js?compression=gzip&label=replayer%20gzip%20size&max=200000&softmax=100000)
 [![](https://data.jsdelivr.com/v1/package/npm/rrweb/badge)](https://www.jsdelivr.com/package/npm/rrweb)
 
 > 我已开通 Github Sponsor， 您可以通过赞助的形式帮助 rrweb 的开发。

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);