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

# Configuration

_Client initialization, authentication, default options_

## Overview

This page explains how to install Chalk, configure its color level, and initialize instances for use in your Node.js or browser-bundled application. Chalk is an ESM-only library that wraps terminal output strings in ANSI escape sequences, automatically detecting the host terminal's color capability at runtime. Understanding initialization matters because color level affects every styled string your application produces — getting it wrong silently strips all color or applies escape codes a terminal cannot render. The two primary paths covered here are using the pre-configured default export and creating isolated `Chalk` instances with explicit color-level settings via the `Chalk` constructor.

## Prerequisites

Before you begin, ensure your environment meets the following requirements:

- **Node.js ≥ 22** — Chalk's package declares `>=22` and CI tests against Node 22 and 26 only. Earlier versions are not tested.
- **ESM-compatible project** — Chalk is ESM-only. There is no CommonJS build, so your project must use `"type": "module"` in `package.json`, or a bundler configured to consume ES modules.
- **npm, pnpm, or yarn** — any of these package managers can install Chalk.

## Installation

1. Ensure you are running **Node.js ≥ 22**. Chalk is tested on Node 22 and Node 26 in CI.

2. Install Chalk into your project using your preferred package manager:

   **npm**
   ```sh
   npm install chalk
   ```

   **pnpm**
   ```sh
   pnpm add chalk
   ```

   **yarn**
   ```sh
   yarn add chalk
   ```

3. Because Chalk is ESM-only, your project must import it with `import`, not `require`. If your `package.json` does not already declare `"type": "module"`, either add it or use the `.mjs` extension for the files that import Chalk.

   ```json
   {
     "type": "module"
   }
   ```

   > **CommonJS note:** On Node.js ≥ 22.12, `require('chalk')` loads the ES module successfully. Access the default export via `.default` (e.g. `const chalk = require('chalk').default`). On earlier Node 22 releases, `require('chalk')` throws `ERR_REQUIRE_ESM`.

4. Chalk has **no runtime dependencies**. `ansi-styles` and `supports-color` are vendored internally, so no additional packages are installed into your `node_modules`.

## Configuration

### Color level (`level`)

The central configuration knob in Chalk is the **color level**, an integer from `0` to `3` that controls which ANSI escape sequences are emitted.

| Level | Description |
|:---:|:---|
| `0` | All colors disabled — plain strings are returned as-is |
| `1` | Basic 16-color support |
| `2` | 256-color support |
| `3` | Truecolor (16 million colors) support |

Setting any value outside this range — or a non-integer — throws an error.

#### Automatic detection (default behavior)

When you use the default `chalk` export, the level is detected automatically at module load time by inspecting the runtime environment. You do not need to set anything for typical use.

#### Overriding detection with environment variables

You can force a specific level without changing code:

| Variable / Flag | Effect |
|---|---|
| `FORCE_COLOR=0` | Disable all color (level 0) |
| `FORCE_COLOR=1` | Enable basic color (level 1) |
| `FORCE_COLOR=2` | Enable 256-color (level 2) |
| `FORCE_COLOR=3` | Enable Truecolor (level 3) |
| `FORCE_COLOR=true` or `FORCE_COLOR=` (empty) | Enable color at level 1 or above; actual level is still detected from the terminal |
| `--no-color` flag | Disable all color |
| `--color` flag | Enable basic color |
| `--color=256` flag | Enable 256-color mode |
| `--color=16m` flag | Enable Truecolor mode |

Numeric `FORCE_COLOR` sets the level directly and is capped at `3`. The flags `--color=256` and `--color=16m` take precedence over a non-zero numeric `FORCE_COLOR`.

#### Setting `level` on the default instance

You can reassign `chalk.level` at runtime, but this applies **globally** to every consumer of the default export in the same process. Prefer creating an isolated instance instead:

```js
import chalk from 'chalk';

// Global override — affects all code using the default export
chalk.level = 1;
```

#### Creating an isolated instance with `new Chalk({ level })`

The `Chalk` constructor accepts an `Options` object with one field:

- **`level`** (`0 | 1 | 2 | 3 | undefined`) — The color level for this instance. Omit it, or pass `undefined`, to have the level auto-detected from the environment. Throws if the value is not `undefined` and not an integer from 0 to 3.

This is the recommended approach whenever you need per-stream or per-context control, or are writing a reusable module that should not alter global state:

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

const noColorChalk  = new Chalk({ level: 0 }); // always plain text
const basicChalk    = new Chalk({ level: 1 }); // 16-color output
const chalk256      = new Chalk({ level: 2 }); // 256-color output
const trueChalk     = new Chalk({ level: 3 }); // Truecolor output
const autoChalk     = new Chalk();             // level auto-detected
```

#### `chalkStderr`

Chalk exports a second pre-configured instance, `chalkStderr`, whose color level is detected from `stderr` instead of `stdout`. Use it when writing diagnostic output to `process.stderr`:

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

process.stderr.write(chalkStderr.red('Fatal error\n'));
```

#### Browser environments

When Chalk is used in a browser bundle, the `default` condition in the package exports selects a browser-specific color detector that inspects the Chromium brand version instead of terminal flags:

- Chromium brand version > 93 → level 3 (Truecolor)
- Any other Chrome/Chromium user agent → level 1
- No `navigator`, or a non-Chromium browser → level 0

Since Chrome 69, ANSI escape codes are natively supported in the developer console, so level 3 output renders correctly in modern Chromium-based DevTools.

## Usage

### Import the default instance

For most scripts and CLI tools, import the default `chalk` export and start chaining styles immediately. No initialization code is required — the color level is auto-detected.

```js
import chalk from 'chalk';

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

### Chain styles

Styles are chainable properties. Call the last property in the chain as a function, passing one or more strings. Multiple arguments are joined with a space.

```js
import chalk from 'chalk';

console.log(chalk.blue.bgRed.bold('Hello world!'));
console.log(chalk.blue('Hello', 'World!', 'Foo', 'bar'));
```

### Define reusable style themes

Because a chalk chain without a final call returns a function, you can assign partial chains to variables and reuse them:

```js
import chalk from 'chalk';

const error   = chalk.bold.red;
const warning = chalk.hex('#FFA500');

console.log(error('Error!'));
console.log(warning('Warning!'));
```

### Use an isolated instance for reusable modules

If your module is consumed by other packages, never mutate the global `chalk.level`. Create an isolated instance instead:

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

const chalk = new Chalk({ level: 2 }); // 256-color, isolated
console.log(chalk.green('Module output'));
```

### Interpolate values in template literals (standard ES syntax)

Chalk's chainable builder returns a function, so you can use standard ES template literals with `${}` interpolation — just call the chalk style as a function inside the expression:

```js
import chalk from 'chalk';

const cpuUsage = '90%';
console.log(`CPU: ${chalk.red(cpuUsage)}`);
```

> **Important:** Do not use chalk as a tagged template literal (e.g. `chalk.red\`text\``). The core library does not support tagged template literal interpolation. If you need tagged template literal syntax with `${}` interpolation, install the separate [`chalk-template`](https://github.com/chalk/chalk-template) package.

### Write to stderr with `chalkStderr`

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

process.stderr.write(chalkStderr.yellow('Warning: retrying...\n'));
```

### Disable color output programmatically

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

const plainChalk = new Chalk({ level: 0 });
console.log(plainChalk.red('This will have no color'));
```

## Examples

**Basic colored output**

```js
import chalk from 'chalk';

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

---

**Chaining multiple styles**

```js
import chalk from 'chalk';

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

---

**Combining styled and plain strings**

```js
import chalk from 'chalk';

console.log(chalk.blue('Hello') + ' World' + chalk.red('!'));
```

---

**Multiple arguments (space-joined)**

```js
import chalk from 'chalk';

console.log(chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz'));
```

---

**Nested styles**

```js
import chalk from 'chalk';

console.log(chalk.red('Hello', chalk.underline.bgBlue('world') + '!'));
```

---

**Reusable theme definitions**

```js
import chalk from 'chalk';

const error   = chalk.bold.red;
const warning = chalk.hex('#FFA500');

console.log(error('Error!'));
console.log(warning('Warning!'));
```

---

**Using `console.log` string substitution**

```js
import chalk from 'chalk';

const name = 'Sindre';
console.log(chalk.green('Hello %s'), name);
//=> 'Hello Sindre'
```

---

**Truecolor with RGB and hex**

```js
import chalk from 'chalk';

console.log(chalk.rgb(123, 45, 67).underline('Underlined reddish color'));
console.log(chalk.hex('#DEADED').bold('Bold gray!'));
```

---

**Isolated instance with explicit color level**

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

const customChalk = new Chalk({ level: 0 });
console.log(customChalk.red('This will not be red'));
```

---

**Validating style names with exported name arrays**

```js
import { modifierNames, foregroundColorNames } from 'chalk';

console.log(modifierNames.includes('bold'));
//=> true

console.log(foregroundColorNames.includes('pink'));
//=> false
```

---

**Underline color (requires an underline modifier)**

```js
import chalk from 'chalk';

console.log(chalk.underlineHex('#DEADED').underlineCurly('Hello, world!'));
```

---

**Background color methods**

```js
import chalk from 'chalk';

console.log(chalk.bgHex('#DEADED').underline('Hello, world!'));
console.log(chalk.bgRgb(15, 100, 204).inverse('Hello!'));
```

## Troubleshooting

### `ERR_REQUIRE_ESM` when calling `require('chalk')`

**Symptom:** Your CommonJS file throws `Error [ERR_REQUIRE_ESM]: require() of ES Module … not supported`.

**Cause:** You are running Node.js 22 but on a release earlier than 22.12. Those releases cannot `require()` an ES module.

**Fix:** Upgrade to Node.js ≥ 22.12, or convert the importing file to ESM (`import chalk from 'chalk'`). On Node.js ≥ 22.12, `require('chalk')` works and returns the ES module namespace; access the default export with `.default`:
```js
const chalk = require('chalk').default;
```

---

### No color appears in output

**Symptom:** Terminal output contains no ANSI color — strings appear plain.

**Cause (1):** The detected color level is `0`. This happens when stdout is not a TTY (e.g. the output is piped), when `FORCE_COLOR=0` is set, or when `--no-color` is passed.

**Fix:** Force a level with an environment variable:
```sh
FORCE_COLOR=1 node your-script.js
# or
FORCE_COLOR=3 node your-script.js   # Truecolor
```
Or use the `--color` flag:
```sh
node your-script.js --color
```

**Cause (2):** A `Chalk` instance was constructed with `{ level: 0 }`.

**Fix:** Remove the explicit level or set it to the appropriate value:
```js
import { Chalk } from 'chalk';
const chalk = new Chalk({ level: 3 });
```

---

### Tagged template literal produces garbled or missing interpolations

**Symptom:** `chalk.green\`Hello ${name}\`` prints `Hello , Sindre` or similar — the interpolated value appears in the wrong position, or the template does not behave like a standard template literal.

**Cause:** Chalk's chainable builder does not implement tagged template literal semantics. Used as a tag, it receives the raw string array and joins it, so variable interpolation does not work as expected.

**Fix:** Either call chalk as a regular function with standard ES template literals:
```js
console.log(chalk.green(`Hello ${name}`));
```
Or install [`chalk-template`](https://github.com/chalk/chalk-template) for proper tagged template literal support with interpolation.

---

### `level` setter throws a `RangeError`-style error

**Symptom:** Assigning `chalk.level = someValue` or passing `{ level: someValue }` to `new Chalk()` throws `Error: The \`level\` should be an integer from 0 to 3`.

**Cause:** The value is not a safe integer in the range 0–3. Common mistakes include passing `true`, `null`, `undefined` to the constructor's `level` field (note: passing `undefined` or omitting `level` is valid and triggers auto-detection), or a floating-point number.

**Fix:** Use only integer values `0`, `1`, `2`, or `3`. Omit `level` entirely (or pass `undefined`) to let Chalk detect the level automatically:
```js
import { Chalk } from 'chalk';

const chalk = new Chalk();             // auto-detect
const chalk2 = new Chalk({ level: 2 }); // explicit 256-color
```

---

### Colors render differently between `stdout` and `stderr`

**Symptom:** Styled strings sent to `process.stderr` appear plain or at a lower color level than those sent to `process.stdout`.

**Cause:** The default `chalk` export detects color support for `stdout`. If `stderr` is attached to a different TTY or is piped, its detected level may differ.

**Fix:** Use the `chalkStderr` export, which is a separate Chalk instance whose color level is independently detected for `stderr`:
```js
import { chalkStderr } from 'chalk';

process.stderr.write(chalkStderr.red('Error message\n'));
```
