@bro-code/logger

A simple, chainable, fully customizable terminal logger with color support, config file integration, log levels, and environment-aware defaults for the @bro-code/* package ecosystem.

Installation

npm install @bro-code/logger

Quick Start

import logger from '@bro-code/logger';

logger.log('Hello world');
logger.info('Server started on port 3000');
logger.debug('Processing request', 1);
logger.error('Something went wrong', 0, { bold: true });

CommonJS

const logger = require('@bro-code/logger').default;

logger.log('Hello from CJS');

Features

• 7 log methods — log, info, warn, debug, error, json, code
• Chainable follow-on args — each additional argument indents one more tab level
• Array support — arrays display items at the same indent level, with optional bullets or numbering
• Fully customizable — colors, styles, borders, timestamps, labels, alignment, and more
• Config file — shared bro.config.json across all @bro-code/* packages
• Log levels — silent, error, warn, info, debug, verbose
• Environment-aware — auto-adjusts log level for production, development, and test
• Zero dependencies — built-in ANSI color support, no external packages
• Dual ESM/CJS — works in both module systems with full TypeScript types

Usage

Indentation (Tabs)

Every method accepts a tab parameter (second argument) that controls indentation. Each tab level is 2 spaces by default.

logger.log('no indent');         // "no indent"
logger.log('one tab', 1);       // "  one tab"
logger.log('two tabs', 2);      // "    two tabs"

Chainable Follow-On Args

Additional arguments after the options parameter each increase the indent by one level:

logger.log('something', 0, null, 'like', 'this');
// something
//   like
//     this

Arrays

When a follow-on arg is an array, each item prints at the same indent level:

logger.log('items', 0, null, ['apples', 'bananas', 'oranges']);
// items
//   apples
//   bananas
//   oranges

Bullets and Numbered Lists

logger.log('shopping list', 0, { bullets: true }, ['milk', 'eggs', 'bread']);
// shopping list
//   - milk
//   - eggs
//   - bread

logger.log('steps', 0, { numbered: true }, ['first', 'second', 'third']);
// steps
//   1. first
//   2. second
//   3. third

JSON Output

logger.json({ name: '@bro-code/logger', version: '2026.0.0' });
// Pretty-printed, colorized JSON output

Code Output

logger.code('const x = 42;\nconsole.log(x);', 0, { codeLineNumbers: true });
// 1  const x = 42;
// 2  console.log(x);

Options

Every log method accepts an options object as the third argument:

logger.log('message', tab, options, ...followOnArgs);

Text Styling

| Option | Type | Description | | --------------- | --------- | -------------------------- | | color | string | Foreground color | | bgColor | string | Background color | | bold | boolean | Bold text | | dim | boolean | Dim/faint text | | italic | boolean | Italic text | | underline | boolean | Underlined text | | strikethrough | boolean | Strikethrough text | | inverse | boolean | Swap foreground/background | | hidden | boolean | Hidden text |

Available colors: black, red, green, yellow, blue, magenta, cyan, white, gray, brightRed, brightGreen, brightYellow, brightBlue, brightMagenta, brightCyan, brightWhite

Available background colors: bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite, bgGray

Indentation

| Option | Type | Default | Description | | --------- | -------- | ------- | ------------------------- | | tabSize | number | 2 | Spaces per tab level |

List Formatting

| Option | Type | Default | Description | | ------------ | --------- | ------- | -------------------------------- | | bullets | boolean | false | Prefix array items with a bullet | | bulletChar | string | '-' | Custom bullet character | | numbered | boolean | false | Number array items |

Line Formatting

| Option | Type | Description | | ----------- | -------- | --------------------------------------- | | prefix | string | String prepended to every output line | | suffix | string | String appended to every output line | | separator | string | Separator between follow-on items |

Timestamp

| Option | Type | Description | | ----------------- | --------- | ---------------------------------------------------- | | timestamp | boolean | Show a timestamp | | timestampFormat | string | Format: 'iso', 'locale', 'time', or custom |

Labels

| Option | Type | Description | | ----------- | --------- | ---------------------------------------- | | label | string | Custom label text | | showLabel | boolean | Show/hide the method label | | labelColor| string | Color for the label text |

Spacing

| Option | Type | Description | | --------------- | --------- | ------------------------------- | | newlineBefore | boolean | Blank line before log | | newlineAfter | boolean | Blank line after log | | padBefore | number | Number of blank lines before | | padAfter | number | Number of blank lines after |

Border / Box

| Option | Type | Description | | ------------- | -------- | -------------------------------------------------- | | border | boolean| Wrap output in a border box | | borderColor | string | Border color | | borderStyle | string | 'single', 'double', 'round', or 'bold' |

JSON Options

| Option | Type | Default | Description | | -------------- | --------- | ------- | ----------------------------- | | jsonIndent | number | 2 | JSON indentation spaces | | jsonColors | boolean | true | Colorize JSON output | | jsonDepth | number | ∞ | Max display depth | | jsonSortKeys | boolean | false | Sort object keys |

Code Options

| Option | Type | Default | Description | | ----------------- | --------- | ------- | ----------------------- | | codeLineNumbers | boolean | false | Show line numbers | | codeBorder | boolean | false | Border around code | | codeLanguage | string | — | Language hint |

Behavior

| Option | Type | Description | | -------- | --------- | ------------------------------------ | | silent | boolean | Suppress this log | | raw | boolean | Output without formatting | | stream | string | 'stdout' or 'stderr' |

Width / Alignment

| Option | Type | Description | | ---------- | -------- | ------------------------------------------ | | maxWidth | number | Max line width (wraps text) | | align | string | 'left', 'center', or 'right' |

Configuration

bro.config.json

Create a bro.config.json file in your project root. This config is shared across all @bro-code/* packages:

{
  "logger": {
    "level": "debug",
    "env": "development",
    "tabSize": 2,
    "defaults": {
      "timestamp": true,
      "showLabel": true
    },
    "methods": {
      "log":   { "color": "white" },
      "info":  { "color": "cyan" },
      "debug": { "color": "gray" },
      "warn":  { "color": "yellow" },
      "error": { "color": "red", "bold": true },
      "json":  { "color": "green" },
      "code":  { "color": "yellow" }
    }
  }
}

Environment Variables

| Variable | Description | | --------------- | ------------------------------------------------ | | BRO_LOG_LEVEL | Override log level (silent, error, warn, info, debug, verbose) | | BRO_ENV | Override environment (production, development, test); the config's env beats it | | NODE_ENV | Fallback environment variable | | NO_COLOR | Disable color output (colors are enabled by default) |

Log Levels

| Level | Shows | Default Environment | | --------- | ---------------------------------- | ---------------------- | | silent | Nothing | — | | error | error | test | | warn | error, warn | production | | info | error, warn, info, log, json, code | — | | debug | All of the above + debug | development | | verbose | Everything | — |

Programmatic Configuration

import { BroLogger } from '@bro-code/logger';

const logger = new BroLogger({
  level: 'debug',
  tabSize: 4,
  defaults: {
    timestamp: true,
    bold: true,
  },
  methods: {
    error: { color: 'brightRed', border: true },
  },
});

API

Methods

All methods return the logger instance (this) and share the same signature:

method(message: unknown, tab?: number, options?: BroLogOptions | null, ...args: unknown[]): BroLogger

| Method | Default Color | Default Label | Stream | | -------- | ------------- | ------------- | -------- | | log | white | — | stdout | | info | cyan | [INFO] | stdout | | warn | yellow | [WARN] | stderr | | debug | gray | [DEBUG] | stdout | | error | red | [ERROR] | stderr | | json | green | — | stdout | | code | yellow | — | stdout |

Properties

| Property | Type | Description | | --------- | ---------- | ---------------------------- | | level | LogLevel | Get/set the current log level | | tabSize | number | Get/set the tab size |

reload()

Reload configuration from the bro.config.json file.

logger.reload();

Color helpers: fg(), bg() and style()

A log method colors its whole line. To color only parts of one, build the text with the helpers and log it with no line color ({ color: undefined }), so the method's default color doesn't wrap it:

import logger, { fg, style } from '@bro-code/logger';

logger.log(`${fg('✓', 'green')} adds an item ${fg('3 ms', 'gray')}`, 0, { color: undefined });
logger.log(style('Summary', 'bold', 'underline'), 0, { color: undefined });

| Function | Returns | | -------- | ------- | | fg(text, color?) | text in a foreground ColorName ('green', 'gray', 'brightRed', ...) | | bg(text, color?) | text on a background BgColorName ('bgYellow', ...) | | style(text, ...styles) | text with each StyleName given: 'bold', 'dim', 'italic', 'underline', 'inverse', 'hidden', 'strikethrough' |

Each ends with a reset, so the text after it is unstyled. With no color given, or no color support (NO_COLOR set), they return text unchanged. Borders measure lines without the codes, so a boxed line still lines up.

Other exports

| Export | What it does | | ------ | ------------ | | supportsColor() | false when NO_COLOR is set (or outside Node), else true; every color and style follows it | | loadConfig(cwd?) | Reads bro.config.json (or bro.config.js, bro.config.cjs) in cwd, the current folder by default; {} when there is none or it doesn't parse. The result is cached for the process | | getLoggerConfig(cwd?) | The loaded config's logger section, or {} | | resetConfigCache() | Clears that cache, so the next load reads the file again | | LOG_LEVEL_PRIORITY | Each level's number, from silent (0) to verbose (5) | | METHOD_LEVEL | The level each method needs to show: error → 'error', warn → 'warn', debug → 'debug', the rest → 'info' | | shouldLog(activeLevel, methodLevel) | Whether a method needing methodLevel shows at activeLevel | | resolveLogLevel(envVar?, configLevel?, env?) | A logger's starting level: envVar when it names a level, else configLevel, else the environment's default from the Log Levels table |

new BroLogger(config) uses the config given in place of the file's logger section; reload() reads the file again.

The types are exported too: BroLogOptions, BroLoggerConfig, BroConfig, MethodDefaults, LogLevel, ColorName, BgColorName, StyleName, BorderStyle, TextAlign and StreamTarget.

License

MIT © Bro Code Technologies

Changelog

[2026.1.0] - 2026-11-11

Added

• fg(), bg() and style() are exported, so one line can mix colors, with the StyleName type that style() takes.

Fixed

• BRO_ENV overrides NODE_ENV, as documented. Before, NODE_ENV won, so BRO_ENV only counted where NODE_ENV was unset, and a build tool that set NODE_ENV made it do nothing.

Documentation

• The README covers every export: supportsColor(), the config loaders, the level helpers and the types.
• The features list counts seven log methods, and the license badge links the package's LICENSE.

[2026.0.3] - 2026-04-23

Fixed

• CJS build: tsconfig.cjs.json corrected to emit real CommonJS output. The previous module: Node16 setting combined with "type": "module" caused TypeScript to emit ESM syntax (export {) into dist/cjs/, which broke require() in Node.js environments.

[2026.0.2] - 2026-04-19

Documentation

• Added usage examples for all options in the README

[2026.0.1] - 2026-04-19

Fixed

• Colors are now enabled by default — only NO_COLOR env var disables them. Previously, colors were disabled when process.stdout.isTTY was false (e.g., spawned child processes), causing all output to appear uncolored.
• Multi-line log messages now indent continuation lines by one tab level for readability.

[2026.0.0] - 2026-04-17

Added

• Initial release
• Log methods: log, info, warn, debug, error, json, code
• Chainable follow-on arguments with progressive indentation
• Array support with bullets and numbered lists
• Full text styling: color, bgColor, bold, dim, italic, underline, strikethrough, inverse
• Border/box wrapping with single, double, round, and bold styles
• Timestamps with iso, locale, and time formats
• Configurable labels per method
• Prefix/suffix per line
• Text wrapping and alignment
• JSON pretty-printing with colorized output, depth limiting, key sorting
• Code display with optional line numbers and borders
• bro.config.json shared config file support
• Environment-aware log levels (production → warn, development → debug, test → error)
• BRO_LOG_LEVEL, BRO_ENV, NODE_ENV environment variables
• NO_COLOR and FORCE_COLOR support
• Dual ESM/CJS output with TypeScript declarations
• Zero runtime dependencies