@mpen/ansi-colors

Small, composable ANSI formatters for Node.js, Bun, and other JavaScript environments. The main entry point exposes each formatter independently so bundlers can remove unused colors.

Installation

bun add @mpen/ansi-colors

Usage

Import the package as a namespace for a concise API:

import * as ac from '@mpen/ansi-colors'

console.log(ac.green('Success!'))
console.log(ac.bold(ac.red('Error: Access denied.')))

Named imports work well when bundle size matters. Each formatter is an independent export, so an ESM bundler can retain only the functions that are used:

import { bold, red } from '@mpen/ansi-colors'

console.log(bold(red('Error')))

Truecolor

rgb, bgRgb, hex, and bgHex create reusable 24-bit color formatters:

import * as ac from '@mpen/ansi-colors'

const purple = ac.hex('#7c3aed')
const bgGold = ac.bgHex('ffd700')
const orange = ac.rgb(255, 128, 0)

console.log(purple(bgGold(' Royal and Gold ')))
console.log(orange('Warning'))

RGB channels must be integers from 0 through 255. Hex colors may contain three or six digits, with an optional # prefix.

Explicitly enabling or disabling colors

The root exports automatically detect color support. Use the opt-in class entry point when support must be overridden:

import { AnsiColors } from '@mpen/ansi-colors/class'

const ac = new AnsiColors(false)
console.log(ac.red('This remains plain text.'))

new AnsiColors() uses automatic detection. The class contains the complete formatter collection and therefore is not intended to be tree-shaken per method.

Color support detection

Automatic detection considers NO_COLOR, FORCE_COLOR, CI, TERM, TTY status, and the Windows platform. The detected result is exported as isColorSupported.

API

| Category | Exports | | :----------------- | :------------------------------------------------------------------------------------------------------------------------------------ | | Modifiers | reset, bold, dim, italic, underline, inverse, hidden, strikethrough | | Text colors | black, red, green, yellow, blue, magenta, cyan, white, gray | | Bright text | blackBright, redBright, greenBright, yellowBright, blueBright, magentaBright, cyanBright, whiteBright | | Backgrounds | bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite | | Bright backgrounds | bgBlackBright, bgRedBright, bgGreenBright, bgYellowBright, bgBlueBright, bgMagentaBright, bgCyanBright, bgWhiteBright | | Custom colors | rgb, bgRgb, hex, bgHex |

Breaking change in 0.2.0

Version 0.2.0 removes the default export and createColors from the package root. Replace grouped API usage with either the tree-shakeable root exports or the class subpath:

// Before
import createColors from '@mpen/ansi-colors'
const ac = createColors(false)

// After: grouped, explicitly configurable API
import { AnsiColors } from '@mpen/ansi-colors/class'
const ac = new AnsiColors(false)

For automatically detected support, prefer import * as ac from '@mpen/ansi-colors' and call formatters directly.

License

MIT © Mark Penner. Portions derived from picocolors (Copyright © Oleksii Raspopov, Kostiantyn Denysov, Anton Verinov).