Lumely Logo
Lumely

Documentation

Everything you need to integrate Lumely into your applications.

Next.js Setup

Get started with Lumely in under 2 minutes. No backend setup required.

1. Install the SDK

Install the package using your preferred package manager.

npm install lumely-next

2. Add the Provider

Wrap your application with the LumelyProvider and add your API key.

App Router (app/layout.tsx)

import { LumelyProvider } from 'lumely-next';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <LumelyProvider apiKey={process.env.NEXT_PUBLIC_LUMELY_API_KEY ?? ''}>
          {children}
        </LumelyProvider>
      </body>
    </html>
  );
}

Pages Router (pages/_app.tsx)

import { LumelyProvider } from 'lumely-next';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <LumelyProvider apiKey={process.env.NEXT_PUBLIC_LUMELY_API_KEY ?? ''}>
      <Component {...pageProps} />
    </LumelyProvider>
  );
}

3. Add Your API Key

Add your key to .env.local:

NEXT_PUBLIC_LUMELY_API_KEY=lum_your_api_key_here

4. Test It

Trigger an error to verify everything is working:

<button onClick={() => { throw new Error('Test Lumely!') }}>
  Trigger Error
</button>

React.js Setup

Get started with Lumely in any React app (Vite, CRA, etc.).

1. Install the SDK

npm install lumely-react

2. Add the Provider

Wrap your app with LumelyProvider (src/main.tsx).

import React from 'react';
import ReactDOM from 'react-dom/client';
import { LumelyProvider } from 'lumely-react';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <LumelyProvider apiKey={import.meta.env.VITE_LUMELY_API_KEY ?? ''}>
      <App />
    </LumelyProvider>
  </React.StrictMode>,
);

3. Add Your API Key

Vite (.env)

VITE_LUMELY_API_KEY=lum_key...

Create React App (.env)

REACT_APP_LUMELY_API_KEY=lum_key...

Manual Reporting

Capture handled exceptions and specific logic errors using the useLumelyReport hook.

Basic Usage

import { useLumelyReport } from 'lumely-next';

function PaymentForm() {
    const { reportError } = useLumelyReport();

    const handlePayment = async () => {
        try {
            // ... payment logic
        } catch (err) {
            await reportError(err as Error, { action: 'payment' });
            alert('Something went wrong.');
        }
    };
}

Adding Context

Pass detailed metadata to aid debugging.

await reportError(error, {
    action: 'user_signup',
    userId: user.id,
    email: user.email,
    formStep: 'payment',
});

Reusable Fetch Wrapper

// lib/fetchWithLumely.ts
import { useLumelyReport } from 'lumely-next';

export function useFetchWithLumely() {
    const { reportError } = useLumelyReport();
    
    return async (url: string, options?: RequestInit) => {
        try {
            const res = await fetch(url, options);
            if (!res.ok) {
                const error = new Error(`${res.status}: ${url}`);
                await reportError(error, { 
                    url, 
                    status: res.status 
                });
                throw error;
            }
            return res;
        } catch (err) {
            await reportError(err as Error, { url });
            throw err;
        }
    };
}

Integrations

Connect Lumely to your favorite tools for real-time alerts.

#Slack

  1. Go to Integrations in your dashboard.
  2. Click Connect Slack.
  3. Select the channel (e.g., #alerts).Do NOT select Direct Messages.
  4. Invite the bot to the channel:
    /invite @Lumely

Telegram

  1. Go to Integrations in dashboard.
  2. Click Connect Telegram.
  3. This opens Telegram. Click Start.
  4. You'll receive a confirmation message.