---
title: Intended Audience
product: amazing-cli
doc_type: concept
version: main
source: git2docs (code-derived, validation-filtered)
canonical: https://git2docs.com/wabam/docs/amazing-cli/chalk/intended-audience
---

# Intended Audience

_Who should use this library_

## Overview

This page describes who Chalk is designed for and what kinds of problems it solves best. Understanding the intended audience helps you decide whether Chalk is the right tool for your project and how to get the most out of its API.

## Content

## Who Chalk is for

Chalk is built for **intermediate Node.js developers** who are creating CLI tools, build scripts, development servers, test runners, or any other program that writes styled output to a terminal. If you are manually constructing ANSI escape sequences, concatenating color codes, or working around environment-specific color support, Chalk is designed to remove exactly that complexity.

### Primary use cases

**CLI tool authors** are the core audience. When you ship a command-line tool, you want errors to appear in red, warnings in yellow, and success messages in green — without requiring your users to have a particular terminal or OS. Chalk's automatic color-level detection handles this: it reads TTY properties, environment variables (`FORCE_COLOR`, `COLORTERM`, `TERM`), and CI-related flags at startup and selects the appropriate ANSI encoding level (0–3) so your styled strings degrade gracefully in environments that do not support color.

**Node.js script authors** who produce diagnostic or progress output also benefit directly. Because Chalk ships with no runtime dependencies — `ansi-styles` and `supports-color` are vendored internally — adding it to a project does not grow your dependency graph.

**Browser bundle authors** targeting Chromium-based developer-console output are supported through a separate color-detection entry point that inspects the Chromium brand version instead of terminal flags. Chromium brand version > 93 receives level 3 (Truecolor); any other Chrome or Chromium user agent receives level 1; non-Chromium browsers or environments without `navigator` receive level 0.

### What Chalk assumes about you

- You are writing **ESM** (`import`/`export`). Chalk is an ESM-only package (`"type": "module"` in its `package.json`). On Node.js ≥ 22.12 you can `require('chalk')` and receive the module namespace — access the default export via `.default` — but Node.js < 22.12 throws `ERR_REQUIRE_ESM`.
- You are running **Node.js ≥ 22**. That is the only engine range declared in `package.json` and the only one tested in CI (Node 22 and Node 26).
- You are comfortable calling functions and chaining properties on a JavaScript object. Chalk's entire API is a fluent, chainable style builder; each style property or color method on a `Chalk` instance returns a new, cached builder function — not `this` — so chains like `chalk.bold.red('Error!')` produce a fresh builder at every step.

### What Chalk does not assume

Chalk does not assume a specific terminal emulator, operating system, or deployment environment. Color level detection is automatic. If you need deterministic output — for example, in a test suite or in a context where color must be forced off — you can override detection by setting `FORCE_COLOR=0` in the environment or by constructing an isolated instance:

```js
import { Chalk } from 'chalk';

const noColor = new Chalk({ level: 0 });
```

The `Chalk` constructor accepts an integer level from 0 to 3. Passing any other value throws an `Error` with the message `"The \`level\` should be an integer from 0 to 3"`.

### Who Chalk is not for

- **Raw CommonJS projects on Node.js < 22.12.** Those runtimes cannot load the ESM package without the experimental loader flag.
- **Developers who need tagged template literal interpolation built in.** Core Chalk does not support the `chalk.red\`text ${val}\`` pattern correctly — the raw string array is coerced and interpolated values are misplaced in the output. For tagged template literal support, use the companion [`chalk-template`](https://github.com/chalk/chalk-template) package instead.
- **Projects that need the smallest possible bundle.** Chalk trades minimal size for a richer API, broad color-model support, and long-term maintenance. If absolute package size is your top priority, the README suggests [`yoctocolors`](https://github.com/sindresorhus/yoctocolors) as an alternative.

## Examples

### Basic use — confirming the library loads and produces styled output

```js
import chalk from 'chalk';

console.log(chalk.blue('Hello world!'));
```

### Checking whether the runtime is a supported audience

If you need to detect color capability before applying styles — for example, to decide whether to enable chalk at all — inspect the `supportsColor` export. Guard with a truthy check before reading `.level`, since the value is `false` when color is not detected.

```js
import { supportsColor } from 'chalk';

if (supportsColor) {
  console.log('Color level:', supportsColor.level); // 1, 2, or 3
} else {
  console.log('Color not supported in this environment.');
}
```

### Creating an isolated instance for a specific context

If you are writing a reusable module and do not want to affect the global chalk state, construct your own `Chalk` instance. This is especially useful when targeting `stderr` or a non-TTY stream where you want to force color off.

```js
import { Chalk } from 'chalk';

const stderrChalk = new Chalk({ level: 1 }); // Basic 16-color output
console.error(stderrChalk.red('Something went wrong'));
```

### Forcing color level via environment variable (operational context)

In CI environments that do not expose a TTY, you can force chalk to emit color by setting `FORCE_COLOR` before invoking your script. A numeric value sets the level directly (capped at 3); `FORCE_COLOR=true` enables color at level 1 or above and lets detection determine the exact level.

```sh
FORCE_COLOR=3 node my-cli.js
```

Note: `FORCE_COLOR` takes precedence over `--no-color`. If both are present, `FORCE_COLOR=1` wins and chalk emits at level 1.

## Related concepts

- **Install and import** — step-by-step guide to adding Chalk to your project and writing your first styled line.
- **Apply chained styles** — how the chainable builder API works, including style ordering, conflict resolution, and multiple-argument joining.
- **Color level detection** — how `#supports-color` inspects the runtime environment and what `FORCE_COLOR`, `--color`, and `--no-color` flags do.
- **Chalk class (`new Chalk({ level })`)** — creating isolated instances for per-stream or per-context styling control.
- **chalk-template** — the companion package that adds correct tagged template literal interpolation to Chalk's style builder.
