rollbar/AGENTS.md

Effortlessly track and debug errors in your JavaScript applications with Rollbar. This package includes advanced error tracking features and an intuitive interface to help you identify and fix issues more quickly.

# Repository Guidelines

## Project Structure & Module Organization

Rollbar.js is the cross-platform SDK for Rollbar error monitoring. Browser runtime code sits in `src/browser/`, Node handlers in `src/server/`, React Native-specific modules in `src/react-native/`, and shared systems in `src/tracing/`, `src/telemetry.*`, and `src/utility/`. Public entry points flow through `src/rollbar.js` into bundled artifacts under `dist/` (do not edit generated files). Type definitions live in `index.d.ts`. Integration examples and docs are in `examples/` and `docs/`, while CLI helpers and release scripts live under `scripts/`. Tests mirror the source layout inside `test/`, with replay-focused coverage in `test/replay/`.

## Build, Test, and Development Commands

Use `npm run build` for production bundles and `npm run build:dev` during debugging. `npm test` executes both browser (Web Test Runner) and server (Mocha) suites; target subsets via `npm run test:wtr`, `npm run test:wtr:watch`, or `npm run test:server`. Lint with `npm run lint`, and rely on `npm run format` / `npm run format:check` for Prettier parity. Before publishing, run `npm run validate` to enforce ES5 compatibility and verify example snippets, then package distributables with `npm run pack`.

## Coding Style & Naming Conventions

This repo is an ES module project (`package.json` sets `"type": "module"`). ESLint rules in `eslint.config.js` enforce 2-space indentation, single quotes (via Prettier), `no-console` outside `scripts/`, maximum cyclomatic complexity of 35, and grouped alphabetized imports. The `unused-imports` plugin must leave files warning-free. Prefer PascalCase for exported classes or constructors, camelCase for functions and variables, and keep side-effect files named `<feature>.js` or `<feature>.cjs` to match existing patterns.

## Testing Guidelines

Author browser-facing specs under `test/browser.*.test.js` and Node scenarios under `test/server.*.test.js`. Session replay code should carry dedicated unit and integration coverage in `test/replay/**`. Tests use Mocha with Chai assertions and Sinon stubs. Add fixtures in `test/fixtures/` when mocking rrweb payloads or HTTP exchanges. Ensure `npm test` and `npm run validate:es5` succeed before opening a PR, especially after touching bundling or transport logic.

## Commit & Pull Request Guidelines

Follow the existing history by writing imperative, present-tense commit messages (e.g., `Add import linting guard (#1410)`). Each PR should summarize behavior changes, call out linked issues, and include test evidence or reproduction steps. Update relevant docs (`docs/`, `examples/`, `README.md`) for public-facing changes, avoid leaving TODOs, and surface any follow-up work in the PR description rather than the code. For security-sensitive fixes, coordinate disclosure via `SECURITY.md` instructions before merging.