@lerix-dev/lerix-nextjs

Error tracking and Web Push notifications for Next.js apps, backed by the Lerix platform. Built on @lerix-dev/lerix-react and @lerix-dev/lerix-core — works with both the App Router and the Pages Router.

Install

npm install @lerix-dev/lerix-nextjs

Setup

1. Configure your API key and project ID

Add to .env.local:

NEXT_PUBLIC_LERIX_API_KEY=your-api-key
NEXT_PUBLIC_LERIX_PROJECT_ID=your-project-id

These must be prefixed NEXT_PUBLIC_ — that's Next.js's own convention for env vars exposed to client-side code, required here since the SDK registers/reports from the browser.

2. Register the SDK (App Router)

Wrap your root layout in LerixNextProvider and LerixErrorBoundary:

import { LerixErrorBoundary, LerixNextProvider } from '@lerix-dev/lerix-nextjs';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <LerixNextProvider>
          <LerixErrorBoundary fallback={<p>Something went wrong.</p>}>
            {children}
          </LerixErrorBoundary>
        </LerixNextProvider>
      </body>
    </html>
  );
}

LerixNextProvider reads NEXT_PUBLIC_LERIX_API_KEY/NEXT_PUBLIC_LERIX_PROJECT_ID automatically — pass options explicitly only if you want to override them (e.g. debugMode, a different project per environment).

For the Pages Router, do the same in pages/_app.tsx instead.

layout.tsx itself stays a Server Component — LerixNextProvider and LerixErrorBoundary are pre-marked 'use client' internally, so wrapping them around children doesn't force your whole tree to become client-only.

3. Report errors

'use client';
import { useLerix } from '@lerix-dev/lerix-nextjs';

export function MyComponent() {
  const lerix = useLerix();
  return <button onClick={() => lerix.throwError('Something went wrong')}>Test</button>;
}

LerixErrorBoundary only catches errors during rendering. For Next.js's own file-based error boundaries (error.tsx, global-error.tsx) — which you'll need for errors above where LerixErrorBoundary sits, e.g. in the root layout itself — call reportCaughtError directly:

'use client';
import { reportCaughtError } from '@lerix-dev/lerix-nextjs';
import { useEffect } from 'react';

export default function Error({ error }: { error: Error }) {
  useEffect(() => {
    reportCaughtError(error);
  }, [error]);

  return <p>Something went wrong.</p>;
}

Filtering errors

options also takes ignoreErrors and beforeSend, applied to every report (LerixErrorBoundary, reportCaughtError in error.tsx, global handlers). 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.

Functions and RegExps can't be passed as props from a Server Component, so set these options in a small client component and use it in layout.tsx in place of LerixNextProvider:

'use client';
import { LerixNextProvider } from '@lerix-dev/lerix-nextjs';

export function Lerix({ children }: { children: React.ReactNode }) {
  return (
    <LerixNextProvider
      options={{
        ignoreErrors: ['ResizeObserver loop', /^ChunkLoadError/],
        beforeSend: (event) => (event.message.includes('extension://') ? null : event),
      }}
    >
      {children}
    </LerixNextProvider>
  );
}

4. 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 dashboard: Notifications → Settings → Web Push → Generate keys.

'use client';
import { useLerixNotifications } from '@lerix-dev/lerix-nextjs';

export function MyComponent() {
  const notifications = useLerixNotifications();
  return <button onClick={() => notifications.subscribe()}>Enable notifications</button>;
}

API

| Export | Description | |---|---| | LerixNextProvider | Registers the SDK at mount, reading config from NEXT_PUBLIC_* env vars by default. | | 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. | | reportCaughtError(error) | Reports an already-caught error directly — for use in Next's own error.tsx/global-error.tsx. |

Requirements

• Next.js 13+
• React 18+