{"id":13422,"library":"kolorist","title":"Kolorist: Terminal Colorization Utility","description":"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.","status":"active","version":"1.8.0","language":"javascript","source_language":"en","source_url":"https://github.com/marvinhagemeister/kolorist","tags":["javascript","typescript"],"install":[{"cmd":"npm install kolorist","lang":"bash","label":"npm"},{"cmd":"yarn add kolorist","lang":"bash","label":"yarn"},{"cmd":"pnpm add kolorist","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Kolorist is primarily designed for ESM; CommonJS `require` might lead to issues depending on Node.js version and project configuration.","wrong":"const { red } = require('kolorist')","symbol":"red","correct":"import { red } from 'kolorist'"},{"note":"The `options` object allows for global configuration, such as programmatically enabling or disabling colors via `options.enabled = false`.","symbol":"options","correct":"import { options } from 'kolorist'"},{"note":"Used to remove ANSI escape codes from a string, useful for logging to files or environments where colors are undesirable.","symbol":"stripColors","correct":"import { stripColors } from 'kolorist'"},{"note":"All color functions are named exports; there is no default export for individual colors.","wrong":"import { default as cyan } from 'kolorist'","symbol":"Named color functions (e.g., cyan, green)","correct":"import { cyan, green } from 'kolorist'"}],"quickstart":{"code":"import { red, cyan, green, stripColors, options } from 'kolorist';\n\nconsole.log(red(`Error: something critical failed in ${cyan('my-app.ts')}!`));\nconsole.log(green('Successfully completed operation.'));\n\n// Demonstrate disabling colors programmatically\noptions.enabled = false;\nconst colorlessMessage = red('This message should not be colored.');\nconsole.log(colorlessMessage); // Logs \"This message should not be colored.\"\noptions.enabled = true; // Re-enable for subsequent output\n\n// Demonstrate stripping colors from a string\nconst coloredString = red('This text is red and should be stripped.');\nconsole.log(`Original: ${coloredString}`);\nconsole.log(`Stripped: ${stripColors(coloredString)}`);","lang":"typescript","description":"This quickstart demonstrates basic usage of color functions, programmatic color toggling, and stripping ANSI colors from a string."},"warnings":[{"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.","message":"Kolorist'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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Versions 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.","severity":"breaking","affected_versions":"<1.3.2"},{"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.","message":"Although 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.","severity":"gotcha","affected_versions":">=1.8.0"},{"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`.","message":"Changes 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.","severity":"breaking","affected_versions":">=1.5.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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`.","error":"Error [ERR_UNKNOWN_MODULE_TYPE]: An unknown module type was detected for the entry-point"},{"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.","cause":"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.","error":"TypeError: (0 , _kolorist.red) is not a function"},{"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`).","cause":"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.","error":"ReferenceError: TERM is not defined (or similar runtime error related to `process.env.TERM`)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}