# Angular Dependencies
> Dependency & Compatibility guide for @revrag-ai/embed-angular — supported Angular versions, builders, TypeScript, what the SDK adds to the host, and what to do outside the supported ranges.
URL: /embed/integration/angular/angular-dependencies
Markdown: /embed/integration/angular/angular-dependencies.md
# Dependency & Compatibility Guide [#dependency--compatibility-guide]
For client apps integrating **`@revrag-ai/embed-angular`** · SDK **2.0.0**
Which Angular, builder and TypeScript versions the SDK works with, what it adds to the host app, and what to do when the host is outside the supported ranges.
Everything here comes from the package's `package.json`, its build, and the apps it was checked against for `2.0.0`.
| Status | Meaning |
| ------------- | ---------------------------------------------------------------------- |
| **Exercised** | An app on that stack was built against the `2.0.0` package and checked |
| **In range** | The peer ranges allow it, but no app covers it |
**Treat "exercised" as strong evidence, not a release certification.**
Stack A uses the SDK's packaged build through a local file link. Stack B used the packed `2.0.0` tarball. Neither installed the package from npm.
***
## Table of contents [#table-of-contents]
1. [Known-good stacks](#1-known-good-stacks)
2. [Peer dependencies](#2-peer-dependencies)
3. [What the SDK adds to the host](#3-what-the-sdk-adds-to-the-host)
4. [Angular versions, router, builders and app styles](#4-angular-versions-router-builders-and-app-styles)
5. [Outside the ranges: workarounds](#5-outside-the-ranges-workarounds)
6. [TypeScript](#6-typescript)
7. [Browsers and runtime](#7-browsers-and-runtime)
8. [Package managers](#8-package-managers)
9. [Out of scope](#9-out-of-scope)
***
## 1. Known-good stacks [#1-known-good-stacks]
Pin to one of these when you can.
| Stack | Angular | App style | Builder | TypeScript | RxJS | zone.js | Checked how |
| ----------------- | ----------- | ------------------ | ----------------------- | --------------- | ---- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **A. Angular 19** | **19.2.19** | standalone, router | `application` (esbuild) | 5.7 (`bundler`) | 7.8 | 0.15 | `examples/angular` in the SDK repository: production build, then the widget driven in a browser with no errors |
| **B. Angular 16** | **16.2.12** | NgModule, router | `browser` (webpack) | 5.1 (`node`) | 7.8 | 0.13 (the Angular 16 `ng new` default) | A fresh `ng new` app built for production against the packed `2.0.0` tarball |
Both use `lottie-web` 5.13 and `livekit-client` 2.x.
Stack A bootstraps with `bootstrapApplication`, `provideZoneChangeDetection`, `provideRouter` and `provideAnimations()`.
**Stack B also compiles code written against `1.0.7`.** It references a deprecated `1.0.7` export, which still type-checks in `2.0.0`.
***
## 2. Peer dependencies [#2-peer-dependencies]
Your app installs these. The SDK uses your copy.
| Package | Declared range | Status |
| ---------------------------------------------------------------------------- | -------------- | ---------------------------------------------- |
| `@angular/core`, `@angular/common`, `@angular/animations`, `@angular/router` | `>=16.0.0` | 16 and 19 exercised; 17, 18 and newer in range |
| `rxjs` | `^7.4.0` | 7.8 exercised |
| `livekit-client` | `^2.0.0` | 2.x exercised |
| `lottie-web` | `^5.10.0` | 5.13 exercised |
* **Every peer is required.** npm 7+ installs missing peers for you; with yarn classic, install `livekit-client` and `lottie-web` yourself.
* **All `@angular/*` packages must be the same version** as each other, and as the rest of your Angular packages.
* **`@angular/router` is required to install, but not to run.** The provider injects the router optionally, so an app that never configures routes works through `[currentPath]`.
* **`@angular/animations` must match your Angular version** — install it pinned first (see [§5](#5-outside-the-ranges-workarounds)).
* **RxJS 6 is outside the range.** Angular 16 and newer accept RxJS 6 or 7, so check `npm ls rxjs`. The SDK imports `map`, `filter` and `distinctUntilChanged` straight from `rxjs`, which RxJS 6 doesn't support. Upgrade to 7.4 or newer.
* **`zone.js` is not a peer.** Use the version your Angular release asks for. See [zone.js](#zonejs) for zoneless apps.
***
## 3. What the SDK adds to the host [#3-what-the-sdk-adds-to-the-host]
**Runtime dependency** (npm installs it for you):
| Package | Range | Notes |
| ------- | -------- | ------------------------------------------------------------------------------- |
| `tslib` | `^2.6.0` | Every Angular app already has it; npm shares one copy when your version matches |
`livekit-client` and `lottie-web` are **peers**, not dependencies, so add them to your own `package.json`. The [install command](/embed/integration/angular) does this for you.
**Bundled inside the package** (not installed, cannot conflict):
* **`@revrag-ai/embed-core`** — inlined into the package's bundle. Never install or import it. Import only from `@revrag-ai/embed-angular` and `@revrag-ai/embed-angular/diagnostics`.
* **The default avatar animation** — its own chunk, loaded on demand.
**What reaches your bundle:**
| Piece | When it loads |
| ---------------------------- | ------------------------------------------------------------- |
| The SDK itself | With your app |
| `livekit-client` | In its own chunk, when a call starts |
| `lottie-web` | In its own chunk, when the avatar first renders |
| The default avatar animation | In its own chunk, only if your dashboard has no custom avatar |
In `examples/angular` the whole app's initial bundle is **653 KB** (178 KB transferred) — inside Angular's default 1 MB error budget. Before `2.0.0`, the same app was 1.01 MB and failed the build.
653 KB is still past Angular's default 500 kB **warning** budget, so you may see `bundle initial exceeded maximum budget` as a warning. Raise the `initial` budget in `angular.json` if you see it.
**The Angular CLI warns: `Module 'lottie-web' … is not ESM`.**
`lottie-web` ships CommonJS. The warning is harmless; silence it in `angular.json`:
```json
"allowedCommonJsDependencies": ["lottie-web"]
```
**Stylesheet.** `@revrag-ai/embed-angular/styles/widget.css` (\~46 KB) is precompiled and **required**. Add it to `styles` in `angular.json` (see the [integration guide](/embed/integration/angular)).
* **Every rule is scoped** to the widget's own `embed-*` classes; there is no global reset.
* **It works with or without** Tailwind, Angular Material or your own design system.
**Check the result after installing:**
```bash
npm ls @revrag-ai/embed-angular # 2.0.0
npm ls @angular/core @angular/common @angular/animations @angular/router # one copy each, all the same version
npm ls rxjs # 7.4 or newer
npm ls livekit-client lottie-web # one copy each
```
**Two copies of `@angular/core` are never acceptable.**
* This usually happens in monorepos or with linked packages.
* Dedupe them: `npm dedupe`, or `overrides` / `resolutions` pinned to your app's Angular version.
***
## 4. Angular versions, router, builders and app styles [#4-angular-versions-router-builders-and-app-styles]
### Angular [#angular]
| Version | Status | Notes |
| ------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 19 | exercised (A) | |
| 17, 18 | in range | Same code path |
| 20 and newer | in range | The peer range is open-ended. `@angular/animations` is deprecated from 20.2 and npm prints a warning; the SDK still needs it. Angular 22 needs TypeScript 6.0 |
| 16 | exercised (B) | The oldest supported version |
| 15 and older | **unsupported** | The build fails: the SDK uses signals (Angular 16+) |
**Angular 17, 18 and 20+ have not been run by an app.**
The SDK's templates use only `*ngIf` / `*ngFor`, not the newer `@if` / `@for` blocks. Its only Angular 16+ API is `signal`. Still, run a production build and test the widget before you release.
### Angular Router [#angular-router]
* **With Angular Router set up:** `` follows navigation by itself. It uses the URL path, without `?query` or `#fragment`.
* **Without Angular Router:** pass `[currentPath]`. Otherwise the provider reads `window.location.pathname` once, on start, and never updates.
* **If you pass `[currentPath]`**, it always wins over the router.
### Builders [#builders]
| Builder | Status | Notes |
| ------------------------------------------------------ | ------------- | ------------------------------------------------------------------- |
| `application` (esbuild — the default since Angular 17) | exercised (A) | `@angular-devkit/build-angular:application`. Also covers `ng serve` |
| `@angular/build:application` | in range | The same esbuild builder, published in its own package |
| `browser` (webpack — the default up to Angular 16) | exercised (B) | |
| `browser-esbuild` | in range | |
| Nx (`@nx/angular`) | in range | Add the stylesheet to `project.json` instead of `angular.json` |
### App styles [#app-styles]
| | Status | Notes |
| ------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------ |
| Standalone components | exercised (A) | Import `EmbedProviderComponent`, plus `provideAnimations()` in your app config |
| NgModule | exercised (B) | Import `EmbedModule`, plus `BrowserAnimationsModule` |
| SSR (`@angular/ssr`, Angular Universal) | in range | The widget no-ops on the server |
| `OnPush` components | in range | The SDK updates its own components itself |
| Zoneless (`provideExperimentalZonelessChangeDetection`) | **untested** | Keep `zone.js` |
| Angular Material / CDK | in range | CDK dialogs attached to `document.body` stay visible to the agent |
**Animations are required in both styles.** The widget's components use Angular animations. Without `provideAnimations()` (or `BrowserAnimationsModule`), the collapsed button appears, but Angular throws `NG05105: Unexpected synthetic property` as soon as the widget opens or shows its nudge. Only development builds throw; a production build shows no error.
### zone.js [#zonejs]
* **With zone.js** (the default for most apps): exercised with 0.15 (A).
* **Zoneless apps** (`provideZonelessChangeDetection` or its older name `provideExperimentalZonelessChangeDetection`, and new projects on recent Angular versions): **not exercised**. If your app is zoneless, test opening and closing the widget, a full call and live captions before you release.
***
## 5. Outside the ranges: workarounds [#5-outside-the-ranges-workarounds]
| Host | Symptom | Do |
| ---------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Angular 15 or older | Build error: `signal` is not exported by `@angular/core` | Upgrade Angular to 16 or newer. There is no workaround |
| No `@angular/animations` installed yet | `npm ERR! ERESOLVE` — npm picked a newer major than your Angular | `npm install @angular/animations@` first, then the SDK (below) |
| Still on SDK `1.0.7`, no `skipLibCheck` | `TS2307: Cannot find module '@revrag-ai/embed-core'` | Upgrade to `2.0.0` |
| yarn berry with PnP | resolution errors | `nodeLinker: node-modules` in `.yarnrc.yml` |
| `--legacy-peer-deps` / `legacy-peer-deps=true` | Missing modules at build time (`livekit-client`, `lottie-web`, `@angular/animations`) | npm skips peers in this mode. Install every peer from [§2](#2-peer-dependencies) yourself |
| Plain `http://` (not `localhost`) | Calls fail silently: no mic prompt, no console error | Serve over HTTPS |
**Fixing the `@angular/animations` ERESOLVE.** Find your Angular version, install the missing packages at that exact version, then install the SDK:
```bash
npm ls @angular/core # e.g. @angular/core@19.2.19
npm install @angular/animations@19.2.19 @angular/router@19.2.19
npm install @revrag-ai/embed-angular livekit-client lottie-web
```
Use the version `npm ls` printed for you, not `19.2.19`.
**Do not up- or downgrade the host's unrelated dependencies to fit the SDK.**
Apart from Angular 15, every mismatch above has a fix that leaves the host's versions alone.
**Do not reach for `--force` or `--legacy-peer-deps` to get past ERESOLVE.**
They can leave you with an `@angular/animations` that doesn't match your `@angular/core`, or with peers missing. Pinning the version, as above, fixes the cause.
***
## 6. TypeScript [#6-typescript]
| | |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Versions | 5.1 (B) and 5.7 (A) exercised; whatever your Angular version requires works: 4.9–5.1 for Angular 16, 5.5–5.8 for 19, 6.0 for 22 |
| `moduleResolution` | `bundler` (A) and `node` (B) exercised. Both resolve `@revrag-ai/embed-angular` and `@revrag-ai/embed-angular/diagnostics` |
| Types | Bundled, including `/diagnostics`. No `@types` package to install |
| `skipLibCheck` | Not needed since `2.0.0`. The package's types check cleanly with `skipLibCheck: false` |
| Strict templates | Stack A runs with `strictTemplates: true` |
***
## 7. Browsers and runtime [#7-browsers-and-runtime]
| Requirement | Detail |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Browsers | The browsers your Angular version supports |
| JavaScript | The package ships ES2022 code (`fesm2022`). The Angular CLI compiles it for your project's browsers, the same way it compiles your own code |
| Calls | WebRTC + `getUserMedia`, in a **secure context** (HTTPS, or `localhost`). Elsewhere the call fails silently: no mic prompt and no console error |
| Storage | `sessionStorage` is **required**: the widget doesn't render without it. `localStorage` is optional. IndexedDB is optional (falls back to memory) |
| Test on | Desktop Chrome and iOS Safari, on the production build. iOS Safari only allows the mic and audio after a user gesture |
| SSR | The widget renders nothing on the server and appears after hydration |
***
## 8. Package managers [#8-package-managers]
| Manager | Notes |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| npm 7+ | Installs peers automatically. Expect `ERESOLVE` only in the [§5](#5-outside-the-ranges-workarounds) cases |
| npm with `legacy-peer-deps` | Doesn't install peers. Install every package in [§2](#2-peer-dependencies) yourself |
| yarn classic | Doesn't install peers: add `livekit-client` and `lottie-web` yourself, and `@angular/animations` / `@angular/router` at your Angular version if your app doesn't have them |
| yarn berry | Use `nodeLinker: node-modules` |
| pnpm | Works; pnpm 8+ installs peers by default (`auto-install-peers`). In a workspace, check `pnpm why @angular/core` for a single copy |
***
## 9. Out of scope [#9-out-of-scope]
* **React, Next.js and Preact** use `@revrag-ai/embed-react` — see the [React integration guide](/embed/integration/react).
* **React Native** has its own package, `@revrag-ai/embed-react-native` — see the [React Native integration guide](/embed/integration/react-native).
* **AngularJS (1.x)** isn't supported.
* **Vue** isn't supported.
* **Plain `