@prifina-dev/next-telemetry

v1.0.17

Published

3 hours ago

Lightweight telemetry library for Next.js App Router applications.

0High
0Medium
0Low

tro-npmjs9999

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:

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:

"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:

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):

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:

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.