Contributing to rrweb

We want to make contributing to this project as easy and transparent as possible.

Our Development Process

The majority of development on rrweb will occur through GitHub. Accordingly, the process for contributing will follow standard GitHub protocol.

Pull Requests

We actively welcome your pull requests (PRs)!

1. Fork the repo and create your branch from main.
2. If you've added code that should be tested, add tests
3. Ensure the test suite passes or ask for help as to why tests are failing
4. We use changesets to enable you to easily document your PR so that it can be packaged up into the next release. A github plugin will prompt you to fill in your changeset if you haven't already done so.
5. If you've changed APIs, update the documentation.
6. Make sure your code lints and typechecks.

Issues

We use GitHub issues to track public bugs. Please ensure your description is clear and has sufficient instructions to be able to reproduce the issue.

Run locally

• Install dependencies: yarn
• Build all packages: (in /) yarn build:all or yarn dev
• Run recorder on a website: (in /packages/rrweb) yarn repl
• Run a cobrowsing/mirroring session locally: (in /packages/rrweb) yarn live-stream
• Build individual packages: yarn build or yarn dev
• Test: yarn test or yarn test:watch
• WebKit (Safari engine) tests: yarn test:webkit (in /packages/rrweb-snapshot)

WebKit tests

test/webkit-monkey-patched.test.ts is excluded from the regular yarn test run because it requires a Playwright WebKit browser binary. It is run separately via yarn test:webkit in packages/rrweb-snapshot.

macOS — install the browser once, then run directly:

npx playwright install webkit
yarn test:webkit

Linux — system library dependencies vary by distro. The most reliable approach is Docker (requires Docker to be installed):

# first time, or after changing rrweb-snapshot source: build the dist then the image
cd packages/rrweb-snapshot && yarn build && cd ../..
docker build -t rrweb-webkit-test -f Dockerfile.webkit-test .

# run rrweb-snapshot webkit tests
docker run --rm -e BROWSER=webkit rrweb-webkit-test \
  yarn workspace rrweb-snapshot vitest run --config vitest.config.webkit.ts

# run rrweb webkit tests
docker run --rm -e BROWSER=webkit rrweb-webkit-test \
  yarn workspace rrweb vitest run --config vitest.config.webkit.ts

# iterate on test file and/or dist without rebuilding the image
# (run `yarn build` in the relevant package first if you changed source)
docker run --rm -e BROWSER=webkit \
  --mount type=bind,src=/absolute/path/to/rrweb/packages/rrweb-snapshot/dist/rrweb-snapshot.umd.cjs,dst=/work/packages/rrweb-snapshot/dist/rrweb-snapshot.umd.cjs \
  --mount type=bind,src=/absolute/path/to/rrweb/packages/rrweb-snapshot/test/monkey-patched.test.ts,dst=/work/packages/rrweb-snapshot/test/monkey-patched.test.ts \
  rrweb-webkit-test bash -c 'yarn workspace rrweb-snapshot vitest run --config vitest.config.webkit.ts'

The image is based on mcr.microsoft.com/playwright:v1.61.1-jammy which has all required system libraries pre-installed. The same image can be used to run webkit tests from any package in the monorepo by changing the yarn workspace command. Rebuild the image after updating the playwright package version or adding new test files.

• Lint: yarn lint
• Rewrite files with prettier: yarn format or yarn format:head

Coding style

See documentation

License

rrweb is MIT licensed.

By contributing to rrweb, you agree that your contributions will be licensed under its MIT license.