@astral/biomejs-config

Совместимость с версией biomejs

!!! Совместим только с версией biomejs 2.x.x

Установка

npm install @biomejs/[email protected] @astral/biomejs-config --save-dev

Доступные конфиги

• @astral/biomejs-config/web - конфиг для frontend приложений
• @astral/biomejs-config/node - конфиг для nodejs приложений

Дополнительная функциональность конфигов

• Совместимость с @astral/eslint-config-react-ts
• Игнорирует файлы и директории, указанные в .gitignore
• Настроена и включена сортировка и группировка импортов
• Разрешает импорт пакета из devDeps в файлах конфигураций и тестах
• Разрешает использование console.log в файлах конфигураций

Кастомные правила

Запрещены index файлы для слоев и директорий группировок

index файлы запрещены:

• В корне shared, modules, api, screens директорий
• В директориях первого уровня вложенности shared, modules, api
• shared/form директории
• modules/**/features директории

Запрещен импорт из корня для библиотек @astral/*

Список обрабатываемых библиотек:

• @astral/ui
• @astral/features
• @astral/utils
• @astral/services

✅ Valid:

import { Button } from '@astral/ui/Button'

❌ Invalid:

import { Button } from '@astral/ui'

Запрещен импорт внутренних частей features

✅ Valid:

import { Profile } from '#modules/requests/features/profile'

❌ Invalid:

import { Profile } from '#modules/requests/features/profile/utils'

Особенность реализации правила: работает только для импортов, содержащих в путях modules (ограничение biome). То есть импорт вида ../../profile/utils не будет обработан.

Запрещен импорт приватных сущностей

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

✅ Valid:

import { publicHelper } from '#modules/requests/features/profile'

❌ Invalid:

import { _internalHelper } from '#modules/requests/features/_profile'

Запрещен относительный импорт . и ..

✅ Valid:

import { MyComponent } from './MyComponent'

❌ Invalid:

import { MyComponent } from '.'

Запрещено использование нативных HTML-тегов для текста

Для обеспечения единообразия UI запрещено использование стандартных тегов (p, span, h1-h6 и др.). Вместо них следует использовать компонент Typography.

❌ Invalid:

<p>Some text</p>

✅ Valid:

<Typography>Some text</Typography>

Запрещен импорт внешних библиотек вне shared слоя

Для централизованного управления зависимостями, внешние библиотеки (например, @mui/material, dayjs, remeda) должны реэкспортироваться через shared слой.

❌ Invalid:

import { format } from 'dayjs'

✅ Valid:

import { format } from '#shared/utils/date'

Правила для конфигурационных файлов

Для файлов конфигураций (JS-файлы в корне, файлы с префиксом vite) действуют послабления:

• Разрешено использование console.log (правило noConsole отключено).
• Разрешено использование CommonJS (правило noCommonJs отключено).

Разрешено использование devDependencies

В тестовых файлах, конфигурациях и т.п. разрешен импорт пакетов из devDependencies (правило noUndeclaredDependencies настроено с исключениями).

Список исключений:

• **/*.test.*, **/_tests/**, **/tests/**, **/pw/**
• **/vite*, **/playwright.config.ts, **/next.config.js и др.
• **/*.stories.tsx, **/stories/**
• **/.scripts/**, **/faker.ts

Правила именования (Naming Convention)

Для обеспечения единообразия кода установлены следующие правила именования:

• Интерфейсы: должны начинаться с префикса I (например, IUser).
• Generics (Type Parameters): должны начинаться с префикса T (например, TComponent).

Группировка и сортировка импортов

Импорты автоматически группируются в следующем порядке:

1. Системные и внешние пакеты (node:, npm:).
2. Aliases (#shared, #modules и др.).
3. Относительные пути.

Между группами должна быть одна пустая строка. Внутри групп импорты сортируются по алфавиту.

Настройка

Базовая настройка

Пример настройки.

Создать biome.json в корне

biome.json

{
  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
  "extends": ["@astral/biomejs-config/web"]
}

Включить автофикс при сохранении в IDE

Установить в IDE biome плагин.

VSCode

Настройка плагина.

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

WebStorm

После установки плагина перейти в Settings -> Languages & Frameworks -> Biome, включить все чекбоксы для форматирования при сохранении файла.

!!! Для корректной работы необходимо установить последнюю версию плагина >= 1.7.2, обратить внимание на совместимость с версией WebStorm

Версии плагина и совместимость с WS.

Monorepo

Пример настройки.

Ручная настройка запрета импортов между архитектурными слоями

Пример настройки.

Migration Guide: ESLint -> Biome

1. Заменить внутренние alias, с @ на # (пример: #shared, #api). Правило style guide

2. Удалить Eslint зависимости, отключить Eslint в IDE. Удалить Prettier, если не используется Stylelint.

3. Установить biome и @astral/biomejs-config

npm install @biomejs/[email protected] @astral/biomejs-config --save-dev

4. Добавить biome.json в корень проекта. Пример настройки в монорепозитории.

biome.json

{
  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
  "extends": ["@astral/biomejs-config/web"]
}

5. Установить плагин Biome для IDE и включить автофикс при сохранении (см. инструкцию выше)

6. Заменить eslint-disable-next-line на соответствующий biome-ignore с указанием причины.

{
    eslint-disable-next-line -> biome-ignore
    
    @typescript-eslint/no-explicit-any -> lint/suspicious/noExplicitAny: Причина
    import/no-extraneous-dependencies -> lint/correctness/noUndeclaredDependencies: Причина
    @typescript-eslint/no-throw-literal -> lint/style/noParameterAssign: Причина
    @typescript-eslint/no-unused-vars -> lint/correctness/noUnusedVariables: Причина
    @typescript-eslint/no-shadow -> lint/suspicious/noShadowRestrictedNames: Причина
    no-param-reassign -> lint/style/noParameterAssign: Причина
    no-console -> lint/suspicious/noConsole: Причина
    @typescript-eslint/no-useless-constructor -> lint/complexity/noUselessConstructor: Причина
    @typescript-eslint/no-use-before-define -> lint/correctness/noInvalidUseBeforeDeclaration: Причина
}

Подробное сопоставление правил можно найти здесь https://biomejs.dev/linter/javascript/sources/#eslint

7. Заменить Eslint скрипты в package.json на biome

{
  "scripts": {
    "lint": "biome check --write --diagnostic-level=error",
    "lint:all": "biome check --write",
    "lint:ci": "biome check --diagnostic-level=error"
  }
}

8. Запустить скрипт lint:all. Он выполнит safe fix ошибок.

9. Выполнить unsafe фикс, если необходимо biome check --write --unsafe

10. Оставшиеся ошибки необходимо исправить руками. (Совет: если ошибок много - временно отключите соответствующие правила в локальном biome.json, затем включайте по одному для исправления)

11. Поменять скрипт в CI на "lint:ci"

Changelog

v2

Изменения в версии 2 нацелены на поддержку отказа от barrel файлов в архитектуре.

Изменения

Запрещены index файлы для слоев и директорий группировок

index файлы запрещены:

• В корне shared, modules, api, screens директорий
• В директориях первого уровня вложенности shared, modules, api
• shared/form директории

Запрещен импорт из корня для библиотек @astral/*

Список обрабатываемых библиотек:

• @astral/ui
• @astral/features
• @astral/utils
• @astral/services

✅ Valid:

import { Button } from '@astral/ui/Button'

❌ Invalid:

import { Button } from '@astral/ui'

Запрещен импорт внутренних частей features

✅ Valid:

import { Profile } from '#modules/requests/features/profile'

❌ Invalid:

import { Profile } from '#modules/requests/features/profile/utils'

Особенность реализации правила: работает только для импортов, содержащих в путях modules (ограничение biome). То есть импорт вида ../../profile/utils не будет обработан.

Запрещен импорт приватных сущностей

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

✅ Valid:

import { publicHelper } from '#modules/requests/features/profile'

❌ Invalid:

import { _internalHelper } from '#modules/requests/features/_profile'

Запрещен относительный импорт . и ..

✅ Valid:

import { MyComponent } from './MyComponent'

❌ Invalid:

import { MyComponent } from '.'