The CloudWatch RUM web client is a JavaScript library that performs real user monitoring (RUM) on web applications. It captures page load timing, web vitals (LCP, FID, CLS, INP), JavaScript errors, HTTP requests, session replays, and custom events, then ships them to Amazon CloudWatch RUM.
1. Create an app monitor. Follow Set up an app monitor in the CloudWatch RUM user guide. You will receive an application ID, a region, and (optionally) a Cognito identity pool ID.
2. Install and initialize.
NPM:
npm install aws-rum-webimport { AwsRum, AwsRumConfig } from 'aws-rum-web';
try {
const config: AwsRumConfig = {
sessionSampleRate: 1,
identityPoolId: 'us-west-2:00000000-0000-0000-0000-000000000000',
endpoint: 'https://dataplane.rum.us-west-2.amazonaws.com',
telemetries: ['performance', 'errors', 'http'],
allowCookies: true,
enableXRay: false
};
const APPLICATION_ID = '00000000-0000-0000-0000-000000000000';
const APPLICATION_VERSION = '1.0.0';
const APPLICATION_REGION = 'us-west-2';
const awsRum: AwsRum = new AwsRum(
APPLICATION_ID,
APPLICATION_VERSION,
APPLICATION_REGION,
config
);
} catch (error) {
// Ignore errors thrown during CloudWatch RUM web client initialization
}CDN (embedded script): paste the snippet from the RUM console into your <head>. The snippet loads the bundle from the AWS-hosted CDN — see Choose a package below for CDN bundle URLs, or CDN installation for the full snippet reference.
3. Verify it works. Open your app, trigger a page view or throw a test error, then open the CloudWatch RUM console. Events appear within ~1 minute. If nothing shows up, enable debug: true in the config and check the browser console — every dispatch is logged.
// Throw a test error to verify errors telemetry
setTimeout(() => {
throw new Error('rum-verify');
}, 0);Two distributions, same AwsRum class. Pick full unless bundle size is load-bearing.
| Package | Minified | Gzipped | Included out of the box |
|---|---|---|---|
aws-rum-web (full) |
~162 KB | ~50 KB | Cognito auth, SigV4 signing, default telemetries (errors, performance, http, replay), remote config |
@aws-rum/web-slim |
~32 KB | ~10 KB | Page views and sessions only out of the box. BYO auth via setAwsCredentials, opt-in signing via setSigningConfigFactory, load plugins explicitly via eventPluginsToLoad |
Slim is ~5× smaller. The trade-off is that you wire up auth and plugins yourself — see the slim reference and the full→slim migration guide.
Both distributions are also published to an AWS-hosted CDN. The snippet generated by the RUM console already uses the recommended URL, but you can reference these directly:
| Bundle | Recommended URL (major-pinned) |
|---|---|
cwr.js (full) |
https://client.rum.us-east-1.amazonaws.com/3.x/cwr.js |
cwr-slim.js (slim) |
https://client.rum.us-east-1.amazonaws.com/3.x/cwr-slim.js |
Every published version is available at three pin levels. Pick the level that matches your update tolerance:
| Pin | Example | Resolves to |
|---|---|---|
Major (N.x) |
.../3.x/cwr.js |
Latest 3.*.* release. Default. Picks up backwards-compatible fixes automatically. |
Minor (N.M.x) |
.../3.0.x/cwr.js |
Latest 3.0.* patch. Patches only, no new minor-version features. |
Exact (N.M.P) |
.../3.0.0/cwr.js |
That exact release. Frozen — you bump manually to get fixes. |
The same three levels apply to cwr-slim.js (3.x/cwr-slim.js, 3.0.x/cwr-slim.js, 3.0.0/cwr-slim.js).
⚠️ *.xURLs auto-update on every matching release.3.xand3.0.xare floating pointers — the moment a new matching version is published, every page that loads that URL serves the new bundle on its next cache-miss. No action, no canary. Regressions reach your users automatically, and two browsers loading your page minutes apart may run different versions. If you need staged rollouts, QA sign-off per version, or byte-for-byte reproducibility, pin to an exact version (3.0.0/cwr.js) and bump it deliberately in your own pipeline. See CDN installation for the full discussion.
Start at docs/README.md for the full index. Common entry points:
- Install as a JavaScript module (NPM)
- Install as an embedded script (CDN)
- Configuration reference
- Commands / API reference
- Slim distribution · Full→slim migration
- Framework guides: React · Angular
- Troubleshooting
- Examples
- CloudWatch RUM user guide
- Amazon CloudWatch forum
- AWS Support
- File a bug — please search existing issues first and include the web client version and a repro case.
PRs welcome. See CONTRIBUTING.
Requires Node.js 20+.
npm install
npm run releaseOutputs:
- CDN bundle:
./build/assets/cwr.js,./build/assets/cwr.map.js - NPM (ES + CJS):
./dist/es/index.js,./dist/cjs/index.jsand matching.d.tsfiles
npm run test # Jest unit tests
npm run integ # Playwright integration tests
npm run smoke:headless # Playwright smoke testsDev server (for exploratory testing at http://localhost:9000):
npm run servernpm run lint:fix
npm run prettier:fixSee CONTRIBUTING.
Apache-2.0.