Опция color

Назначение опции

Опция color в Esbuild управляет использованием цветного вывода в терминале при сборке. Она влияет на форматирование логов, предупреждений и ошибок, делая их более читаемыми за счёт цветового выделения ключевых элементов.

Основная задача механизма — улучшение визуального восприятия диагностической информации при работе сборщика в CLI и через JavaScript API.

Режимы работы

Опция поддерживает три основных режима:

  • true — принудительное включение цветного вывода
  • false — полный запрет цветового вывода
  • "auto" — автоматическое определение поддержки терминала

Поведение в режиме auto

Режим "auto" является стандартным поведением. Esbuild анализирует окружение выполнения и принимает решение о включении цветов на основе нескольких факторов:

  • наличие TTY (интерактивного терминала)
  • переменные окружения (NO_COLOR, FORCE_COLOR)
  • возможности терминала по отображению ANSI-цветов

Если окружение не поддерживает цветной вывод, форматирование упрощается до монохромного текста.

Использование в CLI

В командной строке опция задаётся через флаг:

esbuild input.js --bundle --color=true

или

esbuild input.js --bundle --color=false

или

esbuild input.js --bundle --color=auto

При отсутствии параметра используется режим auto.

Использование в JavaScript API

В API Esbuild опция передаётся через объект конфигурации build или context:

import { build } from 'esbuild';

build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  color: true
});

Пример с отключением цветового вывода:

import { build } from 'esbuild';

build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  color: false
});

Автоматический режим:

build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  color: 'auto'
});

Влияние на вывод логов

Цветовое оформление затрагивает следующие элементы вывода:

  • ошибки компиляции
  • предупреждения
  • информационные сообщения
  • пути файлов
  • строки и колонки в стектрейсах

Типичная раскраска включает:

  • красный цвет для ошибок
  • жёлтый для предупреждений
  • серый или приглушённый цвет для дополнительной информации
  • выделение путей файлов и номеров строк

Совместимость с окружениями

Поведение опции зависит от среды выполнения:

Поддержка терминалов:

  • xterm-совместимые терминалы
  • современные терминалы Windows Terminal
  • CI-среды (с ограничениями)

CI-среды: Во многих CI по умолчанию цвет отключается, если не задано принудительное включение через FORCE_COLOR.

Переменные окружения

На работу color влияют стандартные переменные окружения:

  • NO_COLOR — полностью отключает цветовой вывод независимо от настройки
  • FORCE_COLOR — принудительно включает цветовой вывод даже при auto

Эти переменные имеют приоритет над частью внутренних автоматических проверок.

Поведение при ошибках и предупреждениях

При включённом цвете сообщения компиляции становятся структурированными:

  • заголовок ошибки выделяется ярким цветом
  • код ошибки может отображаться с подсветкой
  • строка контекста подсвечивается частично
  • указатель позиции (caret) окрашивается для акцента

При отключении цвета вывод остаётся функциональным, но теряет визуальную структуру.

Особенности реализации

Механизм цветового вывода в Esbuild оптимизирован для минимального влияния на производительность:

  • генерация ANSI-escape последовательностей происходит на этапе форматирования логов
  • не влияет на процесс бандлинга
  • не изменяет AST или результат сборки
  • применяется только к stdout/stderr

Взаимодействие с другими опциями

Опция color часто используется совместно с:

  • logLevel — управляет уровнем детализации логов
  • logLimit — ограничивает количество сообщений
  • silent — полностью отключает вывод (в этом случае color не применяется)
  • metafile — структурированные данные, не зависящие от цветового оформления

Типичные сценарии использования

Разработка: Обычно используется режим auto или true для улучшения читаемости ошибок в терминале.

CI/CD: Часто применяется false или управление через NO_COLOR для чистых логов.

Логирование в файлы: Цвет обычно отключается для избежания ANSI-кодов в текстовых файлах.

Особенности поведения в разных версиях терминала

В некоторых терминалах поддержка цвета ограничена:

  • 16 цветов — базовая поддержка ANSI
  • 256 цветов — расширенная палитра
  • truecolor — полная RGB-поддержка

Esbuild не настраивает палитру вручную, а полагается на возможности окружения, используя стандартные ANSI-последовательности.

Оглавление