Biome: форматирование и проверка кода — мастерская и 8 практических тем

Biome на практике: форматирование, диагностика, safe/unsafe fixes, imports и CI. Восемь тем, двадцать записей CLI, мастерская и исходники для Windows/Linux.

Biome: меньше ручной рутины при работе с кодом

В одном pull request меняется логика формы, в другом — десятки отступов, кавычек и переносов. Разработчик тратит время на замечания, которые могла бы одинаково применять машина. При этом рядом остаётся более важная ошибка: присваивание в условии, забытая подпись поля или сравнение значений разных типов. Biome помогает разделить эти задачи и сделать проверку кода привычной частью работы.

В этой статье мы разберём formatter, linter и assist на собственных небольших примерах. Вы увидите, что действительно меняется в файле, какое правило выдаёт сообщение и почему некоторые исправления нельзя применять автоматически без разбора. Для этого подготовлены восемь практических тем, двадцать записей настоящего CLI и мастерская сравнения до и после.

Из статьи можно забрать готовый проект, lock-файл, конфигурацию, тесты, настройки редактора и пример CI. На странице получится переключать сценарии, читать диагностику, скачивать исправленный файл и собирать свой biome.json. Основная цель — понятный рабочий процесс: увидеть проблему, оценить изменение и закрепить проверку одинаковой командой на Windows и Linux.

Где это полезно: интерфейс, Node.js и общий репозиторий

Первый сценарий — разработка интерфейса. Формы и компоненты регулярно меняются, а мелкие несогласованности затрудняют чтение diff. Автоматическое форматирование приводит код к одному виду, а правила для JSX помогают заметить часть ошибок разметки ещё до ручного просмотра. Разработчик получает обратную связь рядом с изменяемым файлом, пока причина проблемы ещё понятна.

Второй сценарий — Node.js-сервис. Подозрительное условие в обработчике API может быть важнее неровного отступа. Статическая проверка находит определённые шаблоны ошибок, а одинаковая конфигурация не даёт локальной среде незаметно расходиться с CI. Это полезно и для маленького самостоятельного проекта, и для нескольких разработчиков, работающих над общим кодом.

Третий сценарий — поддержка большого репозитория. Здесь важно не просто включить инструмент, а определить область проверки: собственные исходники, тесты, сгенерированные файлы и сторонние библиотеки требуют разного обращения. Biome можно вводить постепенно, с небольшого каталога и понятных правил. Массовое переписывание всех файлов первым коммитом часто усложняет ревью сильнее, чем помогает.

Formatter, linter и assist: три разные обязанности

Formatter отвечает за внешний вид: отступы, кавычки, переносы и другие правила печати синтаксического дерева. Он не должен угадывать, какую бизнес-операцию вы хотели написать. Если выражение синтаксически сломано, красивое расположение символов не превращает его в корректную программу. В мастерской для этого есть отдельный отрицательный опыт.

Linter ищет определённые проблемы и подозрительные конструкции. Диагностика имеет категорию, серьёзность, место и объяснение. Некоторые правила предлагают исправление, другие требуют решения автора. Даже большое число включённых правил не доказывает правильность расчёта скидки, права доступа или полноту обработки внешнего API.

Assist выполняет действия по организации кода, например упорядочивание imports. Это отдельная задача, которую не стоит смешивать с удалением неиспользуемой зависимости. В проекте команды подобраны так, чтобы эффект каждого инструмента был виден отдельно. Общий check удобен в повседневной работе, но понимание отдельных слоёв помогает объяснить, почему появился конкретный diff.

npx --no-install biome format example
npx --no-install biome lint example
npx --no-install biome check example
npx --no-install biome ci example

Версия, установка и воспроизводимость

Для материала зафиксирован Biome 2.6.7. Во время подготовки плана была доступна 2.6.6, поэтому перед реализацией версия проверена заново. В архиве есть package-lock.json, а установка выполняется через npm ci. Это важно: команда, которая сегодня скачала новую версию автоматически, может дать другой набор сообщений, чем запись из статьи.

Сам пакет Biome поставляет нативный исполняемый файл для платформы. У нашего учебного проекта Node 24 LTS используется для запуска тестов, подготовки записей и локального сервера мастерской. Минимальное требование npm-пакета Biome ниже, но оно не означает, что нужно выбирать старую неподдерживаемую среду для нового проекта.

Точную версию проверяйте локальной командой с –no-install: она использует уже установленную зависимость и не должна неожиданно скачивать другой CLI. На другой операционной системе выполните чистый npm ci, а не переносите node_modules с рабочего компьютера. Общий порядок установки описан в официальном quick start.

npm install --save-dev --save-exact @biomejs/biome@2.6.7
npx --no-install biome --version

# При получении готового проекта с package-lock.json:
npm ci

Мини-мастерская: сравните код и результат команды

Выберите задачу и вариант опыта, затем нажмите «Показать результат CLI». Рядом появятся исходник до команды, файл после неё, код выхода и количество оставшихся ошибок. Если исправление не произошло, мастерская не придумывает красивую версию: вы увидите тот же файл и настоящие сообщения инструмента.

Для длинной строки есть переключатель переноса. В опыте с несколькими файлами можно выбрать нужный файл, включая намеренно сломанный generated. Отдельно открывается построчный diff. JSON опыта содержит полную запись, а кнопка скачивания файла позволяет забрать именно содержимое после команды. «Сбросить» возвращает выбранный вариант в исходное состояние просмотра.

Механизм обозначен явно: это replay настоящих запусков зафиксированного Biome CLI, а не выполнение Biome внутри страницы. Произвольный введённый посетителем код здесь не анализируется. Для своих файлов нужен локальный проект или официальный Playground. Ниже в мастерской есть отдельный конструктор конфигурации: он создаёт biome.json, не изменяя сохранённые примеры и не выдавая себя за formatter.

Конфигурация проекта: начать с небольшой области

Конфигурация должна лежать рядом с кодом и быть частью репозитория. Тогда редактор, локальная команда и CI смогут применять одинаковые настройки. В нашем основном biome.json проверяется только папка example: специально сломанные учебные сценарии создаются в отдельных временных каталогах и не мешают обычной команде quality.

В версии 2.6.7 используем linter.rules.preset: "recommended". Старое поле recommended:true пока принимается, но фактический CLI уже сообщает о его устаревании. Поэтому пример не копирует конфигурацию ранних версий вслепую. Схема в $schema помогает редактору подсказать допустимые параметры и обнаружить опечатку.

Сначала выберите минимальный полезный набор и конкретный каталог. Затем проверьте результат на нескольких настоящих файлах. Не стоит включать все правила только ради максимального числа галочек: у команды должны быть понятные причины и способ разбирать исключения. Возможности и приоритеты параметров приведены в справочнике конфигурации.

{
  "$schema": "https://biomejs.dev/schemas/2.6.7/schema.json",
  "files": { "includes": ["src/**", "!src/generated"] },
  "formatter": { "enabled": true, "indentStyle": "space", "indentWidth": 2 },
  "linter": { "enabled": true, "rules": { "preset": "recommended" } },
  "assist": { "enabled": true, "actions": { "source": { "organizeImports": "on" } } }
}

Опыт 1. Форматирование JavaScript и TypeScript

Первый пример специально записан тесно: функция расчёта строк счёта, объект результата и несколько выражений находятся почти на одной строке. Formatter разносит структуру так, чтобы её легче было читать и сравнивать. Это полезно после быстрого прототипа, при работе нескольких авторов и перед отправкой изменения на ревью.

Вариант TypeScript добавляет тип позиции и меняет длину строки. Видно, какие переносы связаны с настройкой печати, а какие — со структурой программы. Изменение кавычек и отступов само по себе не проверяет правильность формулы. Если количество или цена вычислены неверно, аккуратный результат останется неверным.

Запускайте formatter сначала в режиме проверки, затем разрешайте запись в выбранной области. В рабочем репозитории полезно отделять чистое форматирование от функциональных изменений: так reviewer видит, что относится к поведению, а что к стилю. В нашем опыте до и после сохранены реальные файлы, поэтому можно открыть diff и убедиться, какие символы поменял CLI.

// До:
export function invoice(items){return items.map(item=>({name:item.name,amount:item.price*item.quantity,currency:"RUB"}))}

// Команда из корня своего проекта:
// npx --no-install biome format --write src/invoice.js

Ошибка parse: почему форматтер не должен угадывать код

Во втором отрицательном варианте у объявления переменной отсутствует выражение после знака равенства. Инструмент сообщает о синтаксической проблеме и не записывает придуманное значение. Это важная граница автоматизации: ни ноль, ни пустая строка, ни вызов другой функции не могут быть выбраны без понимания задачи.

В мастерской исходный файл при такой ошибке остаётся прежним. Код выхода ненулевой, а диагностика указывает место. Если вы видите в редакторе несколько сообщений после одной незакрытой скобки, начните с первой синтаксической ошибки: дальнейшие жалобы могут быть следствием нарушенной структуры, а не независимыми дефектами.

Для CI это обычный отказ проверки, который автор должен исправить в исходниках. Не добавляйте подавление parse только ради зелёного результата. В проекте специально проверяется, что отрицательная фикстура не изменилась после запуска format –write. Наличие флага записи не является разрешением инструменту выдумывать бизнес-логику вместо разработчика.

export const total = ;
// Здесь нужно решить, какое выражение действительно должно быть справа.
// Formatter не может принять это решение за автора.

Опыт 2. Подозрительная логика до запуска программы

Один вариант содержит присваивание в условии. Такой код может быть синтаксически допустимым, но вести себя совершенно иначе, чем ожидал автор сравнения. Biome показывает правило noAssignInExpressions и связанную диагностику постоянного условия. Это хороший пример пользы статического анализа: проблему можно заметить до ручного клика по нужной ветке интерфейса.

Другой вариант сравнивает два значения через двойное равенство. Вопрос здесь не только в стиле. JavaScript может приводить типы, поэтому строка и число оказываются равными в ситуации, которую автор не предусматривал. Linter отмечает риск, но окончательное решение зависит от контракта данных и места их нормализации.

Не исправляйте сообщение механически, не посмотрев вызывающий код. Возможно, форму нужно приводить к числу перед сравнением, возможно — принимать только строковые идентификаторы, а возможно — отклонять неоднозначный ввод. Хорошая диагностика помогает найти вопрос, но ответ должен соответствовать предметной области приложения. Проверяйте исправленную ветку отдельным тестом поведения.

export function ready(flag) {
  if (flag = true) return "yes";
  return "no";
}

export const equal = (left, right) => left == right;

Опыт 3. Safe fix: let превращается в const

В безопасном варианте переменная получает значение и дальше не переназначается. Правило useConst предлагает более точное объявление. Команда lint –write применяет это исправление, и в файле появляется const. При этом речь идёт о переназначении самой переменной; const не делает вложенный объект автоматически неизменяемым.

Обозначение safe относится к оценке конкретного автоматического исправления инструментом. Оно не освобождает от просмотра diff и тестов проекта. Например, в репозитории могут быть генераторы, необычные соглашения или внешняя обработка исходников. Хорошая привычка — применять небольшую область, быстро просматривать результат и затем расширять охват.

В мастерской этот случай отделён от unsafe. Так читатель видит, что флаг –write не означает «применить абсолютно всё». Часть предложений остаётся сообщениями и требует дополнительного решения. Свойства правила и его исправления доступны в документации useConst; наш пример дополнительно проверен фактическим запуском CLI.

let count = 3;
export { count };

// npx --no-install biome lint --write src/counter.js
// В данном опыте результат: const count = 3;

Unsafe fix: исправление может поменять результат

Здесь нужно открыть два варианта рядом по очереди. Без разрешения unsafe сравнение через == остаётся в исходнике, а команда возвращает ошибку правила. С явным –unsafe Biome меняет оператор на ===. Визуально это один символ, но поведение программы уже другое.

Мы не ограничились текстовым diff: собственный короткий пример действительно выполнен в Node до и после. Для входа строка “1” и число 1 результат меняется с true на false. Эта проверка сохранена в JSON и выделена в мастерской. Она объясняет, почему автоматическое исправление нельзя включать общей настройкой без понимания смысла.

Если существующее приложение сознательно допускало приведение типов, новая версия может изменить фильтрацию, поиск или разрешение действия. Лучше определить правильный контракт на границе данных и покрыть его тестом. Документация noDoubleEquals описывает правило; конкретный эффект в статье показан нашим исполняемым опытом.

// До: true
"1" == 1

// После unsafe-исправления: false
"1" === 1

// Разрешение только после анализа конкретного файла:
// npx --no-install biome lint --write --unsafe src/comparison.js

Как внедрять автоматические исправления без огромного diff

Начните с чистого рабочего дерева или сохраните текущую работу отдельным коммитом. Затем выполните проверку без записи и оцените категории проблем. Форматирование большого количества файлов удобно вынести в отдельное изменение, чтобы оно не скрывало исправления логики и не усложняло расследование регрессий.

Safe fixes применяйте небольшими порциями. После каждого этапа посмотрите diff, запустите прикладные тесты и убедитесь, что команда не затронула generated, vendor или сохранённые эталонные данные. Если репозиторий пока не готов к массовому внедрению, ограничьте область новым модулем и постепенно расширяйте её вместе с исправлением технического долга.

Unsafe fixes лучше рассматривать как предложения для автора. В общем npm-скрипте можно оставить обычный check –write, а опасное исправление запускать отдельно по понятной причине. Автоматизация ценна предсказуемостью: разработчик должен заранее понимать, какие классы изменений произойдут после команды. Скрытый набор дополнительных исправлений при каждом сохранении разрушает это ожидание.

npx --no-install biome check src/billing
npx --no-install biome check --write src/billing
git diff -- src/billing
npm test

Опыт 4. JSX-доступность: изображение, подпись и кнопка

В проблемной форме нет альтернативного текста изображения, label не связан с полем, а тип кнопки не указан явно. Biome выдаёт конкретные сообщения для этих мест. Это полезная ранняя проверка: забытый атрибут часто проще поправить во время написания компонента, чем после того, как форма уже встроена в несколько экранов.

Исправленный вариант добавляет осмысленный alt, связывает htmlFor и id и задаёт type=”submit”. В нашей фикстуре сообщения этих правил исчезают. Но отсутствие статических ошибок не доказывает, что форма понятна человеку. Текст подписи может быть неудачным, фокус — уходить в скрытый элемент, а состояние ошибки — оставаться незаметным для screen reader.

Проверяйте интерфейс клавиатурой и в реальном браузере, особенно после открытия модального окна, динамического добавления полей и отправки формы. Biome не видит весь пользовательский сценарий и не заменяет такую приёмку. В статье JSX рассматривается как исходный код для анализа; мастерская не монтирует эти React-компоненты и не выдаёт статический результат за полноценный тест доступности.

export const Form = () => (
  <form>
    <img src="/avatar.png" alt="Аватар клиента" />
    <label htmlFor="name">Имя</label>
    <input id="name" name="name" />
    <button type="submit">Сохранить</button>
  </form>
);

Опыт 5. JSON и CSS: разные языки, разные проверки

В JSON-примере компактная конфигурация превращается в читаемую структуру. В CSS-примере правила карточки и media query получают нормальные переносы и отступы. Это удобно для файлов настроек, стилей компонентов и небольших служебных данных, которые регулярно меняются вместе с кодом приложения.

Отдельный вариант содержит JSON без значения после двоеточия. Он завершается ошибкой и остаётся неизменным. Как и в JavaScript, formatter не должен выбирать за автора пропущенную настройку. Обратите внимание: допустимость комментариев и завершающих запятых зависит от формата файла и конфигурации парсера. JSON и JSONC не стоит считать одним и тем же контрактом для любого потребителя.

Поддержка языка включает несколько отдельных возможностей: разбор, форматирование и набор правил. Наличие formatter не означает, что linter найдёт для этого языка те же классы проблем, что для JavaScript. Перед подключением Vue, Svelte или других смешанных форматов проверьте актуальную матрицу поддержки и собственные файлы проекта.

npx --no-install biome format --write src/settings.json
npx --no-install biome format --write src/card.css

# Конфигурация не должна терять смысл после форматирования.
# Синтаксическая ошибка требует исправления автором.

Опыт 6. Imports: порядок и побочные эффекты

В исходнике есть side-effect import, импорт из встроенного модуля Node и несколько имён из локального файла. Assist упорядочивает группы и именованные импорты. После команды код читается последовательнее, а читателю легче понять зависимости модуля. Изменённый порядок виден в настоящем diff, без подмены заранее нарисованной картинкой.

Отдельный импорт register.js нужен ради выполнения модуля, а не ради используемого имени. В нашем опыте он сохранён и остаётся на прежней границе группы. Это важная проверка: некоторые подключения регистрируют обработчики, полифиллы или стили. Их назначение необходимо понимать перед ручным удалением или перестройкой зависимостей.

Организация imports не равна удалению неиспользуемых импортов. Для второго случая есть отдельный вариант с диагностикой noUnusedImports. В этой конфигурации предупреждение не делает код выхода ненулевым, и никакого удаления без записи не происходит. Поведение assist подробно описано в официальном разделе organizeImports.

import "./register.js";
import { zebra, alpha } from "./items.js";
import { join } from "node:path";
export const result = [join("a", "b"), alpha, zebra];

// В опыте assist меняет порядок обычных imports и имён.
// Подключение ./register.js сохраняется.

Опыт 7. Исключить generated и не скрыть собственный код

Сгенерированный файл может иметь другой стиль или вообще быть временной частью процесса сборки. Если команда каждый раз пытается исправить его вручную, следующий запуск генератора отменяет изменения. Правильнее определить границу: проверять источник генерации и необходимые результаты по подходящим правилам, а технический каталог исключить осознанно.

В опыте generated/broken.js намеренно содержит неверный синтаксис. Конфигурация исключает каталог, и проверка собственного src/main.js проходит. Это не означает, что сломанный файл стал правильным: он просто находится вне выбранной области. Мастерская позволяет выбрать его в списке и увидеть, что содержимое не изменилось.

Для Biome 2.6.7 используем исключение папки !generated. Вариант с !generated/** исключает файлы, но может оставлять лишний обход самого каталога; установленный CLI предупреждает о таком шаблоне. Разницу объясняет правило useBiomeIgnoreFolder. Проверяйте glob-паттерны на настоящей структуре своего репозитория, особенно при вложенных пакетах.

{
  "files": {
    "includes": ["**", "!generated"]
  }
}

Overrides и точечное подавление с объяснением

Иногда правило полезно в приложении, но мешает в ограниченном контексте. Например, console может быть запрещён в основном коде, но нужен для диагностического вывода учебного CLI или теста. Вместо отключения всего linter задайте узкий override для определённых файлов либо подавите конкретное правило возле конкретной строки.

В мастерской показаны оба подхода. Override касается только *.test.js. Подавление noConsole сопровождается причиной на русском языке, чтобы следующий читатель понял, зачем оно оставлено. Такой комментарий должен объяснять намерение, а не просто повторять «это нужно». Если смысл кода изменился, исключение тоже следует пересмотреть.

Не используйте широкое подавление как способ убрать все сообщения перед дедлайном. Оно скрывает и будущие ошибки в изменённом коде. Удобная политика команды — сначала исправить проблему, затем рассмотреть локальное исключение, и только после этого менять общее правило. Поддерживаемый синтаксис находится в документации suppressions.

// biome-ignore lint/suspicious/noConsole: диагностический вывод учебного CLI
console.log("fixture trace");

// Исключение относится к конкретному правилу и следующей конструкции.
// Оно не должно выключать анализ всей программы.

Опыт 8. CI: проверка должна быть одинаковой и не переписывать код

В CI важно получить однозначный результат: checkout соответствует правилам или требует изменений. Команда biome ci предназначена для проверки без записи исправлений. В опыте есть чистый файл и файл с нарушенным форматированием. Первый завершает проверку с кодом 0, второй — с ненулевым кодом.

Мы сравниваем хеши файлов до и после, а также проверяем неизменность конфигурации. Это доказывает наблюдаемое поведение именно нашего запуска: CI-режим не исправил исходники незаметно. Если инструмент возвращает ошибку, автор должен локально посмотреть изменения, применить нужное исправление и отправить новый коммит.

Не превращайте шаг CI в автоматический коммит неизвестных исправлений. Такой процесс усложняет происхождение кода и может смешать проверку с изменением логики. Для обычного проекта понятнее разделить действия: локальное исправление, ревью diff, затем read-only проверка в pipeline. Пример последовательности приведён в официальной инструкции CI.

npm ci
npx --no-install biome ci src
npm test

# Для проекта TypeScript дополнительно:
# npm run typecheck

Предупреждение и ошибка: что означает код выхода

Нулевой код выхода не всегда означает отсутствие любых сообщений. В опыте с неиспользуемым импортом правило имеет серьёзность warning, и обычная проверка завершается успешно. Это полезный повод согласовать политику команды: предупреждения просто подсвечиваются или должны блокировать слияние изменения.

Biome позволяет включить –error-on-warnings, если именно такое поведение требуется в CI. Альтернативный подход — повысить серьёзность конкретного важного правила. Не выбирайте самый строгий режим без оценки существующего кода: большое число неразобранных предупреждений может превратить внедрение в длительную борьбу с pipeline и научить людей обходить проверку.

В мастерской отдельно показаны код выполнения выбранной команды и сводка diagnostics после неё. Они отвечают на разные вопросы: завершилась ли команда успешно и что осталось в файлах. Для скриптов проверяйте код выхода процесса, а не наличие слова error в тексте. Форматирование терминального вывода и локализация сообщений могут меняться между версиями.

npx --no-install biome ci --error-on-warnings src

# PowerShell после команды:
# $LASTEXITCODE

# Linux shell после команды:
# echo $?

Редактор: одинаковые правила при сохранении файла

Расширение редактора сокращает цикл обратной связи: замечание появляется во время работы, а форматирование применяется при сохранении. Но оно должно использовать ту же конфигурацию проекта, что и CLI. Иначе разработчик видит чистый файл локально, а CI предлагает другой результат.

В архиве есть пример настроек VS Code для официального расширения biomejs.biome. Выберите Biome formatter для поддерживаемых языков и проверьте действия на сохранение. Если другой formatter одновременно меняет те же файлы, они могут спорить за кавычки и переносы. Настройки лучше ограничить нужными языками или проектом, сохранив инструменты для форматов вне текущей поддержки.

Не включайте unsafe исправления незаметно для автора. Сохранение файла должно оставаться предсказуемым действием. После установки расширения полезно открыть один знакомый файл, сохранить его, посмотреть diff и сравнить с результатом локального check. Актуальные способы подключения разных редакторов перечислены в разделе настройки редактора.

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  }
}

Git: проверять изменённые файлы, сохраняя полную приёмку

В большом репозитории полная проверка при каждом небольшом действии может быть неудобной. Интеграция с Git позволяет сузить область до подготовленных файлов или изменений относительно выбранной ветки. Для этого Biome должен знать, что используется Git, и учитывать согласованные правила игнорирования.

В CI убедитесь, что базовая ветка действительно доступна в checkout. Поверхностное клонирование или другое имя основной ветки могут сделать сравнение неполным либо привести к ошибке команды. Выбирайте main только если это настоящая база вашего проекта. Для staged-проверки сначала должно быть понятно, какие файлы подготовлены к коммиту.

Ограниченная проверка ускоряет текущую обратную связь, но не заменяет проверку целого проекта перед важным выпуском. Изменение общей конфигурации может повлиять на файлы, которые сами не менялись. Команды и требования VCS описаны в официальной инструкции; в нашей мастерской CI-примеры проверяют фиксированные каталоги, а не ваш Git-репозиторий.

{
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  }
}

// После настройки, из корня Git-проекта:
// npx --no-install biome check --staged
// npx --no-install biome check --changed --since=main

Windows: запустить проект в PowerShell

Распакуйте архив в отдельную папку и перейдите внутрь biome-project. Установите Node LTS из доверенного источника и откройте новое окно PowerShell, чтобы оно увидело актуальный PATH. Сначала проверьте версию, затем выполните npm.cmd ci. Суффикс .cmd позволяет не зависеть от политики запуска npm.ps1.

Тесты запускают настоящий CLI на собственных временных фикстурах. Capture повторяет двадцать опытов и сохраняет JSON, а build копирует локальные стили, исходники и лицензии для мастерской. Start поднимает простой сервер на loopback: откройте 127.0.0.1:8560. Для остановки используйте Ctrl+C в том терминале, где запущен ваш сервер.

Если порт занят другим приложением, выберите свободный через переменную PORT. Не завершайте чужие процессы только ради демонстрации. Локальная кнопка скачивания общего архива рассчитана на опубликованную страницу; у вас исходники уже находятся в распакованной папке. Кнопки скачивания JSON и отдельного файла работают из самой мастерской.

node --version
npm.cmd ci
npm.cmd test
npm.cmd run capture
npm.cmd run build
npm.cmd run quality
npm.cmd start

# Другой порт, если требуется:
$env:PORT = '8566'
npm.cmd start

Windows: проверять свой код и читать результат

Когда демонстрация понятна, подключайте Biome к собственному проекту отдельным изменением. Установите точную зависимость, добавьте конфигурацию и начните с выбранного каталога. Команда с точкой означает текущую область проекта; ошибочный рабочий каталог способен сделать запуск намного шире, чем вы ожидали.

Перед –write сохраните текущие изменения, чтобы их можно было отличить от автоматической обработки. После запуска посмотрите git diff и код выхода. В PowerShell код последней нативной команды находится в LASTEXITCODE; сообщение npm или красивый терминальный вывод не заменяют эту проверку при написании своего скрипта.

Если Biome не найден, сначала убедитесь, что npm ci завершился успешно и devDependencies установлены. Не исправляйте ситуацию случайной глобальной установкой другой версии. Локальная зависимость рядом с lock-файлом делает команду воспроизводимой для коллег и CI. В нашем проекте качество обычного example проверяется отдельным npm-скриптом, не затрагивающим намеренно ошибочные учебные данные.

npx.cmd --no-install biome check example
$LASTEXITCODE

npx.cmd --no-install biome check --write example
git diff -- example

npx.cmd --no-install biome ci example
$LASTEXITCODE

Linux: чистая установка и те же результаты

На Linux последовательность почти такая же, но используется обычная команда npm. Установленный Node должен соответствовать выбранной поддерживаемой ветке. Не переносите Windows node_modules: нативный CLI и служебные зависимости устанавливаются для целевой платформы через npm ci.

Для учебного проекта не нужны root-права, Docker или серверная база данных. Docker удобен для изолированной проверки, но не обязателен пользователю. В нашем тестовом прогоне Linux установка выполнялась заново в отдельном окружении, затем запускались тесты, capture, build и quality. Исходники для Windows и Linux оставались одинаковыми.

Избегайте sudo при форматировании рабочего checkout. Иначе исправленные файлы могут получить владельца root, и следующая обычная команда не сможет их изменить. Если возникают проблемы доступа, разберите права конкретной рабочей папки. Форматтер должен быть частью нормального процесса разработки, а не административной операцией над неизвестным каталогом.

node --version
npm ci
npm test
npm run capture
npm run build
npm run quality
npm start

# Проверка своего каталога:
npx --no-install biome check src
echo $?

Linux/VPS: проверять до развёртывания

Biome обычно нужен на машине разработчика и в pipeline перед выпуском. На production VPS лучше переносить уже проверенный артефакт, а не запускать массовое исправление кода по SSH в рабочем каталоге сервиса. Так проще понимать происхождение файлов, повторить сборку и откатить изменение.

В CI зависимости разработки необходимы, поэтому npm ci –omit=dev перед проверкой Biome не подойдёт для нашего package.json. Сначала установите нужные инструменты в окружении сборки, выполните quality, тесты и type-check вашего приложения, затем создайте артефакт. В production-образ можно переносить только то, что нужно для запуска сервиса.

Приложенный workflow — пример для GitHub Actions, а не отчёт о запуске в вашем аккаунте. Его область example нужно заменить на реальные исходники и дополнить проверками приложения. На собственном Linux-сервере CI логика остаётся той же: отдельный checkout, фиксированные зависимости, проверка без записи и развёртывание только после успешного результата.

# Окружение сборки / CI:
npm ci
npm run quality
npm test
# npm run typecheck
# npm run build

# Дальше публикуется собранный артефакт,
# а не исправляются production-файлы форматтером.

Biome, ESLint, Prettier, TypeScript и Vitest

Biome объединяет несколько повседневных операций, но решение о миграции зависит от проекта. Если существующий ESLint использует важные специальные правила или плагины, сначала проверьте их соответствие выбранному набору Biome. Если Prettier обрабатывает форматы вне нужной вам поддержки, не удаляйте его до проверки реальных файлов.

Удобнее распределять ответственность явно: один formatter для конкретного языка, согласованный статический анализ и отдельные проверки поведения. Одновременное применение двух противоположных форматтеров к одним файлам создаёт бесконечный diff. Постепенный переход позволяет сохранить рабочий процесс и оценить, какие правила действительно нужны команде.

TypeScript type-check и тесты остаются самостоятельными слоями. Статический анализ не проверит весь внешний контракт API или расчёт итоговой стоимости. Для практических тестов поведения полезна наша мастерская Vitest. Сочетайте инструменты по проверяемым свойствам, а не по принципу «одна новая зависимость обязана заменить всё».

Конструктор biome.json: полезная отправная точка

Вторая часть мастерской позволяет выбрать отступ в два или четыре пробела, длину строки и кавычки JS/TS. На основе этих параметров создаётся обычный JSON с ограничением на src и исключением src/generated. Его можно скачать и положить в корень своего проекта, затем проверить на собственных файлах.

Все двенадцать сочетаний параметров из интерфейса проходят проверку настоящим CLI в тестах. Это подтверждает корректность создаваемой конфигурации для зафиксированной версии. Однако конструктор не знает структуру вашего монорепозитория, текущие соглашения и сторонние форматы. Перед использованием измените область includes, если исходники лежат иначе.

Конструктор намеренно не редактирует запись выбранного опыта выше. Его задача — подготовить файл настроек, а задача replay — показать фактический результат уже выполненной команды. Такое разделение помогает избежать ложного впечатления, будто любой новый параметр мгновенно пересчитал Biome в браузере. Для свободного редактирования кода есть официальный Playground.

Что делать при неожиданных сообщениях

Начните с версии CLI и местоположения конфигурации. Если редактор и терминал дают разные результаты, проверьте выбранный formatter, локальный пакет, рабочий каталог и дополнительные настройки workspace. При изменении major не переносите старый конфиг без миграции и просмотра новых сообщений.

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

Полезный отчёт об ошибке содержит версию, минимальный пример, конфигурацию, точную команду и ожидаемый результат. Наш capture устроен похожим образом: он сохраняет собственные фикстуры, diagnostics и хеши происхождения. При работе с закрытым проектом перед публикацией такого отчёта удаляйте секреты и приватные пути, сохраняя минимальный воспроизводимый случай.

Как проверен проект и как получить собственную запись

Тесты проекта действительно запускают Biome CLI, а не сравнивают заранее придуманные строки. Проверяются форматирование, сохранение ошибочного parse-файла, категории логических проблем, различие safe и unsafe, исправленная JSX-разметка, imports, исключения и read-only поведение CI. Отдельный тест запускает все варианты конструктора конфигурации.

Для unsafe-опыта выполняется собственная маленькая функция до и после, чтобы изменение результата было доказано. Произвольный код посетителя не исполняется. В capture сохраняются относительные или обезличенные пути, а проверка ищет утечки временных пользовательских каталогов. Дата и версии показывают, к какому окружению относится запись.

При изменении примеров повторите test, capture и build в этом порядке. Windows и Linux-прогоны подтверждают работу проекта в проверенных окружениях; они не заменяют запуск вашего GitHub workflow или проверку конкретного приложения. Публичная мастерская предназначена для изучения и сравнения результатов, а реальная команда остаётся в скачиваемых исходниках.

npm test
npm run capture
npm run build

# В public/capture.json:
# runtime, capturedAt, sourceHashes, definitions, records

Исходники и материалы для продолжения

В архиве находятся исходники мастерской, генератор фикстур, runner CLI, тесты, двадцать записей, конфигурация, маленький пример приложения и README с командами Windows/Linux. Папка node_modules не включена: зависимости ставятся из lock-файла. Авторский код доступен по MIT, лицензии сторонних компонентов приложены отдельно.

Для визуального разбора изменений посмотрите также diff2html, а для создания редактора в интерфейсе — CodeMirror 6. Подсветка и diff помогают читать результат, но сами по себе не выполняют статический анализ Biome.

Основные официальные материалы: установка, конфигурация, CLI, linter и CI. При добавлении инструмента в рабочий проект начните с конкретной области и понятных правил, а затем закрепите одинаковую проверку в редакторе и pipeline.