@c5h-soft/discord-logger

Lightweight Discord webhook logger with pino integration, colored console output, and timezone support.

Perfect for monitoring your applications in real-time through Discord webhooks.

Features

• 🚀 Simple API - Initialize once, use everywhere
• 🎨 Colored console output - Beautiful logs in development
• 🌍 Timezone support - Configure timestamps for your region
• 📊 Pino integration - Professional logging with structured data
• 🔔 Discord webhooks - Real-time notifications to your Discord channel
• 📦 TypeScript - Full type support out of the box
• 🪶 Lightweight - Minimal dependencies

Installation

npm install @c5h-soft/discord-logger
# or
yarn add @c5h-soft/discord-logger
# or
pnpm add @c5h-soft/discord-logger

Quick Start

1. Initialize the logger (once at app startup)

// For Next.js: src/instrumentation.ts
import { initDiscordLogger } from "@c5h-soft/discord-logger";

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    initDiscordLogger({
      webhookUrl: process.env.DISCORD_WEBHOOK_URL,
      timezone: "America/Argentina/Buenos_Aires",
      locale: "es-AR",
      appName: "my-app",
      debug: process.env.NODE_ENV === "development",
    });
  }
}

// For Express/Node.js: src/index.ts
import { initDiscordLogger } from "@c5h-soft/discord-logger";

initDiscordLogger({
  webhookUrl: process.env.DISCORD_WEBHOOK_URL,
  appName: "api-server",
});

2. Use the logger anywhere

import { log } from "@c5h-soft/discord-logger";

// Simple messages
log.info("Server started on port 3000");
log.warn("Deprecated function called");
log.error("Database connection failed", new Error("Connection refused"));
log.debug("Request payload", { userId: 123, action: "login" });

// Structured event logging
log.info({
  event: "user.registered",
  timestamp: new Date(),
  userId: "123",
  email: "[email protected]",
  provider: "google",
});

Configuration Options

| Option | Type | Default | Description | | ---------------- | ------------------- | ------------- | ------------------------------------------------------------------------ | | webhookUrl | string | undefined | Discord webhook URL. Required for Discord logging. | | timezone | string | 'UTC' | Timezone for timestamps (e.g., 'America/New_York', 'Europe/London'). | | locale | string | 'en-US' | Locale for date formatting (e.g., 'es-AR', 'de-DE'). | | appName | string | 'app' | Application name shown in logs. | | debug | boolean | false | Enable debug level logging. | | colors | boolean | true in dev | Enable colored console output. | | disableDiscord | boolean | false | Disable Discord logging (useful for testing). | | disableConsole | boolean | false | Disable console logging entirely. | | pinoOptions | PinoLoggerOptions | {} | Custom pino configuration options. |

API Reference

initDiscordLogger(config)

Initialize the logger with your configuration. Call this once at application startup.

import { initDiscordLogger } from "@c5h-soft/discord-logger";

initDiscordLogger({
  webhookUrl: process.env.DISCORD_WEBHOOK_URL,
  timezone: "America/Argentina/Buenos_Aires",
  locale: "es-AR",
  appName: "my-app",
  debug: true,
  colors: true,
});

log.info(message, data?)

Log an informational message.

log.info("User logged in");
log.info("Processing request", { userId: 123, path: "/api/users" });
log.info({ event: "payment.completed", amount: 100, userId: "456" });

log.error(message, error?)

Log an error message with optional error object.

log.error("Something went wrong");
log.error("Database query failed", new Error("Connection timeout"));
log.error("API call failed", { status: 500, body: "Internal error" });

log.warn(message, data?)

Log a warning message.

log.warn("Rate limit approaching");
log.warn("Deprecated API called", { endpoint: "/v1/users", by: "client-123" });

log.debug(message, data?)

Log a debug message (only when debug: true is configured).

log.debug("Cache hit", { key: "user:123" });
log.debug({ query: "SELECT * FROM users", duration: 45 });

log.child(bindings)

Create a child logger with additional context.

const requestLog = log.child({ requestId: "abc-123", userId: 456 });
requestLog.info("Processing request");
requestLog.error("Request failed", new Error("Not found"));

log.getPino()

Get the underlying pino logger instance for advanced usage.

const pinoLogger = log.getPino();
pinoLogger.info({ custom: "data" }, "Using pino directly");

Event Formatting

The logger automatically formats event objects with special handling for common event types:

log.info({
  event: "user.registered",
  timestamp: new Date(),
  userId: "123",
  email: "[email protected]",
  name: "John Doe",
  provider: "google",
});

Discord output:

ℹ️ [my-app] **USER.REGISTERED** - 12/12/2025, 10:30:00
User: 123 • Email: [email protected] • Name: John Doe • Provider: google

Supported event patterns:

• user.* - User events (login, register, etc.)
• payment.* - Payment events (amount, credits)
• job.* - Job events (title, company)
• application.* - Application events
• api_key.* - API key events
• webhook.* - Webhook events

Development vs Production

In development (NODE_ENV=development):

• Colored console output using pino-pretty
• Human-readable timestamps
• Debug messages shown (if enabled)

In production:

• JSON structured logging via pino
• Optimized for log aggregation services
• Discord notifications for monitoring

Environment Variables

# Required for Discord logging
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

# Optional
NODE_ENV=development  # Enables colored output

Common Timezone Values

| Timezone | Region | | -------------------------------- | -------------------------- | | UTC | Coordinated Universal Time | | America/New_York | Eastern US | | America/Chicago | Central US | | America/Denver | Mountain US | | America/Los_Angeles | Pacific US | | America/Argentina/Buenos_Aires | Argentina | | America/Sao_Paulo | Brazil | | America/Mexico_City | Mexico | | Europe/London | UK | | Europe/Paris | Central Europe | | Europe/Berlin | Germany | | Europe/Madrid | Spain | | Asia/Tokyo | Japan | | Asia/Shanghai | China | | Asia/Singapore | Singapore | | Asia/Dubai | UAE | | Asia/Kolkata | India | | Australia/Sydney | Australia (East) |

📋 Full list: IANA Time Zone Database

Common Locale Values

| Locale | Language / Region | | ------- | ------------------------ | | en-US | English (United States) | | en-GB | English (United Kingdom) | | es-ES | Spanish (Spain) | | es-AR | Spanish (Argentina) | | es-MX | Spanish (Mexico) | | pt-BR | Portuguese (Brazil) | | pt-PT | Portuguese (Portugal) | | fr-FR | French (France) | | de-DE | German (Germany) | | it-IT | Italian (Italy) | | ja-JP | Japanese (Japan) | | zh-CN | Chinese (Simplified) | | zh-TW | Chinese (Traditional) | | ko-KR | Korean (South Korea) | | ru-RU | Russian (Russia) | | ar-SA | Arabic (Saudi Arabia) | | hi-IN | Hindi (India) |

📋 Full list: BCP 47 Language Tags | MDN Intl.Locale

Examples

Next.js App Router

// src/instrumentation.ts
import { initDiscordLogger, log } from "@c5h-soft/discord-logger";

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    initDiscordLogger({
      webhookUrl: process.env.DISCORD_WEBHOOK_URL,
      appName: "nextjs-app",
      timezone: "UTC",
    });
    log.info("Application started");
  }
}

Express Server

import express from "express";
import { initDiscordLogger, log } from "@c5h-soft/discord-logger";

initDiscordLogger({
  webhookUrl: process.env.DISCORD_WEBHOOK_URL,
  appName: "api-server",
});

const app = express();

app.use((req, res, next) => {
  log.debug("Request received", { method: req.method, path: req.path });
  next();
});

app.listen(3000, () => {
  log.info("Server started on port 3000");
});

Error Handling

import { log } from "@c5h-soft/discord-logger";

async function processPayment(userId: string, amount: number) {
  try {
    const result = await paymentService.charge(userId, amount);
    log.info({
      event: "payment.completed",
      timestamp: new Date(),
      userId,
      amount,
      transactionId: result.id,
    });
    return result;
  } catch (error) {
    log.error("Payment processing failed", error);
    throw error;
  }
}

License

MIT © c5h.dev

Made with ❤️ by c5h.dev - Custom software development