---
title: Development Guide
product: amazing-cli
doc_type: guide
version: main
source: git2docs (code-derived, validation-filtered)
canonical: https://git2docs.com/wabam/docs/amazing-cli/chalk/development-guide
---

# Development Guide

_How to contribute and build the library_

## 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.**

   ```sh
   git clone https://github.com/chalk/chalk.git
   cd chalk
   ```

2. **Install development dependencies.**

   ```sh
   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.**

   ```sh
   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:

| 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) |

## Usage

### Running the full check locally

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

```sh
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:

```sh
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:

```js
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

```sh
npm test
```

#### Run the benchmark suite

```sh
npm run bench
```

#### Manually test color output from a fixture

```sh
node test/_fixture.js
```

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

```js
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`

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

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

```sh
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

```js
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}\`` produces `Hello , 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`](https://github.com/chalk/chalk-template) package for tagged template literal support with interpolation.
