@bwisemedia/njs-logger

A Winston-based logger library for Node.js applications, with support for:

• local output to file + console;
• remote forwarding via TCP or HTTP;
• dual-package distribution for ESM and CommonJS.

The exported logger behaves like console.log: it accepts multiple arguments and automatically serializes strings, objects, and errors.

Overview

The package exports a preconfigured singleton logger:

• input: calls to standard logger methods (info, warn, error, debug, etc.);
• local output:
  • logs/logs/combined.log (all levels),
  • logs/logs/error.log (errors only),
  • configurable console output (standard or JSON);
• optional remote output:
  • TCP (LOGGER_TRANSPORT_TYPE=tcp),
  • HTTP (LOGGER_TRANSPORT_TYPE=http).

Configuration is environment-variable driven (dotenv is loaded automatically).

Requirements

• Node.js >= 18
• npm (or any compatible package manager)

Installation

npm install @bwisemedia/njs-logger

Usage

ESM

import logger from "@bwisemedia/njs-logger";

logger.info("Server started", { port: 3000 });
logger.warn("Incomplete configuration", { key: "SMTP_HOST" });
logger.error("Application error", new Error("DB timeout"));

CommonJS

const logger = require("@bwisemedia/njs-logger").default;

logger.debug("Debug payload", { userId: 42, action: "login" });

Environment Variables

The variables below are the ones actually read by the code.

General

| Variable | Default | Description | | --- | --- | --- | | APP_NAME | unknown-app | Application name added to log payloads. | | APP_ENV | development | Environment (development, staging, production, etc.). | | LOGGER_MIN_LEVEL | info | Global minimum Winston logger level. | | STANDARD_OUTPUT | standard | Standard output format: standard (human-readable) or json (structured). |

Remote Forwarding Controls

| Variable | Default | Description | | --- | --- | --- | | LOGGER_SEND_TO_ELK | true | If true, enables adding a remote transport. | | LOGGER_TRANSPORT_TYPE | (none) | Remote transport type: tcp or http. | | LOGGER_SEND_TO_ELK_MIN_LEVEL | error | Minimum level for the remote transport. |

Transport TCP

| Variable | Default | Description | | --- | --- | --- | | TCP_LOGGER_HOST | localhost | TCP collector host. | | TCP_LOGGER_PORT | 5000 | TCP collector port. |

Transport HTTP

| Variable | Default | Description | | --- | --- | --- | | HTTP_LOGGER_ENDPOINT | http://localhost:8080 | HTTP endpoint that receives logs. | | HTTP_LOGGER_TOKEN | "" | Bearer token used in the Authorization header. |

Configuration Examples

Local Logs Only (file + console)

APP_NAME=my-service
APP_ENV=development
LOGGER_MIN_LEVEL=info
STANDARD_OUTPUT=standard
LOGGER_SEND_TO_ELK=false

Docker-Friendly Standard Output (JSON)

Use this when you want structured logs in docker logs:

APP_NAME=my-service
APP_ENV=production
LOGGER_MIN_LEVEL=info
STANDARD_OUTPUT=json
LOGGER_SEND_TO_ELK=false

Remote Forwarding via TCP

APP_NAME=my-service
APP_ENV=production
LOGGER_SEND_TO_ELK=true
LOGGER_TRANSPORT_TYPE=tcp
LOGGER_SEND_TO_ELK_MIN_LEVEL=error
TCP_LOGGER_HOST=logs.internal
TCP_LOGGER_PORT=9000

Remote Forwarding via HTTP

APP_NAME=my-service
APP_ENV=production
LOGGER_SEND_TO_ELK=true
LOGGER_TRANSPORT_TYPE=http
LOGGER_SEND_TO_ELK_MIN_LEVEL=warn
HTTP_LOGGER_ENDPOINT=https://logserver.example.com/ingest
HTTP_LOGGER_TOKEN=your-secret-token

Runtime Behavior

• Logger methods (error, warn, info, http, verbose, debug, silly) are wrapped to support multiple arguments.
• Each argument is converted as follows:
  • string -> unchanged string;
  • Error -> stack (or message);
  • other objects -> JSON.stringify (fallback to String() if needed).
• JSON payloads include application metadata (app, environment) and timestamps.
• STANDARD_OUTPUT=json switches only the standard console/stdout transport to JSON, useful for containerized workloads.
• The TCP transport keeps a local buffer while disconnected and flushes buffered messages after reconnecting.

Local Package Development

npm install
npm run build

Build output:

• dist/index.js (ESM)
• dist/index.cjs (CJS)
• dist/index.d.ts (TypeScript types)

Watch mode:

npm run dev

Test with npm link:

npm link

In a consumer project:

npm link @bwisemedia/njs-logger

Docker Test (Mounted Project)

Use the test Dockerfile to run the logger in a container while mounting your local project. This is useful to verify structured stdout logs with docker logs.

Build the test image:

docker build -f Dockerfile.test -t njs-logger-test .

Run with JSON standard output (recommended for container logging validation):

docker run --rm \
  -v "$(pwd)":/workspace \
  -e STANDARD_OUTPUT=json \
  -e APP_NAME=my-service \
  -e APP_ENV=production \
  -e LOGGER_SEND_TO_ELK=false \
  njs-logger-test

Run with human-readable standard output:

docker run --rm \
  -v "$(pwd)":/workspace \
  -e STANDARD_OUTPUT=standard \
  -e LOGGER_SEND_TO_ELK=false \
  njs-logger-test

Optional quick test (shorter run):

docker run --rm \
  -v "$(pwd)":/workspace \
  -e STANDARD_OUTPUT=json \
  -e LOGGER_SEND_TO_ELK=false \
  -e LOG_MESSAGES=5 \
  -e LOG_INTERVAL_MS=500 \
  njs-logger-test

Publishing

The package automatically runs the build in prepublishOnly.

Typical flow:

npm version patch
git push --follow-tags

Operational Notes

• The repository includes .env.example; use it as a baseline and keep it aligned with the effective variables above.
• If LOGGER_SEND_TO_ELK=true but LOGGER_TRANSPORT_TYPE is not set to tcp or http, only local transports stay active.

License

MIT