@bugmail-js/next

v0.1.3

Published

a month ago

BugMail SDK for Next.js

0High
0Medium
0Low

kaave-mark

bugmail error-tracking nextjs react sdk

@bugmail-js/next — BugMail SDK for Next.js

Official BugMail SDK for Next.js applications. Provides first-class error tracking for both App Router and Pages Router.

Installation

npm install @bugmail-js/next
# or
pnpm add @bugmail-js/next

Quick Start

App Router (Next.js 13+)

1. Create an error reporting component:

// app/error.tsx
'use client';

import { useEffect } from 'react';
import { createAppRouterErrorHandler } from '@bugmail-js/next';

const reportError = createAppRouterErrorHandler({
  apiKey: process.env.NEXT_PUBLIC_BUGMAIL_API_KEY!,
  projectId: process.env.NEXT_PUBLIC_BUGMAIL_PROJECT_ID!,
  baseUrl: process.env.NEXT_PUBLIC_BUGMAIL_ENDPOINT || '<your-bugmail-endpoint>',
  environment: process.env.NODE_ENV,
});

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    reportError(error);
  }, [error]);

  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  );
}

2. Wrap API Route Handlers (optional):

// app/api/example/route.ts
import { createNextApiWrapper } from '@bugmail-js/next';

const withBugMail = createNextApiWrapper({
  apiKey: process.env.BUGMAIL_API_KEY!,
  projectId: process.env.BUGMAIL_PROJECT_ID!,
  baseUrl: process.env.BUGMAIL_ENDPOINT || '<your-bugmail-endpoint>',
});

// Note: For App Router, use try/catch in route handlers
export async function GET() {
  try {
    // Your code
    return Response.json({ ok: true });
  } catch (error) {
    // Manual capture for App Router routes
    throw error;
  }
}

Pages Router

1. Create API middleware:

// pages/api/example.ts
import { createNextApiWrapper } from '@bugmail-js/next';

const withBugMail = createNextApiWrapper({
  apiKey: process.env.BUGMAIL_API_KEY!,
  projectId: process.env.BUGMAIL_PROJECT_ID!,
  baseUrl: process.env.BUGMAIL_ENDPOINT || '<your-bugmail-endpoint>',
  environment: process.env.NODE_ENV,
});

async function handler(req, res) {
  // Your API logic
  res.status(200).json({ message: 'Hello' });
}

export default withBugMail(handler);

Client-Side (React Components)

Use the BugMailProvider for client-side error tracking:

// app/providers.tsx
'use client';

import { BugMailProvider } from '@bugmail-js/next';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <BugMailProvider
      apiKey={process.env.NEXT_PUBLIC_BUGMAIL_API_KEY!}
      projectId={process.env.NEXT_PUBLIC_BUGMAIL_PROJECT_ID!}
      endpoint={process.env.NEXT_PUBLIC_BUGMAIL_ENDPOINT || '<your-bugmail-endpoint>'}
      environment={process.env.NODE_ENV}
    >
      {children}
    </BugMailProvider>
  );
}

// app/layout.tsx
import { Providers } from './providers';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Configuration

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiKey | string | Yes | Your BugMail project API key | | projectId | string | Yes | Your BugMail project ID | | baseUrl | string | No | API endpoint (e.g., <your-bugmail-endpoint>) | | environment | string | No | Environment name (default: production) |

Environment Variables

# .env.local
BUGMAIL_API_KEY=your_api_key_here
BUGMAIL_PROJECT_ID=your_project_id_here

# For client-side (prefix with NEXT_PUBLIC_)
NEXT_PUBLIC_BUGMAIL_API_KEY=your_api_key_here
NEXT_PUBLIC_BUGMAIL_PROJECT_ID=your_project_id_here

API Reference

Server-Side

createNextApiWrapper(config) — Wraps Pages Router API routes
createAppRouterErrorHandler(config) — Creates error reporter for App Router
initServer(config) — Initialize server-side client manually
captureServerError(error, context?) — Manually capture server errors

Client-Side

BugMailProvider — React context provider
useBugMail() — Hook to access BugMail client
init(options) — Initialize client-side SDK

Troubleshooting

Errors not appearing in dashboard?

Check your API key and project ID
Verify baseUrl is set correctly (e.g., <your-bugmail-endpoint>)
Check browser/server console for BugMail debug messages
Ensure environment variables are set correctly

CORS errors?

The BugMail API should allow CORS from your origins.

License

MIT