Files

Justin Halsall bcf93ca926 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>

2026-02-17 13:59:02 +01:00

3.0 KiB

Raw Blame History

Plugin

The plugin API is designed to extend the function of rrweb without bump the size and complexity of rrweb's core part.

Available plugins

@rrweb/rrweb-plugin-console-record: A plugin for recording console logs.
@rrweb/rrweb-plugin-console-replay: A plugin for replaying console logs.
@rrweb/rrweb-plugin-sequential-id-record: A plugin for recording sequential IDs.
@rrweb/rrweb-plugin-sequential-id-replay: A plugin for replaying sequential IDs.
@rrweb/rrweb-plugin-canvas-webrtc-record: A plugin for stream <canvas> via WebRTC.
@rrweb/rrweb-plugin-canvas-webrtc-replay: A plugin for playing streamed <canvas> via WebRTC.

Interface

Same to with other functionality in rrweb, a plugin can implement record or replay or both features.

export type RecordPlugin<TOptions = unknown> = {
  name: string;
  observer: (cb: Function, options: TOptions) => listenerHandler;
  options: TOptions;
};

export type ReplayPlugin = {
  handler: (
    event: eventWithTime,
    isSync: boolean,
    context: { replayer: Replayer },
  ) => void;
};

Both record and replay plugins have a type interface.

example

record plugin

import { record } from '@rrweb/record';

const exampleRecordPlugin: RecordPlugin<{ foo: string }> = {
  name: 'my-scope/example@1',
  observer(cb, options) {
    const timer = setInterval(() => {
      cb({
        foo: options.foo,
        timestamp: Date.now(),
      });
    }, 1000);
    return () => clearInterval(timer);
  },
  options: {
    foo: 'bar',
  },
};

record({
  emit: emit(event) {},
  plugins: [exampleRecordPlugin],
});

In this example, the record plugin will emit events like this:

{
  type: 6,
  data: {
    plugin: 'my-scope/example@1',
    payload: {
      foo: 'bar',
      timestamp: 1624693882345,
    },
  },
  timestamp: 1624693882345,
}

replay plugin

import { Replayer } from '@rrweb/replay';

const exampleReplayPlugin: ReplayPlugin = {
  handler(event, isSync, context) {
    if (event.type === EventType.Plugin) {
      // do something with event.data.payload
      if (event.data.plugin === 'my-scope/example@1') {
        // handle example plugin data
      }
    }
  },
};

const replayer = new Replayer(events, {
  plugins: [exampleReplayPlugin],
});

A replay plugin can interact with the replayer by using context.replayer.

naming a plugin

A record plugin should have a unique name, and it will be stored in the event it emits.

Since we will have both plugins in the rrweb repo and plugins in users' own codebase, which may cause naming conflicts in the future, we strongly recommended users naming their own plugins in this way:

scope/name@version

For example rrweb/console@1 or github/pr@2.

3.0 KiB Raw Blame History