colorino

v0.19.3

Published

2 days ago

A super simple colorized logger that gets the most out of your terminal

0High
0Medium
0Low

simwai

ansi chalk color console kuler logger terminal

🎨 Colorino

The zero‑configuration, context‑aware console logger for Node.js and the browser—with smart theming and graceful color degradation.

Colorino automatically adapts its palette to your terminal or browser DevTools theme, and degrades colors gracefully so your logs stay readable and on‑brand even in limited environments

Demo Demo 2

Why use Colorino?

Plain console.log is colorless and inconsistent. Libraries like chalk let you style strings, but you have to decorate every message and manually manage color choices.

Colorino is different: it’s a "batteries-included" logging facade with beautiful, theme-aware colors and a familiar API. Instantly upgrade your logs everywhere.

Features

🎨 Smart Theming: Automatically detects dark/light mode and applies a high‑contrast base palette by default (Dracula for dark, GitHub Light for light); opt into a coordinated theme preset when you want richer colors.
🤘 Graceful Color Degradation: Accepts rich colors (hex/RGB) and automatically down‑samples to the best ANSI‑16/ANSI‑256/Truecolor match for the current environment.
🎯 CSS styling in DevTools (browser only): Use a dedicated helper to apply arbitrary CSS properties to specific console segments in Chrome, Firefox, and Safari DevTools, powered by the %c formatter.
🤝 Familiar API: If you know console.log, you already know Colorino: all standard log levels are supported.
🔀 Environment-Aware: Works in Node.js (ANSI color and truecolor) and all major Browsers (CSS styles).
⚡️ Fast, Lightweight: Minimal dependencies, works great in modern frameworks and CLIs.
🔒 Robust: Handles bad inputs and weird environments safely.
🛠️ Customizable: Override individual log colors for your own branding.

Installation

npm install colorino

Browser via CDN (unpkg)

You can use Colorino directly in the browser without any build step.

ESM (Recommended)

<!DOCTYPE html>
<html>
  <head>
    <script type="module">
      import { colorino } from 'https://unpkg.com/colorino/dist/cdn.min.mjs'

      colorino.info('Hello from the browser!')
      colorino.error('Something went wrong')
    </script>
  </head>
  <body></body>
</html>

For debugging (non‑minified):

<script type="module">
  import { colorino } from 'https://unpkg.com/colorino/dist/cdn.mjs'
</script>

UMD (Classic `<script>`)

<!DOCTYPE html>
<html>
  <head>
    <script src="https://unpkg.com/colorino/dist/cdn.min.js"></script>
    <script>
      // `colorino` is exposed as a global
      colorino.info('Hello from the UMD bundle!')
      colorino.error('Something went wrong')
    </script>
  </head>
  <body></body>
</html>

For debugging (non‑minified):

<script src="https://unpkg.com/colorino/dist/cdn.js"></script>

Usage

Quick Start

Just import the default instance and log away!

import { colorino } from 'colorino'

// All log levels automatically themed
colorino.error('A critical error!')
colorino.warn('A warning message.')
colorino.info('Useful info logging.')
colorino.log('A plain log.')
colorino.debug('Debug with objects:', { x: 5, y: 9 })
colorino.trace('Tracing app start...')

Creating a Custom Logger

Need your own colors or different settings? Use the factory to create as many loggers as you want (each with its own palette and options):

import { createColorino } from 'colorino'

const myLogger = createColorino({
  // Palette (partial)
  error: '#ff007b',
  info: '#3498db',
})
myLogger.error('Critical!')
myLogger.info('Rebranded info!')

Options & Theme Overrides

createColorino(palette?, options?) accepts:

| Option | Type | Default | Description | | -------------------------- | ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | theme | ThemeOption (see below) | 'auto' | Control the active color theme or force a specific mode. | | maxDepth | number | 5 | Maximum depth when pretty-printing objects in log output. | | areNodeFramesVisible | boolean | true | Show Node.js internal frames (e.g., node:internal/...) in stack traces. | | areColorinoFramesVisible | boolean | false | Show Colorino internal frames in stack traces (useful for debugging Colorino). | | isOsc11Enabled | boolean | true | Enables auto light/dark theme detection, but can eventually lead to crashes/unwanted behaviour. Then, just set this env variable to false. |

theme accepts three types of values:

'auto' (Default): Automatically detects your terminal or browser theme (dark/light) and applies the matching default preset. (Pls use Terminal on Windows if you wanna use this.)
'dark' | 'light': Forces the logger into a specific mode using the default preset for that mode.
ThemeName: Forces a specific built-in palette (e.g., 'dracula').

Available Theme Presets

Pass any of these names to the theme option to use a specific palette:

| Theme Name | Type | Description | | -------------------- | ------------------------- | --------------------------------------- | | 'dracula' | Dark (High Contrast) | Vibrant pinks, purples, and cyans. | | 'catppuccin-mocha' | Dark (Low Contrast) | Soothing pastel colors. | | 'github-light' | Light (High Contrast) | Clean, sharp, high-contrast. | | 'catppuccin-latte' | Light (Low Contrast) | Warm, cozy light mode with soft colors. |

In auto mode, Colorino uses dracula in dark environments and github-light in light environments.

Examples

1. Default palette with custom branding: Set only the colors you care about; everything else uses the detected base theme or your explicitly selected theme.

// Only customize error and warn
const myLogger = createColorino({
  error: '#ff007b',
  warn: '#ffa500',
})

// Detected dark terminal (uses dracula as base):
// - error: #ff007b (your custom red)
// - warn: #ffa500 (your custom orange)
// - info: #8be9fd (dracula cyan)
// - log: #f8f8f2 (dracula foreground)
// - debug: #bd93f9 (dracula purple)
// - trace: #6272a4 (dracula comment)

// Detected light terminal (uses github-light as base):
// - error: #ff007b (your custom red)
// - warn: #ffa500 (your custom orange)
// - info: #0366d6 (github blue)
// - log: #24292e (github text)
// - debug: #586069 (github gray)
// - trace: #6a737d (github gray-light)

2. Use a specific preset: Instant branding with zero configuration.

// Forces the Dracula palette
const draculaLogger = createColorino({}, { theme: 'dracula' })

3. Customize a preset: Overlay your own colors on top of a built-in theme.

// Use GitHub Light but with a custom error color
const myLogger = createColorino({ error: '#ff007b' }, { theme: 'github-light' })

4. Force a specific mode (uses defaults): Useful for environments where detection fails.

// Forces dark mode using the default palette
const darkLogger = createColorino({}, { theme: 'dark' })

Tip: Forcing 'dark' or 'light' bypasses automatic theming, ensuring predictable colors in environments with unknown or unsupported theme detection (like some CI pipelines, dumb terminals, or minimal browsers).

Customization

Use your brand colors by passing a partial palette to the createColorino factory. Any log levels you don't specify will use the detected default colors unless you explicitly select a theme preset.

Colorino always targets the highest color fidelity supported by the environment. If your palette uses hex colors but only ANSI‑16 is available, Colorino computes the nearest ANSI color so your branding stays recognizable, even on limited terminals.

If you pass an invalid color value (e.g. malformed hex) in a custom palette, Colorino throws an InputValidationError at creation time so broken palettes fail fast.

import { createColorino } from 'colorino'

// Custom error color; others use theme defaults
const myLogger = createColorino({ error: '#ff007b' })

myLogger.error('Oh no!') // Uses your custom color
myLogger.info('Still styled by theme.') // Uses the default theme color

Supported Environment Variables

Colorino auto-detects your environment and color support, but you can override behavior using these standard environment variables (compatible with Chalk):

| Variable | What It Does | Example | | ---------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------ | | NO_COLOR | Removes all colors from output (any value works) | NO_COLOR=1 node app.js | | FORCE_COLOR | Override color detection: 0=none, 1=basic (16 colors), 2=extended (256), 3=full RGB | FORCE_COLOR=3 node app.js | | CLICOLOR | Set to 0 to disable colors | CLICOLOR=0 node app.js | | CLICOLOR_FORCE | Set to 1 to force colors even when output is piped/redirected | CLICOLOR_FORCE=1 node app.js | | TERM | Your terminal type (e.g., xterm-256color enables 256 colors) — auto-set by your terminal | TERM=xterm-256color | | COLORTERM | Set to truecolor or 24bit to enable full RGB colors — auto-set by modern terminals | COLORTERM=truecolor | | TERM_PROGRAM | Terminal program name (e.g., WezTerm, iTerm2) — auto-set by terminals for OSC 11 support | (automatic) | | VTE_VERSION | VTE library version — auto-set by GNOME Terminal and VTE-based terminals for OSC 11 detection | (automatic) | | WT_SESSION | Auto-set by Windows Terminal to enable advanced colors and OSC 11 theme detection (don't set manually) | (automatic) | | CI | Auto-set by GitHub Actions, GitLab CI, etc. to disable colors in build logs | CI=true |

Colorize Helper (Manual Overrides) (`colorize(text, hex)`)

Sometimes you want full control over a single piece of text without changing your global palette, e.g. when you use a mostly neutral theme but still want to highlight a keyword.

Colorino exposes a small colorize(text, hex) helper on every logger instance:

import { colorino } from 'colorino'

const important = colorino.colorize('IMPORTANT', '#ff5733')
colorino.info(important, 'Something happened')

When color is disabled (for example via NO_COLOR=1 or lack of support), colorize returns the plain input string, so your logs stay readable.

Browser‑only CSS Helper (`css(text, style)`)

In the browser, Colorino also exposes a css(text, style) helper that lets you apply arbitrary CSS to a single segment in DevTools using the %c formatter.

import { colorino } from 'colorino'

// Object form: keys are CSS properties, values are strings
const badge = colorino.css('NEW', {
  color: 'white',
  'background-color': '#e91e63',
  'font-weight': 'bold',
  'border-radius': '4px',
  padding: '2px 6px',
})

colorino.info('Release status:', badge, 'shipped')

Gradient Text (`gradient(text, startHex, endHex)`)

Create smooth color transitions across text with the gradient(text, startHex, endHex) method, available on all logger instances. Like the css and colorize helper.

import { colorino } from 'colorino'

const rainbow = colorino.gradient('Hello Gradient!', '#ff0000', '#0000ff')
colorino.log(rainbow)

Requires ANSI-256 or Truecolor support (most modern terminals).

Colorino vs. Chalk

| Feature | 🎨 Colorino | 🖍️ Chalk | | ----------------------- | ------------------------ | ----------------- | | Out-of-box logs | ✔ themed, all log levels | ✘ string styling | | Zero-config | ✔ | ✘ manual, per-use | | Node + browser | ✔ | ✘ (Node only) | | CSS console logs | ✔ | ✘ | | Extensible / Composable | ✔ (via factory) | ✘ |

API Reference

The colorino package exports two main items:

1. `colorino` (default instance)

A pre-configured, zero-setup logger instance. Just import and use.

.log(...args)
.info(...args)
.warn(...args)
.error(...args)
.debug(...args)
.trace(...args)

2. `createColorino(palette?, options?)` (factory)

A factory function to create your own customized logger instances.

palette (Partial<Palette>): An object to override default colors for specific log levels (e.g., { error: '#ff007b' }).
options (ColorinoOptions): An object to control behavior:
- theme: 'dark' | 'light' (default auto): Force a specific theme instead of auto-detecting.

Extending Colorino

Colorino is designed for composition: create a base logger via createColorino(), then extend it by inheriting from the base and overriding only the methods you need.

Use Case: Automatic File/Context Info

This example prefixes every .info() and .error() call with best‑effort caller context (file/line) derived from a synthetic Error stack.

import {
  createColorino,
  type Colorino,
  type ColorinoOptions,
  type Palette,
} from 'colorino'

type ColorinoType = ReturnType<typeof createColorino>

function getCallerContext(): string {
  const err = new Error()
  if (!err.stack) return 'unknown'

  const lines = err.stack.split('\n').slice(2) // skip "Error" + current frame
  const frame = lines[0] ?? ''

  const match =
    frame.match(/at (.+?) \((.+?):(\d+):\d+\)/) ??
    frame.match(/at (.+?):(\d+):\d+/)

  if (!match) return frame.trim() || 'unknown'

  const [_, maybeFn, fileOrLine, maybeLine] = match
  const file = maybeLine ? fileOrLine : maybeFn
  const line = maybeLine ?? fileOrLine

  return `${file}:${line}`
}

export function createContextLogger(
  palette?: Partial<Palette>,
  options?: ColorinoOptions
): ColorinoType {
  const base = createColorino(palette, options)

  // Inherit all default methods from the base logger...
  const logger = Object.create(base) as ColorinoType // Object.create uses `base` as the prototype.

  // ...and override only what you need.
  Object.assign(logger, {
    // Object.assign copies these methods onto `logger`.
    info(...args: unknown[]) {
      base.info(`[${getCallerContext()}]`, ...args)
    },
    error(...args: unknown[]) {
      base.error(`[${getCallerContext()}]`, ...args)
    },
  })

  return logger
}

// Usage
const logger = createContextLogger({}, { theme: 'dracula' })
logger.info('User created', { id: 123 })
logger.error('Failed to load user', { id: 456 })

Why This Pattern?

Composition > Inheritance: No fragile base class problems
Type Safe: TypeScript infers the return type correctly
Future Proof: Works even if colorino's internal implementation changes
Clean: No messing with super() or constructor parameters
Composable: You can layer multiple extensions

License

MIT