chalk の使い方 — ターミナル文字列を自在にスタイリングするnpmパッケージ

一言でいうと

chalk は、Node.js のターミナル出力に色やスタイル（太字・下線など）を簡単に付与するためのライブラリです。ANSI エスケープコードを意識することなく、直感的なチェーンAPIで美しいCLI出力を実現できます。

---

どんな時に使う？

1. CLIツールの開発 — エラーは赤、成功は緑、警告は黄色など、ログメッセージを視覚的に区別したいとき
2. 開発サーバーやビルドツールのログ整形 — Webpack・Vite のようなツールが内部で使っているような、構造化されたカラフルなログ出力を自作したいとき
3. テスト結果やデバッグ情報の強調表示 — 大量のターミナル出力の中から重要な情報を目立たせたいとき

---

インストール

注意: chalk v5 は ESM (ES Modules) 専用 です。CommonJS (require) で使いたい場合は v4 系を使用してください。

# npm
npm install chalk

# yarn
yarn add chalk

# pnpm
pnpm add chalk

CommonJS が必要な場合：

npm install chalk@4

---

基本的な使い方

import chalk from 'chalk';

// 基本的な色付け
console.log(chalk.blue('Hello world!'));

// スタイルのチェーン
console.log(chalk.bold.red('エラーが発生しました'));

// 背景色の指定
console.log(chalk.bgGreen.black(' SUCCESS ') + ' ビルドが完了しました');

// テンプレートリテラルとの組み合わせ
const user = 'admin';
console.log(`${chalk.green('✔')} ユーザー ${chalk.bold(user)} がログインしました`);

// ネストも可能
console.log(chalk.red('エラー:', chalk.underline.bgRed('ファイルが見つかりません')));

出力イメージ:

Hello world!          ← 青色
エラーが発生しました    ← 赤色・太字
 SUCCESS  ビルドが完了しました  ← 緑背景に黒文字
✔ ユーザー admin がログインしました  ← 緑チェック、太字ユーザー名

---

よく使うAPI

1. 文字色（Foreground Colors）

import chalk from 'chalk';

console.log(chalk.black('黒'));
console.log(chalk.red('赤'));
console.log(chalk.green('緑'));
console.log(chalk.yellow('黄'));
console.log(chalk.blue('青'));
console.log(chalk.magenta('マゼンタ'));
console.log(chalk.cyan('シアン'));
console.log(chalk.white('白'));
console.log(chalk.gray('グレー')); // blackBright のエイリアス

// 明るいバリエーション
console.log(chalk.redBright('明るい赤'));
console.log(chalk.greenBright('明るい緑'));

2. 背景色（Background Colors）

import chalk from 'chalk';

console.log(chalk.bgRed('赤背景'));
console.log(chalk.bgGreen.white('緑背景に白文字'));
console.log(chalk.bgYellow.black('黄背景に黒文字'));
console.log(chalk.bgBlueBright('明るい青背景'));

3. テキスト装飾（Modifiers）

import chalk from 'chalk';

console.log(chalk.bold('太字'));
console.log(chalk.dim('薄い文字'));
console.log(chalk.italic('イタリック'));       // ターミナルによっては非対応
console.log(chalk.underline('下線'));
console.log(chalk.strikethrough('取り消し線')); // ターミナルによっては非対応
console.log(chalk.inverse('反転'));

// 組み合わせ
console.log(chalk.bold.underline.red('太字＋下線＋赤'));

4. RGB / HEX / 256色 カスタムカラー

import chalk from 'chalk';

// HEX カラー
console.log(chalk.hex('#FF8800')('オレンジ色のテキスト'));

// RGB 指定
console.log(chalk.rgb(123, 45, 67)('カスタムRGBカラー'));

// 背景にも使える
console.log(chalk.bgHex('#3498db').white('カスタム背景色'));

// ANSI 256色
console.log(chalk.ansi256(202)('ANSI 256色'));

5. chalk.level によるカラーサポート制御

import chalk from 'chalk';

// 現在のカラーサポートレベルを確認
console.log(chalk.level);
// 0 = 色なし
// 1 = 基本16色
// 2 = ANSI 256色
// 3 = Truecolor (1600万色)

// 色を強制的に無効化（テスト時やファイル出力時に便利）
const ctx = new chalk.Instance({ level: 0 });
console.log(ctx.red('この文字には色が付きません'));

// Truecolor を強制有効化
const trueColor = new chalk.Instance({ level: 3 });
console.log(trueColor.hex('#DEADED')('Truecolor テキスト'));

---

類似パッケージとの比較

選定の目安：

• フルカラー・高機能が必要 → chalk
• バンドルサイズ最小・基本色だけでOK → picocolors
• CJS で chalk ライクなAPIが欲しい → kleur / ansi-colors

---

注意点・Tips

⚠️ v5 は ESM 専用

chalk v5 は "type": "module" が設定されたプロジェクト、または .mjs ファイルでのみ動作します。require('chalk') はエラーになります。

// package.json に以下が必要
{
  "type": "module"
}

既存の CommonJS プロジェクトで使う場合は chalk@4 を明示的にインストールしてください。

⚠️ パイプ・リダイレクト時の自動検出

chalk はターミナルの色サポートを自動検出します。node script.js | cat や node script.js > output.txt のようにパイプ/リダイレクトすると、自動的に色が無効化されます。強制的に色を有効にしたい場合は環境変数を使います。

FORCE_COLOR=1 node script.js | cat

💡 再利用可能なスタイルを変数に格納

import chalk from 'chalk';

// よく使うスタイルを定義しておく
const error = chalk.bold.red;
const warning = chalk.hex('#FFA500');
const success = chalk.green;
const info = chalk.blue;
const label = chalk.bgCyan.black;

console.log(error('✖ ビルドに失敗しました'));
console.log(warning('⚠ 非推奨のAPIが使われています'));
console.log(success('✔ テストがすべてパスしました'));
console.log(info('ℹ 3つのファイルが変更されました'));
console.log(label(' INFO ') + ' サーバーが起動しました');

💡 複数引数の渡し方

import chalk from 'chalk';

// 複数の引数はスペース区切りで結合される
console.log(chalk.blue('ファイル数:', 42, '件'));
// → "ファイル数: 42 件" が青色で出力

💡 CI環境での色制御

GitHub Actions や Jenkins などの CI 環境では、色サポートの検出結果が環境によって異なります。確実に色を出したい場合は FORCE_COLOR=1、確実に無効にしたい場合は NO_COLOR=1 を設定してください。

# GitHub Actions の例
- run: node build.js
  env:
    FORCE_COLOR: 1

---

まとめ

chalk は Node.js のターミナル出力スタイリングにおけるデファクトスタンダードです。チェーン可能な直感的API、RGB/HEX によるフルカラーサポート、自動的なターミナル検出など、CLIツール開発に必要な機能が揃っています。v5 で ESM 専用になった点だけ注意すれば、最も安心して採用できるカラーリングライブラリと言えるでしょう。