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. 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.

Basics

import { Logger } from '@cbnventures/nova/toolkit';

Logger.debug('Loading configuration');
Logger.info('Build finished');
Logger.warn('Cache miss; re-installing dependencies');
Logger.error('Tests failed', new Error('some error'));
Logger.dev('Only used in development');

Scoped logger

import { Logger } from '@cbnventures/nova/toolkit';

const log = Logger.customize({
  name: 'SomeClass.init',
  padTop: 0,
  padBottom: 1,
});

log.debug('Checking existing project state');
log.info('Initializing project');
log.warn('Optional dependency missing; skipping feature');
log.error('Aborting due to validation errors');
log.dev('Only used in development');

Multiline alignment

import { Logger } from '@cbnventures/nova/toolkit';

Logger.info([
  'Scanning workspace',
  '- packages: 4',
  '- apps: 1',
  `- node: ${process.version}`,
].join('\n'));

Logger.error(
  [
    'Release blocked:',
    '- Missing env: GITHUB_TOKEN',
    '- Failing tests: 3',
  ].join('\n'),
  new Error('some error'),
);

Output Examples

Basics

Scoped logger

Multiline alignment

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.

Setting	Type	Default	Description
LOG_LEVEL	string	'debug' when NODE_ENV=development; 'warn' for browser production; otherwise 'info'	Minimum level emitted; accepts debug, info, warn, error.
LOG_TIME	string	—	Set to the string 'true' to prefix each message with an ISO timestamp.
NODE_ENV	string	—	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 render only when LOG_LEVEL=debug.

Option	Type	Default	Description
name	string	—	The first segment in the dimmed scope tag (for example [name::type::purpose]). Shown when LOG_LEVEL is 'debug' or NODE_ENV is 'development'.
type	'function' | 'method' | 'test'	—	The second segment highlighting what is emitting (for example [name::type::purpose]). Shown when LOG_LEVEL is 'debug' or NODE_ENV is 'development'.
purpose	string	—	The third segment that calls out the intent (for example [name::type::purpose]). Shown when LOG_LEVEL is 'debug' or NODE_ENV is 'development'.
padTop	number	0	Inserts that many blank lines before the payload (values below 0 are ignored).
padBottom	number	0	Inserts 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. — Ensure LOG_TIME is set to the string 'true', not any other truthy value.
• Debug logs still hidden locally. — Confirm NODE_ENV is 'development' or explicitly set LOG_LEVEL=debug.