Development Guide
How to contribute and build the library
Git2Docs CertifiedThis 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.
Before contributing, make sure you have the following:
- Node.js ≥ 22 — chalk's
package.jsonsets"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"inpackage.json). All source files and test files useimport/export. - Familiarity with ES modules —
importsyntax is required throughout; there is norequire()path in the development workflow.
-
Fork and clone the repository.
git clone https://github.com/chalk/chalk.git cd chalk -
Install development dependencies.
npm installThis installs only dev dependencies (TypeScript, xo, c8, execa, and others listed in
devDependencies). chalk itself has no runtime dependencies —ansi-stylesandsupports-colorare vendored undersource/vendor/and are not installed from npm. -
Verify the setup by running the test suite.
npm testA passing run confirms that linting (xo), tests (Node.js built-in test runner under c8 coverage), and TypeScript type-checking all succeed.
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:
| Step | Tool | What it checks |
|---|---|---|
| Lint | xo | Code style across all non-vendored source files |
| Test + coverage | c8 node --test | All test/[!_]*.js files via the built-in Node.js test runner; vendored files under source/vendor/ are excluded from coverage |
| Type check | tsc --noEmit | source/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.
| Variable | Effect |
|---|---|
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=false | Disables color |
--no-color flag | Disables color |
--color flag | Enables color |
--color=256 flag | Forces level 2 (256-color) |
--color=16m flag | Forces level 3 (Truecolor) |
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).
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
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.