Skip to content

Latest commit

 

History

History
201 lines (163 loc) · 10.2 KB

README.md

File metadata and controls

201 lines (163 loc) · 10.2 KB

UI Watchtower UI Watchtower

UI Watchtower

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.

Layout

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).

Getting started

Requires Node.js 22 or later.

npm install
npm run test
npm run build

The 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.

Scripts

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, string while nothing is registered. The Angular package's are compiled by the Angular compiler, the core's by plain tsc.
  • The API snapshots (public-api.snapshot.json in each package) record every export of the built packages with its members and signatures. After an intended change, run npm run api:update and 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 test records 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 or aws-rum-web installed), a TypeScript one (the core's type tests, and a project without the DOM typings), and an unchanged Angular application, prerendered as a fragment without aws-rum-web and as a shell with /rum. It installs from the registry, so it needs a network.

Before you push

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 smoke

CI runs the same checks on every pull request and every push to main.

Pull requests

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

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
  1. Every push to main updates one release PR, for every package with changes. feat bumps the minor version, fix, perf and revert the patch; until 1.0, a breaking change bumps the minor. Other types don't trigger a release.
  2. The release PR holds each released package's version bump and CHANGELOG.md entry. When the core is released, Release Please's node-workspace plugin 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.
  3. Merging it tags each release, ui-watchtower-v<version> or ngx-ui-watchtower-v<version> (until 0.4.0, the Angular package's tags were v<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 public

Then, 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.

License

Apache License 2.0.