Telemetry for frontend applications, in three parts:
- Scenarios — did a user journey or a workflow succeed, and how long did it take?
- BI events — which features are used?
- Logs — what exactly happened?
Events go to AWS CloudWatch RUM or another destination you choose; logs go to a backend you provide.
It comes as two packages, each with its own version:
| Package | Use it in | Guide |
|---|---|---|
@absaoss-cps/ui-watchtower |
Any frontend: plain JavaScript or TypeScript, or any framework. Framework adapters are built on it (how). | README |
@absaoss-cps/ngx-ui-watchtower |
Angular applications. A thin adapter over @absaoss-cps/ui-watchtower: Angular providers, injectable services and Observables around the same engine. |
README |
Each guide is also the package's npm page. How it is designed: projects/ngx-ui-watchtower/DESIGN.md.
projects/ui-watchtower/
src/ @absaoss-cps/ui-watchtower — the framework-independent engine
rxjs/ secondary entry point — @absaoss-cps/ui-watchtower/rxjs
rum/ secondary entry point — @absaoss-cps/ui-watchtower/rum
type-tests/ consumer type tests, without a framework
README.md usage guide, published to npm
package.json the published package's manifest
projects/ngx-ui-watchtower/
src/ main entry point — @absaoss-cps/ngx-ui-watchtower
rum/ secondary entry point — @absaoss-cps/ngx-ui-watchtower/rum
type-tests/ consumer type tests
README.md usage guide, published to npm
DESIGN.md full design
package.json the published package's manifest
docs/ ADAPTERS.md: how to write a framework adapter
scripts/ the public API snapshot, the packaging smoke test, and publishing
The Angular package depends on the core, never the other way round. Each package has its own version; a core release also releases the Angular package, with its dependency moved (see Releases).
Requires Node.js 22 or later.
npm install
npm run test
npm run buildThe packages are built to dist/ui-watchtower and dist/ngx-ui-watchtower,
the core first: the Angular package compiles against the built core, as an
application does. Tests and the typecheck read the core's source.
| Script | What it does |
|---|---|
npm run build |
Builds both packages (production), the core first |
npm run watch |
Builds the core, then rebuilds the Angular package on change |
npm run test |
Runs the unit tests of both packages (Jest) |
npm run test:core |
Runs the core's unit tests only: plain Jest, no Angular |
npm run test:coverage |
Runs the unit tests with coverage, as CI does; fails below 90% |
npm run typecheck |
Builds the core, then type-checks every tsconfig and type test |
npm run api:check |
Builds both packages, then compares their public APIs |
npm run api:update |
Builds both packages, then rewrites their snapshots |
npm run smoke |
Installs the built packages, packed, into throwaway consumers |
npm run lint |
ESLint, no warnings allowed |
npm run format |
Formats with Prettier |
npm run format:check |
Checks formatting without writing |
Four checks guard what consumers depend on:
- Type tests (
type-tests/in each package) compile a consumer that uses every public export, and one that augments the name registries: registered names accepted, others rejected,stringwhile nothing is registered. The Angular package's are compiled by the Angular compiler, the core's by plaintsc. - The API snapshots (
public-api.snapshot.jsonin each package) record every export of the built packages with its members and signatures. After an intended change, runnpm run api:updateand review the diff. - The broadcast wire fixture
(
projects/ngx-ui-watchtower/src/lib/sinks/uwt-broadcast/uwt-broadcast.wire.fixture.json) records every message a shell and a fragment exchange. Shells and fragments are deployed separately, so it changes only with a deliberate protocol change:UPDATE_WIRE_FIXTURE=1 npm testrecords it again. Every pairing of an Angular or framework-free shell and fragment is held to it. - The smoke test (
scripts/smoke/) packs both packages and installs the tarballs, outside this workspace, into a framework-free Node consumer (no Angular, RxJS oraws-rum-webinstalled), a TypeScript one (the core's type tests, and a project without the DOM typings), and an unchanged Angular application, prerendered as a fragment withoutaws-rum-weband as a shell with/rum. It installs from the registry, so it needs a network.
Run all of them — each catches something the others don't:
npm run test
npm run typecheck
npm run lint
npm run format:check
npm run build
npm run api:check
npm run smokeCI runs the same checks on every pull request and every push to main.
PR titles must follow Conventional Commits,
for example feat: add scenario timeout option or fix: flush logs on page hide.
Allowed types: feat, fix, docs, style, refactor, perf, test,
build, ci, chore, revert. A check enforces it; the ignore-cc-check
label skips it.
Squash-merge pull requests: the title then becomes the commit message on
main, and releases are built from those messages.
Releases are automated with release-please — don't publish by hand. Each package has its own version and changelog, and is released when it changes:
| A change to | Releases |
|---|---|
| The Angular package | The Angular package |
| The core | The core, and a patch of the Angular package that moves its dependency to ^ the new core |
| Both | Each, with its own bump |
- Every push to
mainupdates one release PR, for every package with changes.featbumps the minor version,fix,perfandrevertthe patch; until 1.0, a breaking change bumps the minor. Other types don't trigger a release. - The release PR holds each released package's version bump and
CHANGELOG.mdentry. When the core is released, Release Please'snode-workspaceplugin also moves the Angular package's dependency on the core and releases it as a patch, so it always depends on the core it was built against. - Merging it tags each release,
ui-watchtower-v<version>orngx-ui-watchtower-v<version>(until 0.4.0, the Angular package's tags werev<version>), and creates its GitHub release. GitHub Actions then publishes what was released, the core before the Angular package, through trusted publishing — no npm token.
A failed publish stops before the Angular package, so it never depends on a core that isn't on npm. To finish a partial release, use Re-run failed jobs on that workflow run: each package's step skips a version npm already has.
The core's first release is 0.1.0, set by its initial-version in
release-please-config.json, and published by the workflow like every
release. npm adds a trusted publisher only to a package that exists, so
before the first release PR that releases the core is merged, an
@absaoss-cps owner publishes a placeholder, 0.0.0, by hand:
npm login
mkdir ui-watchtower-placeholder && cd ui-watchtower-placeholder
echo '{ "name": "@absaoss-cps/ui-watchtower", "version": "0.0.0", "description": "Placeholder: the first release is 0.1.0", "license": "Apache-2.0" }' > package.json
npm publish --access publicThen, on npmjs.com, in the package's settings, add the trusted publisher the
Angular package has: GitHub Actions, AbsaOSS/ui-watchtower, workflow
release-please.yml. Once the workflow has published 0.1.0, deprecate the
placeholder:
npm deprecate @absaoss-cps/ui-watchtower@0.0.0 "Placeholder, use 0.1.0 or later"If the release PR is merged first, publishing the core fails, and the Angular package isn't published: add the trusted publisher, then re-run the failed job.
bootstrap-sha in release-please-config.json is the commit tagged
v0.4.0: it keeps what that release shipped out of the first changelogs,
and is read only until both packages have a release. If another v release
reaches main first, set it to that release's commit. That commit is also
tagged ngx-ui-watchtower-v0.4.0, in the new format, so the Angular
package's first changelog compares from a tag that exists.
Apache License 2.0.