colorix v2.0.2

Colorix

Colorix provides a simple way to define and layer color presets, and helps you recognize and track ANSI escape sequences in your code. Each module uses template literals (and a bit of magic 🪄) to construct a type representation of the color sequences applied to your strings.

import cx from 'colorix'

const goblinInk = cx('bgGreen', 'black', 'bold')
console.log(goblinInk('hello goblin', '!'))

With TypeScript, always know when a string has hidden characters

declare const goblinMessage: Colorix<['bgGreen', 'black', 'bold'], ['hello goblin', '!']>
// => `\u001B[42;30;1mhello goblin!\u001B[0m`

This is useful with primitive strings as well

declare const goblinMessage: Colorix<['bgGreen', 'black', 'bold'], [string, ...string[]]>
// => `\u001B[42;30;1m${string}\u001B[0m`

How it works

// create a theme by passing colors to the first function.
declare const cx: <Colors extends Color[]>(
  ...colors: Colors
) => // then pass stringifiable values to the second function to colorize them.
<Strings extends Stringifiable[]>(
  ...strings: Strings
) => // the returned value is an ansified string.
Colorix<Colors, Strings>

Installation

Add colorix to your project using your favorite package manager.

NPM

npm install colorix

PNPM

pnpm add colorix

Yarn

yarn add colorix

How to support terminals without color

safe, colorixSafe, cxs

You can use safe to check if the terminal supports color before applying a preset.

import cx, { safe } from 'colorix'
const errorInk = cx('bold', 'red')

console.log(errorInk('That tasted purple...'))
// "\u001B[mThat tasted purple...\u001B[0m"

console.log(safe(errorInk)('That tasted purple...'))
// "That tasted purple..." | "\u001B[mThat tasted purple...\u001B[0m"

Alternatively, use colorixSafe / cxs for an Ink preset that only applies colors if the terminal supports it.

import { cxs, colorixSafe } from 'colorix'

const safeErrorInk = cxs('bold', 'red') // or colorixSafe('bold', 'red')
console.log(safeErrorInk('That tasted purple...'))

Bonus Features

ColorixError

Fun way to colorize error messages without worrying about the terminal supporting color, or importing colorix / cx / safe into many files.

import { ColorixError } from 'colorix'

const BasicError = new ColorixError(
  'simple message that is always safe to display'
)
const PrettyError = new ColorixError((cx) =>
  cx(
    'white',
    'bgBlue',
    'dim',
    'bold'
  )(
    'Pretty Message',
    cx('reset')(' '),
    cx('underline', 'green')(
      'npmjs.com/package/colorix',
      cx('reset', 'italic')(' '),
      '(this message will always be stripped of color if supportsColor is false)'
    )
  )
)

throw PrettyError

PrettyError

For an "out-of-the-box" solution, use PrettyError. It provides the same naming and fallback message behavior as Colorix without an api for customizing the rest of the error.

import { PrettyError } from 'colorix'

const IOError = PrettyError('IOError', 'An unknown IO error occurred.')

try {
  throw new IOError()
} catch (err) {
  console.log(err)
}

try {
  throw new IOError('Illegal write operation.', 'more info...')
} catch (err) {
  console.log(err)
}

Exports

default, colorix, cx

Constants

Types

Color Tables