Skip to main content

Logger

Deliver consistent log output across local runs and CI without wiring custom formatting by hand.

Summary

The Logger battery locks down terminal output with environment-aware level gating, scope-able helpers, and ANSI-safe formatting so debug chatter stays in dev and production logs stay spotless.

Why Use This Battery?

  1. Delivers out-of-the-box logging, so you skip the busywork of customizing console wrappers.
  2. Automatically adjusts verbosity based on NODE_ENV and allows you to override through LOG_LEVEL.
  3. Produces color-coded output by default, with optional timestamps for easier reading.

Capabilities

  • Messages with line breaks are indented on subsequent lines for readability.
  • Automatically adapts to environment signals (frontend vs. backend) and the LOG_LEVEL setting.
  • Add timestamps to prefixes by setting the LOG_TIME environment flag.
  • Teams can call Logger.customize to reuse shared options like padding or component names.

Usage

Good to Know

Examples use TypeScript, but the API is identical in JavaScript (ESM-only).

Development Logging

Logger.dev is meant for local debugging (enhanced version of console.log). Enable the no-logger-dev ESLint rule to protect you from leaking logs.

Output Examples

Customize

Tune the runtime behavior with the environment variables and options below.

Environment Variables

Before you run a script, set LOG_LEVEL for the right verbosity and toggle LOG_TIME to 'true' when you want timestamped output.

SettingTypeDefaultDescription
LOG_LEVELstring'debug' when NODE_ENV=development; 'warn' for browser production; otherwise 'info'Minimum level emitted; accepts debug, dev, info, warn, error.
LOG_TIMEstring—Set to the string 'true' to prefix each message with an ISO timestamp.
NODE_ENVstring—Controls the default LOG_LEVEL; set to 'development' for chatty logs.

Options

Call Logger.customize({ ... }) to spin up scoped loggers, giving each phase a name and using padding to separate sections in the terminal.

Scope Tags

Scope tags (name, type, and purpose options) render only when LOG_LEVEL is 'debug' or NODE_ENV is 'development'.

OptionTypeDefaultDescription
namestring—The first segment shows who is emitting (e.g., function name).
type'function' | 'method' | 'test'—The second segment highlighting what is emitting.
purposestring—The third segment that calls out the intent of this log.
padTopnumber0Inserts that many blank lines before the payload (values below 0 are ignored).
padBottomnumber0Inserts that many blank lines after the payload (values below 0 are ignored).

Troubleshooting

  • Nothing prints to the terminal — Check LOG_LEVEL; if it is set higher than your message severity, downgrade it or unset it entirely.
  • Colors missing in CI logs — Some environments disable ANSI. Export FORCE_COLOR=1 or rely on timestamps/names for identification.
  • Extra blank lines surround messages — Review padTop / padBottom on customized loggers and reset them to 0 when not needed.
  • Timestamps not appearing — LOG_TIME expects the exact string 'true', not any other truthy value.
  • Debug logs still hidden locally — Confirm NODE_ENV is 'development' or explicitly set LOG_LEVEL=debug.