🎨 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?
- Features
- Installation
- Browser via CDN (unpkg)
- ESM (Recommended)
- UMD (Classic



`

For debugging (non‑minified):

`html

`

$3

`html








`

For debugging (non‑minified):

`html

`

Usage

$3

Just import the default instance and log away!

`typescript
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...')
`

$3

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):

`typescript
import { createColorino } from 'colorino'

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

$3

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:

1. '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.)
2. 'dark' | 'light': Forces the logger into a specific mode using the default preset for that mode.
3. 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.

`typescript
// 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.

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

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

`typescript
// 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.

`typescript
// 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).

$3

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.

`typescript
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
`

$3

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 |

$3

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:

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

$3

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.

`ts
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')
`

$3

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

`ts
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:

$3

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

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

$3

A factory function to create your own customized logger instances.

- palette (Partial): 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.

$3

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

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

type ColorinoType = ReturnType

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,
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 })
`

$3

- 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