lerix-core

Framework-agnostic core for the Lerix SDK — error tracking and Web Push notifications, backed by the Lerix platform. This package has no framework dependency; it's the shared engine behind lerix-angular and lerix-react, and can also be used directly in plain TypeScript/JavaScript, Vue, or any other web app.

Install

npm install lerix-core

Use it

import { Lerix } from "lerix-core";

await Lerix.initialize({
  apiKey: "your-api-key",
  projectId: "your-project-id",
  debugMode: true,
});

Lerix.throwError("Test error");

Lerix.notifications.setOnNotificationReceived((payload) => {
  console.log(payload.title, payload.body);
});

const subscribed = await Lerix.notifications.subscribe();

Filtering errors

Two optional initialize() options decide, on the client, which errors are sent. ignoreErrors runs first; beforeSend sees only what's left. Both apply to every report — global handlers, throwError(), reportCaughtError() and the framework wrappers' error boundaries/handlers.

await Lerix.initialize({
  apiKey: "your-api-key",
  projectId: "your-project-id",
  // A string drops any error whose message contains it (case-insensitive);
  // a RegExp drops any message it matches. Empty strings are ignored.
  ignoreErrors: ["ResizeObserver loop", /^ChunkLoadError/],
  // Return the event (optionally modified) to send it, or null to drop it.
  beforeSend: (event) => {
    if (event.message.includes("extension://")) return null;
    return { ...event, message: event.message.replace(/token=\S+/g, "token=[redacted]") };
  },
});

The event is a LerixErrorEvent: { message, stack, type, severity, metadata? }. If beforeSend throws, the original event is sent unchanged and the exception never reaches your app. There are no built-in ignore patterns in the SDK — common browser noise is filtered on the Lerix server.

Features

• Init/registration — Lerix.initialize() registers the app/user with the backend. Safe to call more than once (concurrent and idempotent — a second call in flight returns the same in-progress result rather than racing).
• Error tracking — Lerix.throwError(), with automatic stack capture from the call site if you don't pass one, automatic resolution of compiled/bundled stack frames back to original source locations (using the build's own source map, when reachable), and automatic capture of uncaught errors/promise rejections via installGlobalCrashHandlers().
• Push notifications — Lerix.notifications.*, using standard Web Push (VAPID) — no Firebase, no OneSignal. Ships its own service worker at sw/lerix-sw.js; copy it to your app's public root. It is registered on its own /lerix/ scope, so it coexists with an app's own service worker.
• Users — Lerix.setUser(externalId, { identityHash? }) after login links this install to your own user id, so your server can send to externalUserIds and reach every device of that user; Lerix.clearUser() on logout unlinks it. The id is stored locally and re-sent automatically when the install is re-registered. identityHash is hex(HMAC-SHA256(identity secret, externalId)), computed by your backend (required only when the project turns on identity verification).

Framework wrappers

If you're building a plain TS/JS app (or a framework without a dedicated Lerix package), use this package directly. If you're using Angular, React, or Next.js, use lerix-angular/lerix-react/lerix-nextjs instead — thin wrappers over this same core, with idiomatic integration (provideLerix()/LerixService for Angular; LerixProvider/hooks/ LerixErrorBoundary for React; LerixNextProvider plus the same React hooks/error boundary, pre-configured for the App Router and Pages Router, for Next.js).