Amazing CLIfor Terminal
Guide

Development Guide

How to contribute and build the library

Git2Docs Certified

Overview

This page explains how to contribute to and build chalk, the ESM-only Node.js terminal styling library. It covers the repository prerequisites, how to install development dependencies, how to run the test suite and benchmarks, and what to expect from the CI environment. Following these steps ensures your changes are validated against the same Node.js versions the project officially supports.


Prerequisites

Before contributing, make sure you have the following:

  • Node.js ≥ 22 — chalk's package.json sets "node": ">=22". CI tests against Node.js 22 and 26 only; other versions are not tested.
  • npm — used to install dev dependencies and run scripts.
  • An ESM-compatible environment — chalk ships no CommonJS build ("type": "module" in package.json). All source files and test files use import/export.
  • Familiarity with ES modules — import syntax is required throughout; there is no require() path in the development workflow.

Installation
  1. Fork and clone the repository.

    git clone https://github.com/chalk/chalk.git
    cd chalk
    
  2. Install development dependencies.

    npm install
    

    This installs only dev dependencies (TypeScript, xo, c8, execa, and others listed in devDependencies). chalk itself has no runtime dependencies — ansi-styles and supports-color are vendored under source/vendor/ and are not installed from npm.

  3. Verify the setup by running the test suite.

    npm test
    

    A passing run confirms that linting (xo), tests (Node.js built-in test runner under c8 coverage), and TypeScript type-checking all succeed.


Configuration

The development workflow is controlled entirely by the scripts in package.json. There are no external config files to edit before contributing.

npm test

Runs three checks in sequence:

StepToolWhat it checks
LintxoCode style across all non-vendored source files
Test + coveragec8 node --testAll test/[!_]*.js files via the built-in Node.js test runner; vendored files under source/vendor/ are excluded from coverage
Type checktsc --noEmitsource/index.d.ts against @types/node with no emit

xo ignores source/vendor/ entirely (see the xo config array in package.json). Coverage (c8) similarly excludes source/vendor/.

npm run bench

Runs the benchmark suite with node --experimental-bench --bench benchmark.js. Because the bench runner pipes stdout, chalk.level is set to 3 inside benchmark.js to prevent chalk from disabling colors and measuring only the plain passthrough.

Environment variables that affect tests

Several test files (test/force-color.js, test/level.js) spawn child processes with extendEnv: false so that ambient CI variables such as FORCE_COLOR, COLORTERM, and TERM cannot leak into the fixture process. When writing new tests that rely on color-level detection, follow the same pattern.

VariableEffect
FORCE_COLOR=<0-3>Sets the color level exactly (capped at 3)
FORCE_COLOR=true or FORCE_COLOR=Enables color and lets the level be detected from the environment
FORCE_COLOR=0 or FORCE_COLOR=falseDisables color
--no-color flagDisables color
--color flagEnables color
--color=256 flagForces level 2 (256-color)
--color=16m flagForces level 3 (Truecolor)

Usage

Running the full check locally

Before opening a pull request, run the full test command exactly as CI does:

npm test

This lints, tests, and type-checks in one step. Fix any xo lint errors before iterating on test failures.

Running only the Node.js test runner

If you want faster feedback on a specific test file, invoke the test runner directly:

node --test test/chalk.js

Writing tests

All test files live under test/. Files prefixed with _ (e.g. test/_fixture.js, test/_force-color-fixture.js) are fixture scripts spawned by other tests — they are excluded from the test runner glob test/[!_]*.js.

Tests use the built-in node:test module and node:assert/strict. Import chalk from the source directly:

import chalk, { Chalk } from '../source/index.js';

When a test needs to control color-level detection from environment variables or CLI flags, spawn a fixture as a child process with extendEnv: false (using execa's execaNode) rather than mutating chalk.level in-process.

Modifying vendored internals

The files under source/vendor/ are vendored copies of ansi-styles and supports-color. They are imported internally via the package #ansi-styles and #supports-color import-map aliases defined in package.json. Changes to these files are intentionally excluded from linting and coverage. If you need to update them, do so as a deliberate, isolated commit and explain the upstream version being vendored.

Code of Conduct

This project is released with a Contributor Code of Conduct. By participating you agree to abide by its terms (see code-of-conduct.md in the repository root).


Examples

Run the full test suite

npm test

Run the benchmark suite

npm run bench

Manually test color output from a fixture

node test/_fixture.js

This script imports chalk and chalkStderr and prints two styled strings:

import chalk, { chalkStderr } from '../source/index.js';

console.log(`${chalk.hex('#ff6159')('testout')} ${chalkStderr.hex('#ff6159')('testerr')}`);

When run in a TTY with Truecolor support, you will see testout testerr rendered in the specified hex color. When run in a piped environment (no color support detected), it prints:

testout testerr

Test color-level detection with FORCE_COLOR

FORCE_COLOR=3 node test/_force-color-fixture.js

Outputs 3, confirming the color level was set to Truecolor.

FORCE_COLOR=0 node test/_force-color-fixture.js

Outputs 0, confirming color is disabled.

Create an isolated Chalk instance for testing a specific level

import { Chalk } from '../source/index.js';

const instance = new Chalk({ level: 1 });
console.log(instance.red('foo')); // basic 16-color ANSI escape

const noColor = new Chalk({ level: 0 });
console.log(noColor.red('foo')); // 'foo' — no escape codes

Troubleshooting

ERR_REQUIRE_ESM when loading chalk

Symptom: A require('chalk') call throws ERR_REQUIRE_ESM.

Cause: You are running Node.js 22 but on a release earlier than 22.12. On Node.js ≥ 22.12, require() can load ES modules and returns the module namespace (access the default export as .default). Earlier 22.x releases do not support this and throw.

Fix: Upgrade to Node.js ≥ 22.12, or convert your consuming file to ESM (import syntax).


Tests fail with unexpected color-level values

Symptom: Tests in test/force-color.js or test/level.js produce wrong color levels.

Cause: Ambient environment variables (FORCE_COLOR, COLORTERM, TERM, CI, GITHUB_ACTIONS) from the host machine or CI runner are leaking into spawned fixture processes.

Fix: Ensure fixture processes are spawned with extendEnv: false (the existing tests already do this). Do not set FORCE_COLOR globally in your shell when running the test suite.


npm test fails at the lint step

Symptom: xo reports style errors before any test runs.

Cause: Code style violations in files outside source/vendor/.

Fix: Run npx xo --fix to auto-fix correctable issues, then review remaining errors manually. Do not modify source/vendor/ files to satisfy linting — that directory is intentionally excluded from xo.


TypeScript type-check (tsc --noEmit) fails

Symptom: npm test exits at the tsc step with type errors.

Cause: A change to source/index.js or source/index.d.ts introduced a type mismatch, or @types/node was updated with incompatible declarations.

Fix: Review source/index.d.ts — this is the authoritative declaration file defining all public types including ChalkInstance, ColorInfo, and Options. Ensure any new API surface is reflected there. Check that @types/node version in devDependencies is compatible.


Benchmark produces only plain (unstyled) output

Symptom: npm run bench completes but reports suspiciously fast timings; chalk appears to output unstyled strings.

Cause: The benchmark runner pipes stdout, which causes supports-color to detect level 0 (no color support). Without the explicit override, chalk's styling is a no-op.

Fix: This is handled inside benchmark.js by setting chalk.level = 3 before the benchmarks run. If you are writing a new benchmark, include the same override at the top of your file.


Tagged template literals do not interpolate correctly

Symptom: chalk.red\Hello ${name}`producesHello , Sindre` (the interpolated value appears after the closing backtick content, not in-place).

Cause: Core chalk does not support tagged template literals. The chainable builder returns a function that joins its arguments with spaces; using it as a template tag does not perform standard interpolation.

Fix: Use the chalk-template package for tagged template literal support with interpolation.