kolorist

library1.8.0jsnpmunverified

Kolorist is a minimal utility library for Node.js environments, designed to apply ANSI escape codes to strings for colored console output. The current stable version, 1.8.0, includes support for 24-bit TrueColor detection, which automatically falls back to Ansi 256 for terminals that lack full TrueColor support, such as the built-in macOS Terminal.app. The library maintains an active release cadence, focusing on minor enhancements and bug fixes like improved handling of `NO_COLOR` and `FORCE_COLOR` environment variables and better module resolution compatibility. Its key differentiators include a tiny footprint, direct focus on standard I/O coloring without unnecessary abstractions, and robust detection of terminal capabilities to ensure appropriate color rendering or disablement. Kolorist ships with TypeScript types, making it well-suited for modern JavaScript and TypeScript projects.

serialization

npm install kolorist

github ↗package ↗

INSTALL

IMPORT

SIG · KOLORIST

kolorist

serializationjavascriptv1.8.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

red

✓ import { red } from 'kolorist'

✗ const { red } = require('kolorist')

Kolorist is primarily designed for ESM; CommonJS `require` might lead to issues depending on Node.js version and project configuration.

options

✓ import { options } from 'kolorist'

The `options` object allows for global configuration, such as programmatically enabling or disabling colors via `options.enabled = false`.

stripColors

✓ import { stripColors } from 'kolorist'

Used to remove ANSI escape codes from a string, useful for logging to files or environments where colors are undesirable.

Named color functions (e.g., cyan, green)

✓ import { cyan, green } from 'kolorist'

✗ import { default as cyan } from 'kolorist'

All color functions are named exports; there is no default export for individual colors.

This quickstart demonstrates basic usage of color functions, programmatic color toggling, and stripping ANSI colors from a string.

import { red, cyan, green, stripColors, options } from 'kolorist'; console.log(red(`Error: something critical failed in ${cyan('my-app.ts')}!`)); console.log(green('Successfully completed operation.')); // Demonstrate disabling colors programmatically options.enabled = false; const colorlessMessage = red('This message should not be colored.'); console.log(colorlessMessage); // Logs "This message should not be colored." options.enabled = true; // Re-enable for subsequent output // Demonstrate stripping colors from a string const coloredString = red('This text is red and should be stripped.'); console.log(`Original: ${coloredString}`); console.log(`Stripped: ${stripColors(coloredString)}`);

Debug

Known issues

gotchaKolorist's color output is influenced by environment variables like `NO_COLOR`, `FORCE_COLOR=0,1,2,3`, and `TERM=dumb`. These variables can override programmatic settings (`options.enabled`) and terminal capability detection, leading to unexpected color behavior if not accounted for.

fix

Be aware of the `NO_COLOR` and `FORCE_COLOR` environment variables in CI/production environments. Use `FORCE_COLOR=0` to explicitly disable colors or `FORCE_COLOR=1` to enable them if `TERM=dumb` is set.

affects: >=1.0.0

breakingVersions prior to `1.3.2` might not be compatible with Node.js 12 due to insufficient down-transpilation (e.g., optional chaining). Ensure your Node.js environment meets the expected runtime target.

fix

Upgrade to Kolorist `1.3.2` or higher to ensure compatibility with Node.js 12+, or ensure your project's build process handles appropriate down-transpilation.

affects: <1.3.2

gotchaAlthough Kolorist `v1.8.0` supports TrueColor (24-bit color), it automatically converts TrueColor values to Ansi 256 for terminals that don't support it (e.g., macOS Terminal.app). This means colors might appear slightly different or less vibrant in some environments without explicit TrueColor support.

fix

Test your application's output in various terminal emulators to understand how colors are rendered. If precise TrueColor is critical, verify terminal capabilities or specify Ansi 256 colors directly.

affects: >=1.8.0

breakingChanges to the `exports` field in `package.json` in versions `1.5.1` and `1.6.0` aimed to improve module resolution, particularly for `nodenext` module resolution. However, this might cause issues with older bundlers or Node.js versions that don't fully support the `exports` field specification, leading to module not found errors.

fix

Ensure you are using a modern Node.js version (12.20.0+, 14.13.0+, or 16.0.0+ for full `exports` field support) and up-to-date bundlers (e.g., Webpack 5, Rollup 3, esbuild) that correctly resolve the `exports` field in `package.json`.

affects: >=1.5.1

Errors

Common errors & fixes

Error [ERR_UNKNOWN_MODULE_TYPE]: An unknown module type was detected for the entry-point

This typically occurs when mixing CommonJS `require()` syntax with an ESM-only package or when Node.js's module resolution fails to correctly interpret the `type` or `exports` field in `package.json`.

fix

Refactor your imports to use ESM `import` statements (e.g., `import { red } from 'kolorist'`). Ensure your `package.json` specifies `"type": "module"` if using ESM, or configure your bundler to handle ESM dependencies appropriately.

TypeError: (0 , _kolorist.red) is not a function

This error often indicates a failed or incorrect import. It suggests that the `red` function was not successfully imported as a named export, possibly due to a CommonJS `require` trying to access an ESM named export.

fix

Verify that you are using correct ESM named import syntax: `import { red } from 'kolorist';`. Do not attempt to `require` named exports directly from an ESM-first package.

ReferenceError: TERM is not defined (or similar runtime error related to `process.env.TERM`)

Older versions of Kolorist (`<1.3.1`) had a runtime error if the `TERM` environment variable was not defined, as they directly accessed `process.env.TERM` without a null check.

fix

Upgrade to Kolorist `1.3.1` or newer, which includes a fix for this issue. If upgrading is not immediately possible, ensure `process.env.TERM` is always defined in your execution environment (e.g., `TERM=xterm node my-script.js`).

Upgrade

Version history

1.8.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/marvinhagemeister/kolorist ↗

packagehttps://www.npmjs.com/package/kolorist ↗