File size: 4,995 Bytes
bc20498 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 |
# picocolors
The tiniest and the fastest library for terminal output formatting with ANSI colors.
```javascript
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`](https://no-color.org/) 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](https://github.com/ai/nanocolors) by [@ai](https://github.com/ai)
- [Colorette](https://github.com/jorgebucaran/colorette) by [@jorgebucaran](https://github.com/jorgebucaran)
- [Kleur](https://github.com/lukeed/kleur) by [@lukeed](https://github.com/lukeed)
- [Colors.js](https://github.com/Marak/colors.js) by [@Marak](https://github.com/Marak)
- [Chalk](https://github.com/chalk/chalk) by [@sindresorhus](https://github.com/sindresorhus)
## Benchmarks
The space in node_modules including sub-dependencies:
```diff
$ 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:
```diff
$ 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:
```diff
$ 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:
```diff
$ 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
```javascript
import pc from "picocolors"
```
The object includes following coloring functions: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `gray`.
```javascript
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` and bright variants `bgBlackBright`, `bgRedBright`, `bgGreenBright`, `bgYellowBright`, `bgBlueBright`, `bgMagentaBright`, `bgCyanBright`, `bgWhiteBright`.
```javascript
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` and bright variants `blackBright`, `redBright`, `greenBright`, `yellowBright`, `blueBright`, `magentaBright`, `cyanBright`, `whiteBright`.
```javascript
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
```javascript
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
```javascript
import pc from "picocolors"
let { red, bgWhite } = pc.createColors(options.enableColors)
```
## Replacing `chalk`
1. Replace package name in import:
```diff
- import chalk from 'chalk'
+ import pico from 'picocolors'
```
2. Replace variable:
```diff
- chalk.red(text)
+ pico.red(text)
```
3. Replace chains to nested calls:
```diff
- chalk.red.bold(text)
+ pico.red(pico.bold(text))
```
4. You can use [`colorize-template`](https://github.com/usmanyunusov/colorize-template)
to replace chalk’s tagged template literal.
```diff
+ import { createColorize } from 'colorize-template'
+ let colorize = createColorize(pico)
- chalk.red.bold`full {yellow ${"text"}}`
+ colorize`{red.bold full {yellow ${"text"}}}`
```
|