fude: A JavaScript repository from msanguineti

nodejs library for terminal text style formatting.

Features

Fast loading, fast performing
NO_COLOR friendly
TypeScript support (types included)
Automatic color detection
Overrideable color support (e.g. stdout, stderr, etc.)
No dependencies
8-bit, 24-bit color support
Proper bold, dim support
Proper reset support (optional with env variable or argument flag)
Tagged template literals support (with helper library)

ATTENTION: version 3.0.0 BREAKS backward compatibility with previous versions!

Install

$ npm i fude

Usage

Import fude the way you need it:

import { bgRed, white, bgWhite, black } from 'fude'
console.log(bgRed(white`筆`) + bgWhite(black` fude `))

const { bgRed, white, bgWhite, black } = require('fude')
console.log(bgRed(white`筆`) + bgWhite(black` fude `))

import fude from 'fude'
console.log(fude.bgRed(fude.white`筆`) + fude.bgWhite(fude.black` fude `))

const fude = require('fude')
console.log(fude.bgRed(fude.white`筆`) + fude.bgWhite(fude.black` fude `))

Styles

Character styles applicable to text.

Modifiers	Fg colors (normal)	Fg colors (bright)	Bg colors (normal)	Bg colors (bright)
`reset`	`black`	`blackBright`	`bgBlack`	`bgBlackBright`
`bold`	`red`	`redBright`	`bgRed`	`bgRedBright`
`dim`	`green`	`greenBright`	`bgGreen`	`bgGreenBright`
`italic`	`yellow`	`yellowBright`	`bgYellow`	`bgYellowBright`
`underline`	`blue`	`blueBright`	`bgBlue`	`bgBlueBright`
`inverse`	`magenta`	`magentaBright`	`bgMagenta`	`bgMagentaBright`
`hidden`	`cyan`	`cyanBright`	`bgCyan`	`bgCyanBright`
`strikethrough`	`white`	`whiteBright`	`bgWhite`	`bgWhiteBright`

blackBright is also gray or grey
bgBlackBright is also bgGray or bgGrey

8-bit and 24-bit color support

Examples:

import f from 'fude'

console.log(f.ansi256(9)('red'))

console.log(f.rgb(255, 99, 71)('tomato text'))

console.log(f.hexBg('#FFBF47')('mustard background'))

Color support override

Programmatically

It is possible to override the automatic detection of the color support level. This might be useful for when piping the output to a file, or splitting the stderr and stdout streams.

import f from 'fude'

const noColors = f.Fude({ level: 0 }) // color support levels: 0 none, 1 basic, 2 ANSI 256, 3 Truecolor

console.log(f.red('red text!')) // in red

console.log(noColors.red('red text?')) // nope, text is plain

const errorStream = f.Fude({ level: 'stderr' }) // get the support level of `stderr` or `stdout`

console.error(errorStream.red('Error!')) // this will be red only if stderr supports colors

Environment variables

FORCE_COLOR can be used to override the automatic detection of the color support level. (see NodeJS TTY)

Valid values are:

0: Switch off color support
1: Basic color support
2: ANSI 256 color support
3: Truecolor color support

Any other value will be ignored (switch on auto color detection).

# color support set to basic colors
FORCE_COLOR=1 node example.js

NO_COLOR (also NODE_DISABLE_COLORS) can be used to switch off the color support.

# color support set to none
NO_COLOR= node example.js

FORCE_COLOR overrides both NO_COLOR and NODE_DISABLE_COLORS

CLI Arguments `--color[=0|1|2|3]` and `--no-color`

# --color without a value will set color support to auto detection (the default)
$ node example.js --color
# color support set to none
$ node example.js --no-color
# color support set to truecolor
$ node example.js --color=3

Proper `bold` and `dim` support

Given a string like this (with embedded dims and bolds)

import c from 'fude' // 'chalk', 'colorette', 'picocolors' or 'kleur'

const output =
  c.dim(' dim ' + c.bold(' bold ') + ' dim ') +
  c.bold(' bold ' + c.dim(' dim ') + ' bold ')

We get these results:

fude handles bold and dim properly by default.

Proper `reset` support

fude does not properly handle reset by default. This is the behaviour of every other CLI text styling library. The reason is that the check for reset is expensive, and it is not necessary for most cases.

To fix this, you can use the env variable HANDLE_RESET or the argument flag --handle-reset.

# handle reset
HANDLE_RESET= node example.js

# handle reset
node example.js --handle-reset

This is what I mean by properly handling reset:

Tagged Template Literals

Tagged template literals are supported with a helper library such as colorize-template.

import fude from 'fude'
import { createColorize } from 'colorize-template'

const colorize = createColorize(fude)

console.log(colorize`{bgRed {white 筆}}{bgWhite ${fude.rgb(0, 0, 0)('fude ')}}`)

What's in a name?

Fude (筆 - Japanese pronunciation: [ɸɯ̟ᵝde̞] foo-de -- de as in dentist) is Japanese for a calligraphy brush. Since there isn't really a plural form in Japanese, in this case 'fude' can be interpreted as 'brushes'.

Thanks & Credits

Thanks to the authors of and contributors to colorette and picocolors for their work which I have borrowed heavily to improve performance in v3.0.

Also, thanks to chalk because it is always the slowest and everyone badmouths it, but it has a gazillion of installations and everyone envies it.

Benchmarks? Every CLI text styling library has its own benchmarks and it is always the fastest... go figure.

Changelog

The changelog can be found on the Releases page.

Contributing

PRs welcomed here.

Authors and license

Mirco Sanguineti and contributors.

MIT License, see the included LICENCE file.

msanguineti/fude