alexeyraspopov / picocolors

The tiniest and the fastest library for terminal output formatting with ANSI colors

picocolors

The tiniest and the fastest library for terminal output formatting with ANSI colors.

import pc from "picocolors"

console.log(
  pc.green(`How are ${pc.italic(`you`)} doing?`)
)

• No dependencies.
• 14 times smaller and 2 times faster than chalk.
• Used by popular tools like PostCSS, SVGO, Stylelint, and Browserslist.
• Node.js v6+ & browsers support. Support for both CJS and ESM projects.
• TypeScript type declarations included.
• NO_COLOR friendly.

Motivation

With picocolors we are trying to draw attention to the node_modules size problem and promote performance-first culture.

Prior Art

Credits go to the following projects:

• Nanocolors by @ai
• Colorette by @jorgebucaran
• Kleur by @lukeed
• Colors.js by @Marak
• Chalk by @sindresorhus

Benchmarks

The space in node_modules including sub-dependencies:

$ node ./benchmarks/size.js
Data from packagephobia.com
  chalk       101 kB
  cli-color  1249 kB
  ansi-colors  25 kB
  kleur        21 kB
  colorette    17 kB
  nanocolors   16 kB
+ picocolors    7 kB

Library loading time:

$ node ./benchmarks/loading.js
  chalk          6.167 ms
  cli-color     31.431 ms
  ansi-colors    1.585 ms
  kleur          2.008 ms
  kleur/colors   0.773 ms
  colorette      2.476 ms
  nanocolors     0.833 ms
+ picocolors     0.466 ms

Benchmark for simple use case:

$ node ./benchmarks/simple.js
  chalk         24,066,342 ops/sec
  cli-color        938,700 ops/sec
  ansi-colors    4,532,542 ops/sec
  kleur         20,343,122 ops/sec
  kleur/colors  35,415,770 ops/sec
  colorette     34,244,834 ops/sec
  nanocolors    33,443,265 ops/sec
+ picocolors    33,271,645 ops/sec

Benchmark for complex use cases:

$ node ./benchmarks/complex.js
  chalk            969,915 ops/sec
  cli-color        131,639 ops/sec
  ansi-colors      342,250 ops/sec
  kleur            611,880 ops/sec
  kleur/colors   1,129,526 ops/sec
  colorette      1,747,277 ops/sec
  nanocolors     1,251,312 ops/sec
+ picocolors     2,024,086 ops/sec

Usage

Picocolors provides an object which includes a variety of text coloring and formatting functions

import pc from "picocolors"

The object includes following coloring functions: black, red, green, yellow, blue, magenta, cyan, white, gray.

console.log(`I see a ${pc.red("red door")} and I want it painted ${pc.black("black")}`)

The object also includes following background color modifier functions: bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite.

console.log(
  pc.bgBlack(
    pc.white(`Tom appeared on the sidewalk with a bucket of whitewash and a long-handled brush.`)
  )
)

Besides colors, the object includes following formatting functions: dim, bold, hidden, italic, underline, strikethrough, reset, inverse.

for (let task of tasks) {
  console.log(`${pc.bold(task.name)} ${pc.dim(task.durationMs + "ms")}`)
}

The library provides additional utilities to ensure the best results for the task:

• isColorSupported — boolean, explicitly tells whether or not the colors or formatting appear on the screen

  import pc from "picocolors"
  
  if (pc.isColorSupported) {
    console.log("Yay! This script can use colors and formatters")
  }

• createColors(enabled) — a function that returns a new API object with manually defined color support configuration

  import pc from "picocolors"
  
  let { red, bgWhite } = pc.createColors(options.enableColors)

Replacing chalk

1. Replace package name in import:

   - import chalk from 'chalk'
   + import pico from 'picocolors'

2. Replace variable:

   - chalk.red(text)
   + pico.red(text)

3. Replace chains to nested calls:

   - chalk.red.bold(text)
   + pico.red(pico.bold(text))

4. You can use colorize-template to replace chalk’s tagged template literal.

   + import { createColorize } from 'colorize-template'
   
   + let colorize = createColorize(pico)
   - chalk.red.bold`full {yellow ${"text"}}`
   + colorize`{red.bold full {yellow ${"text"}}}`