@moonstar-x/logger

A tiny, zero-dependency logger for Node.js with levels, colors, timestamps, child loggers and JSON output.

• Zero dependencies. Nothing but node:util and node:process.
• Seven levels, from trace to fatal, with a silent threshold to turn everything off.
• Pretty by default, JSON when you need it. One colored line per message for humans, one JSON object per line for log collectors.
• Child loggers. Namespaced names and inherited structured bindings.
• Configurable from the environment. LOG_LEVEL, LOG_FORMAT, LOG_TIMESTAMP, NO_COLOR and FORCE_COLOR are all honored out of the box.
• Written in TypeScript, shipped as both ESM and CJS with full type declarations.

Installation

npm install @moonstar-x/logger

This package requires Node.js >=22.12.0.

Usage

The default logger

The package exports a ready-to-use logger, configured from the environment.

import logger from '@moonstar-x/logger';

logger.info('server listening on port 3000');
logger.warn('cache miss, falling back to the database');
logger.error(new Error('could not reach the database'));

CommonJS works too:

const { default: logger } = require('@moonstar-x/logger');

logger.info('server listening on port 3000');

Logger methods are not bound to their instance, so call them on the logger (logger.info(...)) instead of destructuring them (const { info } = logger).

Logging messages

Every method takes any number of arguments. Strings are used as-is, everything else is inspected, which means objects are serialized and errors keep their stack trace.

logger.trace('entering the request handler');           // gray,    stdout
logger.debug('resolved config', config);                // green,   stdout
logger.info('user signed in', { userId: 42 });          // cyan,    stdout
logger.log('plain message');                            // white,   stdout
logger.warn('token is about to expire');                // yellow,  stderr
logger.error(new Error('request failed'));              // red,     stderr
logger.fatal('unrecoverable, shutting down');           // magenta, stderr

Which prints:

(1:57:54 PM) - [TRACE] - entering the request handler
(1:57:54 PM) - [DEBUG] - resolved config { port: 3000 }
(1:57:54 PM) - [INFO] - user signed in { userId: 42 }
(1:57:54 PM) - [LOG] - plain message
(1:57:54 PM) - [WARN] - token is about to expire
(1:57:54 PM) - [ERROR] - Error: request failed
    at file:///app/index.js:12:14
    ...
(1:57:54 PM) - [FATAL] - unrecoverable, shutting down

You can also clear the terminal, which is a no-op when the output is not a TTY:

logger.clear();

Log levels

A logger only emits messages at or above its own level. log is an alias of info that keeps its own tag and color.

| Level | Severity | Method | Color | Destination | | -------- | -------- | ----------------- | ------- | ----------- | | trace | 10 | logger.trace() | gray | stdout | | debug | 20 | logger.debug() | green | stdout | | info | 30 | logger.info() | cyan | stdout | | info | 30 | logger.log() | white | stdout | | warn | 40 | logger.warn() | yellow | stderr | | error | 50 | logger.error() | red | stderr | | fatal | 60 | logger.fatal() | magenta | stderr | | silent | — | — | — | — |

The level can be read, set, or checked at any time:

logger.level;                      // 'info'
logger.level = 'debug';            // throws a TypeError on an invalid level
logger.setLevel('debug');          // same, but chainable

if (logger.isLevelEnabled('debug')) {
  logger.debug('expensive dump', buildExpensiveReport());
}

Creating a logger

createLogger builds a logger from the environment, with the options you pass taking precedence.

import { createLogger } from '@moonstar-x/logger';

const logger = createLogger({
  name: 'api',
  level: 'debug',
  format: 'pretty'
});

logger.info('ready');
// (1:57:54 PM) - [INFO] - (api) - ready

To ignore the environment entirely, construct the class directly:

import { Logger } from '@moonstar-x/logger';

const logger = new Logger({ level: 'warn' });

Child loggers

child() creates a logger that inherits its parent's configuration. Names are joined with a colon and bindings are merged, so subsystems are easy to tell apart.

const logger = createLogger({ name: 'api' });
const database = logger.child('db');
const pool = database.child({ name: 'pool', level: 'trace', bindings: { poolId: 1 } });

database.info('connected');
// (1:57:54 PM) - [INFO] - (api:db) - connected

pool.trace('acquired a connection');
// (1:57:54 PM) - [TRACE] - (api:db:pool) - acquired a connection

JSON output

Switching the format to json renders one JSON object per line, ready to be picked up by a log collector. This is where bindings come in: they are structured fields added to every entry.

const logger = createLogger({
  format: 'json',
  name: 'api',
  bindings: { service: 'checkout', version: '2.0.0' }
});

logger.info('order placed');

{"level":"info","time":"2026-09-10T18:57:54.678Z","name":"api","service":"checkout","version":"2.0.0","msg":"order placed"}

Bindings are serialized safely: circular references are replaced with [Circular], BigInt values are stringified, and errors are turned into their name, message and stack.

Custom destinations

Anything with a write method is a valid destination, which makes it trivial to point a logger at a file, a socket or an in-memory buffer — very handy in tests.

import fs from 'node:fs';

const file = fs.createWriteStream('app.log', { flags: 'a' });
const logger = createLogger({ format: 'json', stdout: file, stderr: file });

const lines = [];
const logger = createLogger({ stdout: { write: (line) => lines.push(line) }, color: false });

Configuration

Every option has a sensible default, so createLogger() is a valid call.

| Option | Type | Default | Description | |-------------|----------------------------------------------------------------|------------------|-------------------------------------------------------------------------------------------------| | bindings | Record<string, unknown> | {} | Structured fields added to every entry. Only rendered in json format. | | color | boolean | auto-detected | Forces colors on or off, bypassing NO_COLOR, FORCE_COLOR and TTY detection. | | depth | number \| null | null | How deep objects are inspected. null means unlimited. | | format | 'pretty' \| 'json' | 'pretty' | How the output is rendered. | | level | LogLevel | 'info' | The minimum severity that gets logged. | | name | string | — | A name shown on every entry, useful to tell subsystems apart. | | stderr | Destination | process.stderr | Where warn, error and fatal are written. | | stdout | Destination | process.stdout | Where trace, debug, info and log are written. | | timestamp | 'iso' \| 'time' \| ((date: Date) => string) \| false \| true | true | How the timestamp is rendered. true picks a locale time for pretty and ISO 8601 for json. |

Environment variables

createLogger and the default logger read these on startup. Explicit options always win.

| Variable | Effect | |-----------------|-------------------------------------------------------------------------| | LOG_LEVEL | The minimum severity, e.g. debug. Invalid values are ignored. | | LOG_FORMAT | json or pretty. | | LOG_TIMESTAMP | iso, time, or off / false to drop the timestamp. | | NO_COLOR | Disables colors, per the NO_COLOR convention. | | FORCE_COLOR | Forces colors on, even when the output is not a TTY. |

LOG_LEVEL=debug LOG_FORMAT=json node index.js

API

| Export | Description | |--------------------------------------------------------------------------|--------------------------------------------------------------------------| | logger (also the default export) | The default logger, configured from the environment. | | createLogger(options?) | Creates a logger from the environment, with options taking precedence. | | Logger | The logger class, for when the environment should be ignored. | | optionsFromEnvironment(environment?) | Reads logger defaults from an environment object. | | LOG_LEVELS, LEVEL_SEVERITY, LOG_METHODS | The level and method tables the logger is built on. | | isLogLevel(value), shouldLog(level, threshold) | Level helpers. | | formatPretty, formatJson, formatTimestamp, serializeArgs | The rendering primitives, exported for custom formatting. | | createStyler(isEnabled), isColorSupported(destination, environment?) | The ANSI helpers. |

Types are shipped with the package: LoggerOptions, LogFormat, LogLevel, LoggableLevel, LogMethod, MethodSpec, LogEntry, TimestampFormat, Destination, Styler and StyleName.