@lerix-dev/lerix-react

Error tracking and Web Push notifications for React apps, backed by the Lerix platform. Built on the framework-agnostic @lerix-dev/lerix-core package.

Building a Next.js app? Use @lerix-dev/lerix-nextjs instead — it wraps this package with a provider pre-configured for the App Router and Pages Router, and pre-marked 'use client' so it works out of the box in Server Components.

Install

npm install @lerix-dev/lerix-react

Setup

1. Register the SDK

Wrap your app in LerixProvider, and LerixErrorBoundary to catch render errors:

import { LerixErrorBoundary, LerixProvider } from '@lerix-dev/lerix-react'

createRoot(document.getElementById('root')!).render(
  <LerixProvider
    options={{
      apiKey: 'your-api-key',
      projectId: 'your-project-id',
      debugMode: true,
    }}
  >
    <LerixErrorBoundary fallback={<p>Something went wrong.</p>}>
      <App />
    </LerixErrorBoundary>
  </LerixProvider>,
)

Registration with the backend runs once, on mount — safe even under React 18 StrictMode's double-effect-invocation in development, since Lerix.initialize() is re-entrant-safe.

LerixErrorBoundary only catches errors thrown during rendering (React's error boundary contract) — uncaught errors everywhere else (event handlers, async code, promise rejections) are still captured automatically via global handlers LerixProvider installs.

2. Report errors

import { useLerix } from '@lerix-dev/lerix-react'

function MyComponent() {
  const lerix = useLerix()

  const onSomethingFailed = () => {
    lerix.throwError('Something went wrong')
  }
}

Filtering errors

options also takes ignoreErrors and beforeSend, applied to every report (including LerixErrorBoundary). ignoreErrors runs first: a string drops any error whose message contains it (case-insensitive), a RegExp drops any messageit 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.

<LerixProvider
  options={{
    apiKey: 'your-api-key',
    projectId: 'your-project-id',
    ignoreErrors: ['ResizeObserver loop', /^ChunkLoadError/],
    beforeSend: (event) => (event.message.includes('extension://') ? null : event),
  }}
>

3. Push notifications

Copy the service worker into your app's public folder:

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

Generate a Web Push key from the dashboard: Notifications → Settings → Web Push → Generate keys.

import { useLerixNotifications } from '@lerix-dev/lerix-react'

function MyComponent() {
  const notifications = useLerixNotifications()

  useEffect(() => {
    notifications.setOnNotificationReceived((payload) => {
      console.log(payload.title, payload.body)
    })
  }, [])

  const enablePush = async () => {
    await notifications.subscribe()
  }
}

API

| Export | Description | |---|---| | LerixProvider | Registers the SDK at mount. Wrap your app once, near the root. | | LerixErrorBoundary | Catches React render-tree errors and reports them. | | useLerix() | Returns the Lerix facade — throwError, getUserId, setUser/clearUser, reRegisterUser, etc. | | useLerixNotifications() | Returns the notifications API — subscribe, checkPermissionStatus, getRegisteredTokenId, topics, etc. |

Requirements

• React 18+