Standardize UMD global API strategy across rrweb packages

[Juice10]

Problem

UMD usage is inconsistent across packages today. Some packages use a shared global (window.rrweb), while others use package-specific globals. This causes API confusion and load-order instability.

Why this matters

• Script-tag consumers can get different behavior depending on bundle load order.
• Docs and examples become hard to keep consistent.
• It is unclear whether UMD should optimize for shared namespace ergonomics or package isolation.

Current behavior (verified, post-PR #1762)

1. Core modular packages currently use the same UMD global name:

• @rrweb/all -> rrweb

2. Many other packages use package-specific globals:

• rrweb-player -> rrwebPlayer
• rrdom -> rrdom
• rrdom-nodejs -> rrdomNodejs
• rrweb-snapshot -> rrwebSnapshot
• @rrweb/record -> rrwebRecord
• @rrweb/replay -> rrwebReplay
• @rrweb/types -> rrwebTypes
• @rrweb/utils -> rrwebUtils
• plugins -> rrwebPlugin...

Timeline relative to PR #1762

Reference: #1762

Before PR #1762:

• UMD behavior was already mixed across packages.
• Strategy 1 (see below) was effectively used for @rrweb/all, @rrweb/record, @rrweb/replay.
• Strategy 2 (see below) was effectively used for most other packages.
• Shared-global overwrite happens in practice:
  • Load @rrweb/record UMD first -> rrweb.record exists.
  • Load @rrweb/replay UMD second -> rrweb.Replayer exists, and rrweb.record is gone.
  • This is effectively “last one wins” for shared-global bundles.

After PR #1762 (current state):

• Directionally, the project is moving toward package-specific globals for modular packages.
• Mixed behavior/config still exists in practice.
• See the Current behavior section above for the exact verified package matrix.

Target state:

• One explicit, documented UMD policy across all packages.
• Build config and runtime behavior match that policy consistently.
• Docs/examples and tests enforce the selected behavior.

API matrix discussed

Package	Strategy 1: Shared-global model	Stategy 2: Package-specific model	Strategy 3: Hybrid model
rrweb	window.rrweb.record, window.rrweb.Replayer	window.rrweb.record, window.rrweb.Replayer	window.rrweb.record, window.rrweb.Replayer
@rrweb/all	window.rrweb.record, window.rrweb.Replayer, window.rrweb.pack, window.rrweb.unpack	window.rrwebAll.record, window.rrwebAll.Replayer, window.rrwebAll.pack, window.rrwebAll.unpack	window.rrweb.record, window.rrweb.Replayer, window.rrweb.pack, window.rrweb.unpack
@rrweb/record	window.rrweb.record, window.rrweb.record.addCustomEvent, window.rrweb.record.freezePage, window.rrweb.record.takeFullSnapshot	window.rrwebRecord.record, window.rrwebRecord.addCustomEvent, window.rrwebRecord.freezePage, window.rrwebRecord.takeFullSnapshot	window.rrwebRecord.record, window.rrwebRecord.addCustomEvent, window.rrwebRecord.freezePage, window.rrwebRecord.takeFullSnapshot
@rrweb/replay	window.rrweb.Replayer	window.rrwebReplay.Replayer	window.rrwebReplay.Replayer
@rrweb/packer	window.rrweb.pack, window.rrweb.unpack	window.rrwebPacker.pack, window.rrwebPacker.unpack	window.rrwebPacker.pack, window.rrwebPacker.unpack
rrweb-player	window.rrweb.Player	window.rrwebPlayer.Player	window.rrwebPlayer.Player
rrweb-snapshot	window.rrweb.snapshot, window.rrweb.rebuild	window.rrwebSnapshot.snapshot, window.rrwebSnapshot.rebuild	window.rrwebSnapshot.snapshot, window.rrwebSnapshot.rebuild
rrdom	window.rrweb.RRDocument, window.rrweb.diff	window.rrdom.RRDocument, window.rrdom.diff	window.rrdom.RRDocument, window.rrdom.diff
rrdom-nodejs	n/a (node-focused)	window.rrdomNodejs.* (mostly not browser usage)	n/a (node-focused)
rrvideo	n/a (node-focused)	n/a (node-focused)	n/a (node-focused)
@rrweb/types	window.rrweb.EventType, window.rrweb.IncrementalSource, etc.	window.rrwebTypes.EventType, window.rrwebTypes.IncrementalSource, etc.	window.rrwebTypes.EventType, window.rrwebTypes.IncrementalSource, etc.
@rrweb/utils	window.rrweb.utils.patch	window.rrwebUtils.patch	window.rrwebUtils.patch
@rrweb/web-extension	n/a (extension package)	n/a (extension package)	n/a (extension package)
@rrweb/rrweb-plugin-console-record	window.rrweb.plugins.getRecordConsolePlugin	window.rrwebPluginConsoleRecord.getRecordConsolePlugin	window.rrwebPluginConsoleRecord.getRecordConsolePlugin
@rrweb/rrweb-plugin-console-replay	window.rrweb.plugins.getReplayConsolePlugin	window.rrwebPluginConsoleReplay.getReplayConsolePlugin	window.rrwebPluginConsoleReplay.getReplayConsolePlugin
@rrweb/rrweb-plugin-sequential-id-record	window.rrweb.plugins.getRecordSequentialIdPlugin	window.rrwebPluginSequentialIdRecord.getRecordSequentialIdPlugin	window.rrwebPluginSequentialIdRecord.getRecordSequentialIdPlugin
@rrweb/rrweb-plugin-sequential-id-replay	window.rrweb.plugins.getReplaySequentialIdPlugin	window.rrwebPluginSequentialIdReplay.getReplaySequentialIdPlugin	window.rrwebPluginSequentialIdReplay.getReplaySequentialIdPlugin
@rrweb/rrweb-plugin-canvas-webrtc-record	window.rrweb.plugins.RRWebPluginCanvasWebRTCRecord	window.rrwebPluginCanvasWebRTCRecord.RRWebPluginCanvasWebRTCRecord	window.rrwebPluginCanvasWebRTCRecord.RRWebPluginCanvasWebRTCRecord
@rrweb/rrweb-plugin-canvas-webrtc-replay	window.rrweb.plugins.RRWebPluginCanvasWebRTCReplay	window.rrwebPluginCanvasWebRTCReplay.RRWebPluginCanvasWebRTCReplay	window.rrwebPluginCanvasWebRTCReplay.RRWebPluginCanvasWebRTCReplay

Strategy options

Strategy 1: Shared global (window.rrweb) for all packages.

• Pros: concise UMD API, familiar namespace, old v1 docs mostly apply to new packages
• Cons: collisions
  • Without build tool changes: last import overwrites the earlier imports
    • eg. @rrweb/record + @rrweb/replay: rrweb.record is overwritten by replay's window.rrweb = ...
  • With build tool changes: collisions still possible on method name when multiple packages are imported
    • eg. @rrweb/all + @rrweb/pack both define rrweb.pack
    • quite hard to detect
  • We've been using strategy 2 for most packages since (apart from 3) since the .alphas were introduced a while ago. We can still change it because it is marked as alpha but it will break some people's setups.

Stategy 2: Package-specific globals for modular packages.

• Pros: package isolation, clearer ownership, no collision risk.
• Cons: more verbose UMD API, documentation not 1:1 with rrweb v1 (eg. rrwebRecord.record instead of rrweb.record)

Strategy 3: Package-specific globals - except for @rrweb/all and rrweb

• Keep rrweb global for monolithic bundle only (@rrweb/all and rrweb).
• Use package-specific globals for all other packages.
• Define compatibility behavior explicitly.

Decision requested

Pick one strategy and document it as the official UMD contract.

Acceptance criteria

• One documented UMD/global policy for all packages.
• Build config aligned with that policy.
• Docs/examples aligned with that policy.
• Load-order tests covering shared-global conflict cases.
• Clear migration notes for any breaking UMD/global changes.

[eoghanmurray]

D3 uses Strategy 1, with the 'merge semantics'

D3 v4+ is split into dozens of micro-packages (d3-selection, d3-scale, d3-array, etc.) and each one's UMD build extends the same d3 global rather than replacing it

The only concern at record time is the mixing in of the plugins; e.g. it would be nice that if we were separately pulling in the record console plugin, we didn't have to further pollute the global namespace (window.rrwebPluginConsoleRecord)

I can't see much of a usecase for mixing record/replay functionality in the same webpage, but there could be some motivvating cases e.g. 'record this page' and then 'see your recording'

So I'd still vote for Strategy 1 I think and only have a single rrweb global name no matter what .umd script we use

[Juice10]

Thanks, this is a good point, and I agree the D3-style single-global experience is nicer when script-tag composition is a core use case.

For us, though, I think the key difference is priority: currently don’t have meaningful production script-tag usage as far as we know, so we’d be paying ongoing complexity cost for a path that isn’t mission-critical.

A shared global only works well if we commit to strict merge semantics (clear subtree ownership, additive writes only, collision detection, and load-order test coverage). Without that, we reintroduce exactly the overwrite/instability issues.

Given current usage and maintenance tradeoffs, I’d prefer package-specific globals for modular UMDs as the default policy, and keep a single shared namespace only for the monolithic bundle/docs convenience path (@rrweb/all & rrweb legacy package). That gives us deterministic behavior now, with an easy path to revisit if script-tag demand becomes real.

[Juice10]

I've done some research as to rrweb usage by import type on github to see how important UMD is compared to the rest:

Type	Frequency	Search query	Note
ES Modules	900~	query	Query includes 100+ false positives (mostly java), but also doesn't include any multi line esmodule imports
commonjs	70~	query	Mostly imports of rrweb-cssom
UMD	65~	query	Query includes minified files which in some cases are actually using esmodules in reality

Also esmodule imports seem to be widely supported by browsers, same goes for import maps nowadays so we could completely steer clear of using umd in the documentation and instead use the new recommended syntax (eg.):

<script type="module">
  import { record } from "https://cdn.jsdelivr.net/npm/rrweb@2.0.0-alpha.4/+esm";
  // or via esm.sh
  // import { record } from "https://esm.sh/rrweb@2.0.0-alpha.4";
  record({ emit: console.log });
</script>

or with import maps:

<script type="importmap">
{
  "imports": {
    "rrweb": "https://cdn.jsdelivr.net/npm/rrweb@2.0.0-alpha.4/+esm"
  }
}
</script>

<script type="module">
  import { record } from "rrweb";
  record({ emit: console.log });
</script>