Lerix (Angular)

Error tracking and Web Push notifications for Angular apps, backed by the Lerix platform: app/user registration, error/crash reporting, and push notifications (Web Push / VAPID).

This is an Angular workspace: the library lives in projects/lerix-angular, with a runnable demo app in projects/example.

Install

npm install @lerix-dev/lerix-angular

Setup

1. Register the SDK

Add provideLerix() to your app.config.ts:

import { ApplicationConfig } from '@angular/core';
import { provideLerix } from '@lerix-dev/lerix-angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideLerix({
      apiKey: 'YOUR_PROJECT_API_KEY',
      projectId: 'YOUR_PROJECT_ID',
      debugMode: true,
    }),
  ],
};

Registration with the backend (and the automatic crash handler) runs at bootstrap, before your app becomes interactive — no separate init() call needed.

2. Report errors

import { Component } from '@angular/core';
import { LerixService, BugSeverity } from '@lerix-dev/lerix-angular';

@Component({ ... })
export class MyComponent {
  constructor(private readonly lerix: LerixService) {}

  onSomethingFailed(error: Error) {
    this.lerix.throwError(error.message, error.stack?.split('\n'), undefined, BugSeverity.HIGH);
  }
}

Uncaught errors are captured automatically two ways: a custom Angular ErrorHandler catches anything inside Angular's zone (template bindings, lifecycle hooks, RxJS subscriptions), and global window.onerror / unhandledrejection listeners catch everything else. Unlike a native crash handler, a browser tab isn't about to terminate when this fires, so the report is sent immediately rather than persisted for the next launch.

Filtering errors

provideLerix() also takes ignoreErrors and beforeSend, applied to every report (the Angular ErrorHandler, global handlers, LerixService.throwError). ignoreErrors runs first: a string drops any error whose message contains it (case-insensitive), a RegExp drops any message it matches (empty strings are skipped). beforeSend gets a LerixErrorEvent and returns it (optionally modified) to send, or null to drop it; if it throws, the original is sent.

provideLerix({
  apiKey: 'YOUR_PROJECT_API_KEY',
  projectId: 'YOUR_PROJECT_ID',
  ignoreErrors: ['ResizeObserver loop', /^ChunkLoadError/],
  beforeSend: (event) => (event.message.includes('extension://') ? null : event),
}),

3. Push notifications

cp node_modules/@lerix-dev/lerix-core/sw/lerix-sw.js your-app/public/lerix-sw.js

Generate a Web Push key from the Lerix dashboard: Notifications → Settings → Web Push → Generate keys — one click, nothing to copy into your code.

import { Component, inject } from '@angular/core';
import { LerixService } from '@lerix-dev/lerix-angular';

@Component({ ... })
export class MyComponent {
  private readonly lerix = inject(LerixService);

  async enablePush() {
    const subscribed = await this.lerix.notifications.subscribe();
  }

  constructor() {
    this.lerix.notifications.setOnNotificationReceived((payload) => {
      // Fired while a tab is open.
    });

    this.lerix.notifications.setOnNotificationTapped((payload) => {
      // Fired on click — delivered reliably even from a closed-tab tap.
    });
  }
}

Device identifiers

| Method | Returns | Use it for | |---|---|---| | getRegisteredTokenId() | Lerix's own id for this registered device | The value for the dashboard's/REST API's device-targeting field | | getDeviceToken() | The raw PushSubscription JSON, stringified | Rarely needed directly; diagnostics only | | getDeviceId() | A locally generated identifier, unrelated to Lerix's backend | Local diagnostics only; not what the dashboard's send flow expects |

Users

Link this install to your own user id after login, so your server can send to externalUserIds and reach every device that user is signed in on:

await this.lerix.setUser(user.id, { identityHash }); // identityHash only if verification is on
await this.lerix.clearUser();                        // on logout

identityHash is hex(HMAC-SHA256(identity secret, externalId)), computed by your backend. The id is stored locally and re-sent when the install is re-registered.

Requirements

• Angular 19+
• Chrome, Firefox, and Edge support Web Push fully. Safari requires macOS 13+ / iOS 16.4+ — older Safari doesn't support the standard at all.

Notes

• Device/user identity is stored in localStorage, falling back to an in-memory map if unavailable (private browsing, SSR).