edgelogs

The simplest, Next.js-native logging & error monitoring SDK — edge-safe, zero dependencies.

Features

• 🚀 Edge-safe - Works in Vercel Edge, Cloudflare Workers, and all edge runtimes
• 📦 Zero dependencies - Tiny bundle size (<5KB minified)
• 🔥 Fire-and-forget - Non-blocking, batched log ingestion
• 🎯 TypeScript-first - Full type safety out of the box
• 🔍 Request tracing - Automatic trace ID generation and correlation
• ⚡ Auto-enrichment - Captures deployment info, timestamps, and context

Installation

npm install edgelogs
# or
yarn add edgelogs
# or
pnpm add edgelogs

Quick Start

1. Initialize in instrumentation.ts (Next.js 15+)

// instrumentation.ts (runs on server start)
import { init } from "edgelogs";

export function register() {
  init({
    apiKey: process.env.EDGE_LOGS_API_KEY!,
    // endpoint is optional - defaults to edgelogs.dev
  });
}

2. Use in your application

import { log } from "edgelogs";

// Info logs
log.info("User logged in", { userId: 123, method: "Google" });

// Warnings
log.warn("Rate limit approaching", { userId: 456, endpoint: "/api/search" });

// Errors
try {
  await processPayment(orderId);
} catch (err) {
  log.error(err, { orderId, userId, amount: 99.99 });
}

// Debug logs
log.debug("Cache hit", { key: "user:123", ttl: 3600 });

API Reference

init(config: EdgeLogsConfig): Logger

Initialize the Edge Logs client. Call this once at application startup.

import { init } from "edgelogs";

const logger = init({
  apiKey: "el_your_api_key_here",
  // endpoint is optional - defaults to https://edgelogs.dev/api/ingest
  enabled: true, // optional, default: true
  batchSize: 10, // optional, default: 10
  flushInterval: 5000, // optional, default: 5000ms
  debug: false, // optional, default: false
  deploymentInfo: {
    // optional
    env: "production",
    region: "us-east-1",
    commitSha: "abc123",
  },
});

log.info(message: string, context?: LogContext): void

Log an informational message.

log.info("Server started", { port: 3000, env: "production" });

log.warn(message: string, context?: LogContext): void

Log a warning message.

log.warn("Slow query detected", { query: "SELECT *", duration: 2500 });

log.error(error: Error | string, context?: LogContext): void

Log an error with automatic stack trace capture.

try {
  throw new Error("Payment failed");
} catch (err) {
  log.error(err, { userId: 123, orderId: "ord_abc" });
}

log.debug(message: string, context?: LogContext): void

Log a debug message.

log.debug("Cache miss", { key: "user:123" });

log.flush(): Promise<void>

Manually flush all buffered logs immediately.

await log.flush();

log.setTraceId(traceId: string): void

Set a custom trace ID for request correlation.

log.setTraceId("trace_custom_123");

log.clearTraceId(): void

Clear the current trace ID.

log.clearTraceId();

Configuration Options

| Option | Type | Default | Description | | ---------------- | ---------------- | ------------------------------------------ | ------------------------------------ | | apiKey | string | Required | Your Edge Logs API key | | endpoint | string | https://edgelogs.dev/api/ingest | Log ingestion endpoint | | enabled | boolean | true | Enable/disable logging | | batchSize | number | 10 | Number of logs to batch before flush | | flushInterval | number | 5000 | Auto-flush interval in milliseconds | | debug | boolean | false | Enable debug console output | | deploymentInfo | DeploymentInfo | Auto-detected from Vercel env vars | Deployment metadata |

Usage Examples

Next.js App Router

// app/api/checkout/route.ts
import { log } from "edgelogs";

export async function POST(request: Request) {
  const body = await request.json();

  log.info("Checkout started", { userId: body.userId, items: body.items.length });

  try {
    const result = await processCheckout(body);
    log.info("Checkout completed", { orderId: result.orderId, total: result.total });
    return Response.json(result);
  } catch (error) {
    log.error(error, { userId: body.userId, cart: body.items });
    return Response.json({ error: "Checkout failed" }, { status: 500 });
  }
}

Next.js Server Actions

// app/actions.ts
"use server";

import { log } from "edgelogs";

export async function updateProfile(formData: FormData) {
  const userId = formData.get("userId");

  try {
    await db.users.update(userId, { name: formData.get("name") });
    log.info("Profile updated", { userId });
  } catch (error) {
    log.error(error, { userId, action: "updateProfile" });
    throw error;
  }
}

Edge Middleware

// middleware.ts
import { log } from "edgelogs";
import { NextResponse } from "next/server";

export function middleware(request: Request) {
  const traceId = crypto.randomUUID();
  log.setTraceId(traceId);

  log.info("Request received", {
    path: request.url,
    method: request.method,
  });

  const response = NextResponse.next();
  response.headers.set("X-Trace-ID", traceId);

  return response;
}

Best Practices

1. Initialize once - Call init() in instrumentation.ts or at app startup
2. Use trace IDs - Set trace IDs in middleware for request correlation
3. Add context - Include relevant metadata (userId, orderId, etc.)
4. Handle errors - Always log errors with context for debugging
5. Flush on exit - Call log.flush() before serverless function exits

Environment Variables

Auto-detected from Vercel:

• VERCEL_ENV - Deployment environment (production, preview, development)
• VERCEL_REGION - Deployment region
• VERCEL_GIT_COMMIT_SHA - Git commit SHA

TypeScript Support

Full TypeScript support with exported types:

import type { EdgeLogsConfig, Logger, LogContext, LogLevel, LogEntry } from "edgelogs";

License

MIT

Support

• Documentation
• GitHub Issues
• Email: [email protected]