npm package: @prifina-dev/next-telemetry
Description: Lightweight telemetry library for Next.js App Router applications.
Latest version: 1.0.19

# next-telemetry

Lightweight telemetry library for Next.js App Router applications.

## Installation

Copy this library to your Next.js project or use as a local package.

## Quick Start

### 1. Environment Variables

Add to `.env.local`:
```
NEXT_PUBLIC_TELEMETRY_ENABLED=true
NEXT_PUBLIC_TELEMETRY_API_URL=http://localhost:4000
NEXT_PUBLIC_TELEMETRY_APP_NAME=my-app
NEXT_PUBLIC_TELEMETRY_ENV=dev
```

### 2. Browser Setup

In your Next.js app, update `app/layout.js` to initialize telemetry:
```js
import { TelemetryProvider } from "./telemetry-provider";

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

Create `app/telemetry-provider.js` in your app:
```js
"use client";
import { initBrowserTelemetry, TelemetryErrorBoundary } from "next-telemetry/client";
import { useEffect } from "react";

export function TelemetryProvider({ children }) {
  useEffect(() => {
    initBrowserTelemetry();
  }, []);
  
  return <TelemetryErrorBoundary>{children}</TelemetryErrorBoundary>;
}
```

### 3. API Route Handler (app/api/*/route.js)

Wrap API route handlers to capture server-side errors:
```js
import { withTelemetryRoute } from "next-telemetry/server";

export const GET = withTelemetryRoute(async (req) => {
  // Your API logic here
  return Response.json({ data: "success" });
});

export const POST = withTelemetryRoute(async (req) => {
  const body = await req.json();
  // Your logic
  return Response.json({ success: true });
});
```

### 4. Client-Side Error Capture

Browser errors are automatically captured by `initBrowserTelemetry()` and `TelemetryErrorBoundary`.

For manual capture (e.g., in your `authFetch()` wrapper):
```js
import { captureException } from "next-telemetry";

export async function authFetch(url, options) {
  try {
    const response = await fetch(url, {
      ...options,
      headers: { ...options?.headers, Authorization: `Bearer ${token}` }
    });
    
    if (!response.ok) {
      const error = new Error(`HTTP ${response.status}`);
      captureException(error, {
        extra: { url, status: response.status, method: options?.method }
      });
      throw error;
    }
    
    return response;
  } catch (error) {
    captureException(error, { extra: { url } });
    throw error;
  }
}
```

## API Reference

### Client Functions

- `initBrowserTelemetry(opts)` - Initialize browser error capture (call once on mount)
- `TelemetryErrorBoundary` - React Error Boundary component
- `captureException(error, context)` - Manual error capture (use in try/catch blocks)

### Server Functions

- `withTelemetryRoute(handler, opts)` - Wrap API route handlers
- `captureException(error, context)` - Manual error capture

## Configuration

Environment variables (use `NEXT_PUBLIC_` prefix for browser access):

- `TELEMETRY_ENABLED` - Enable/disable telemetry
- `TELEMETRY_API_URL` - Telemetry API endpoint
- `TELEMETRY_APP_NAME` - Application name
- `TELEMETRY_ENV` - Environment (dev/staging/prod)
- `TELEMETRY_RELEASE` - Release version (optional)
- `TELEMETRY_APP_DIRS` - Comma-separated app directories (default: app,src,lib,components)
- `TELEMETRY_IGNORE_PATTERNS` - Comma-separated ignore patterns (default: node_modules,next/dist,react-dom,internal)

## Copy Rule File to Your App

Copy `TELEMETRY_RULES.md` to your Next.js app's `.amazonq/rules/` directory:
```bash
cp TELEMETRY_RULES.md /path/to/your-nextjs-app/.amazonq/rules/telemetry.md
```

This helps Amazon Q understand how to use the telemetry library in your project.