Biome 완벽 가이드 — 초고속 린터·포매터
이 글의 핵심
Biome은 JavaScript·TypeScript·JSON·CSS 등을 다루는 통합 도구로, 린트·포맷·임포트 정리를 단일 바이너리로 수행합니다. 이 글에서는 핵심 개념, ESLint·Prettier 마이그레이션, biome.json 작성법, 에디터·CI·모노레포 운용까지 실무 관점에서 설명합니다.
이 글의 핵심
Biome은 프런트엔드·풀스택 코드베이스에서 흔히 쓰이는 ESLint(린터)와 Prettier(포매터) 역할을 하나의 CLI와 설정 파일로 통합하려는 도구입니다. Rust로 구현되어 실행 속도가 빠르고, 별도의 Node.js 런타임 없이도 동작하는 배포 모델을 갖추고 있어 대규모 저장소에서도 체감 이점이 큽니다.
이 글에서는 Biome의 핵심 개념과 장점, ESLint·Prettier에서의 마이그레이션 절차, biome.json 설정, VS Code와 JetBrains 통합, CI/CD 파이프라인, 모노레포 구성을 순서대로 다룹니다. 이미 린트·포맷 파이프라인을 운영 중인 팀이 새 도구를 도입할 때 필요한 판단 기준과 실무 체크리스트를 함께 정리했습니다.
1. Biome이란 무엇인가
1.1 핵심 개념
Biome은 린터(linter), 포매터(formatter), 임포트 정리(import organizer) 기능을 한 프로젝트 안에서 제공합니다. 사용자는 주로 biome.json(또는 biome.jsonc) 하나로 규칙과 스타일을 선언하고, CLI 또는 에디터 확장을 통해 동일한 설정을 공유합니다.
설계상 다음과 같은 특징이 있습니다.
- 단일 도구: 규칙 충돌(린터가 원하는 코드 vs 포매터가 바꾼 코드)을 줄이기 위해, 한 엔진이 진단과 포맷을 함께 다룹니다.
- 빠른 실행: 대규모 저장소에서 반복 실행되는
lint·format작업의 대기 시간을 줄이는 것이 주요 목표 중 하나입니다. - 일관된 기본값: 팀이 “권장 프리셋”에서 출발해 필요한 규칙만 조정하는 워크플로를 지향합니다.
1.2 ESLint·Prettier 대비 장점
속도는 Biome을 도입하는 가장 흔한 이유입니다. 기존에는 ESLint와 Prettier를 각각 실행하거나, 에디터에서 두 번의 포맷·진단 사이클이 돌아가는 경우가 있었습니다. Biome은 한 번의 check 또는 ci로 여러 단계를 묶을 수 있어, 로컬 개발과 CI 모두에서 시간을 절약할 수 있습니다.
설정 단순화도 중요한 장점입니다. .eslintrc, .prettierrc, 플러그인 의존성, ignore 파일 규칙이 분산되어 있던 구조를 biome.json 중심으로 모을 수 있습니다. 물론 ESLint 생태계의 모든 플러그인 규칙이 1:1로 대응되는 것은 아니므로, “완전 동일한 규칙 집합”이 필요한 팀은 마이그레이션 후 규칙 갭 분석이 필요합니다.
개발자 경험 측면에서는 공식 VS Code 확장과 JetBrains 플러그인을 통해 LSP 기반 진단·수정·포맷을 제공한다는 점이 큽니다. 팀 전원이 같은 버전의 Biome을 쓰도록 package.json에 고정하는 방식이 일반적입니다.
2. 설치 및 초기화
프로젝트 루트에서 개발 의존성으로 설치합니다. 버전 고정을 위해 --save-exact를 권장합니다.
npm install --save-dev --save-exact @biomejs/biome
npx @biomejs/biome initinit은 기본 biome.json을 생성합니다. 이후 package.json에 스크립트를 추가해 팀이 동일한 명령을 사용하도록 합니다.
{
"scripts": {
"check": "biome check .",
"check:write": "biome check --write .",
"format": "biome format --write .",
"lint": "biome lint .",
"ci": "biome ci ."
}
}biome check는 포맷·린트·임포트 정리 등을 묶어 실행하는 상위 명령으로 생각하면 됩니다. 로컬에서는 --write로 자동 수정까지 적용하고, CI에서는 수정 없이 검증만 하는 편이 안전합니다.
3. biome.json 설정 작성
3.1 최소 구성 예시
아래는 Biome 2.x 기준으로 권장 규칙을 켠 기본 형태입니다. 프로젝트에 맞게 files, vcs, overrides를 확장합니다. Biome 1.x를 쓰는 레거시 저장소는 organizeImports 필드 등 예전 키를 참고해야 할 수 있습니다.
{
"$schema": "https://biomejs.dev/schemas/2.4.12/schema.json",
"files": {
"ignoreUnknown": false,
"includes": ["**", "!!**/dist", "!!**/build", "!!**/.next", "!!**/coverage"]
},
"formatter": {
"enabled": true,
"indentStyle": "tab",
"indentWidth": 2,
"lineWidth": 100
},
"assist": {
"enabled": true,
"actions": {
"source": {
"recommended": true
}
}
},
"linter": {
"enabled": true,
"rules": {
"recommended": true
}
},
"javascript": {
"formatter": {
"quoteStyle": "double",
"semicolons": "always",
"trailingCommas": "all"
}
}
}$schema는 설치한 버전에 맞춰 https://biomejs.dev/schemas/<버전>/schema.json 형식으로 두거나, ./node_modules/@biomejs/biome/configuration_schema.json을 가리키면 로컬 스키마로 자동완성할 수 있습니다.
3.2 린터 규칙과 심각도
linter.rules 아래에는 style, suspicious, correctness 등 카테고리별 규칙이 배치됩니다. 팀 합의 하에 특정 규칙을 error·warn·off로 조정합니다. “Prettier와 동일한 스타일”을 우선한다면 포매터 옵션을 먼저 맞추고, 린트는 점진적으로 강화하는 방식이 충돌이 적습니다.
3.3 VCS 연동(.gitignore 존중)
ESLint·Prettier가 Git이 무시하는 파일을 건너뛰는 것과 유사하게, Biome도 vcs 설정을 통해 버전 관리 클라이언트와 통합할 수 있습니다. 저장소 루트에 biome.json이 있다면, vcs.useIgnoreFile 등을 켜서 불필요한 파일을 분석 대상에서 제외하는 구성이 일반적입니다. CI에서도 동일한 무시 규칙이 적용되어야 로컬과 결과가 일치합니다.
{
"vcs": {
"enabled": true,
"clientKind": "git",
"useIgnoreFile": true
}
}3.4 overrides로 경로별 규칙
테스트 코드, 스크립트, 레거시 폴더에만 다른 규칙을 적용하려면 overrides에 include 패턴을 지정합니다. ESLint의 overrides와 같은 역할로 이해하면 됩니다.
{
"overrides": [
{
"include": ["**/*.test.ts", "**/__tests__/**"],
"linter": {
"rules": {
"suspicious": {
"noExplicitAny": "off"
}
}
}
}
]
}4. ESLint·Prettier에서 마이그레이션
4.1 자동 마이그레이션 명령
Biome은 기존 설정을 읽어 biome.json으로 옮기는 서브커맨드를 제공합니다.
npx @biomejs/biome migrate eslint --write
npx @biomejs/biome migrate prettier --writemigrate eslint: 레거시.eslintrc와 flat config 모두 지원 범위 내에서 동작합니다. 플러그인 의존성 해석을 위해 Node.js가 필요할 수 있습니다. YAML 형식의 ESLint 설정은 지원되지 않을 수 있으므로, 해당 경우 JSON/JS로 옮기거나 수동 매핑을 검토해야 합니다. ESLint 규칙과 Biome 규칙 이름이 다르고, 동작이 100% 동일하지 않을 수 있습니다.migrate prettier:.prettierrc등을 반영합니다. JSON5·TOML·YAML Prettier 설정은 마이그레이션 제약이 있을 수 있어, JSON 기반 설정으로 정리한 뒤 실행하는 편이 안전합니다.
Biome이 “영감을 받은(inspired)” 규칙까지 ESLint에서 그대로 옮기지 않는 경우가 있으므로, 필요하면 --include-inspired 옵션을 검토합니다(프로젝트 규모에 따라 노이즈가 늘 수 있습니다).
4.2 마이그레이션 후 꼭 할 일
biome check로 전체 저장소를 돌려 오류·경고 목록을 확보합니다.- ESLint 주석(
eslint-disable)에 의존하던 부분은 Biome 규칙 ID 기준으로 정리합니다. 주석 체계가 다르므로, 숨겨 두었던 기술 부채가 드러날 수 있습니다. - CI에서
biome ci로 최종 검증합니다. - 팀 문서(기여 가이드)의 명령어·에디터 설정을 Biome 기준으로 갱신합니다.
일부 팀은 전환 기간에 ESLint를 병행하기도 하지만, 규칙이 두 벌이면 개발자 혼란이 커집니다. 가능하면 단일 도구로 수렴하는 일정을 잡는 것이 좋습니다.
5. VS Code 통합
공식 확장 Biome(biomejs.biome)을 설치합니다. Visual Studio Code Marketplace 또는 Open VSX(VSCodium 등)에서 받을 수 있습니다.
5.1 저장 시 포맷·안전 수정·임포트 정리
워크스페이스 .vscode/settings.json 예시는 다음과 같습니다.
{
"editor.defaultFormatter": "biomejs.biome",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.biome": "explicit",
"source.organizeImports.biome": "explicit"
}
}source.fixAll.biome은 안전한(safe) 수정 위주입니다. 불안전한 수정이 필요하면 규칙 설정을 조정하거나, CLI에서 명시적으로 적용하는 전략을 씁니다.
5.2 자주 쓰는 설정
biome.requireConfiguration:true로 두면biome.json이 있을 때만 포맷·진단을 등록해, 엉뚱한 폴더에서 확장이 개입하는 것을 막을 수 있습니다.biome.lsp.bin: 모노레포에서 특정 패키지의 Biome 바이너리를 가리킬 때 유용합니다.
멀티 루트 워크스페이스에서는 폴더마다 Biome 인스턴스가 생기므로, 각 패키지에 biome.json을 두는 모노레포 구조와 잘 맞습니다.
6. JetBrains 통합(WebStorm 등)
Biome 팀은 IntelliJ 계열용 플러그인(biomejs/biome-intellij)을 제공합니다. JetBrains Marketplace에서 “Biome”을 검색해 설치합니다. WebStorm 등 최신 IDE 버전과의 호환 범위는 플러그인 페이지의 릴리스 노트를 확인하세요.
6.1 동작 방식과 설정 요지
플러그인은 프로젝트 로컬의 node_modules에 설치된 biome을 우선 탐지하는 방식이 일반적입니다. 팀원마다 전역 설치에 의존하지 않도록, @biomejs/biome를 devDependencies에 고정해 두는 것이 중요합니다.
설정에서 LSP 기반 포맷을 활성화해야 포맷터로 일관되게 동작하는 경우가 많습니다. 저장 시 자동 수정을 켜려면 IDE의 “저장 시 액션” 또는 플러그인 옵션을 함께 조정합니다. VS Code와 마찬가지로 CLI와 IDE의 Biome 버전 불일치가 가장 흔한 불일치 원인이므로, 버전을 레포에서 통일합니다.
7. CI/CD 파이프라인 구성
7.1 biome ci를 쓰는 이유
CI에서는 파일을 수정하면 안 되므로 biome ci가 적합합니다. 포맷터·린터·임포트 정리를 읽기 전용으로 실행하며, 문제가 있으면 비제로 종료되어 파이프라인이 실패합니다.
npx @biomejs/biome ci .7.2 GitHub Actions 예시
name: Biome
on:
pull_request:
push:
branches: [main]
jobs:
biome:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: '22'
cache: npm
- run: npm ci
- run: npx @biomejs/biome ci .7.3 변경 분만 검사하기
대규모 저장소에서는 PR에 포함된 변경 파일만 검사해 시간을 줄일 수 있습니다. Biome CLI의 --changed 또는 --since 계열 옵션을 사용하면, 기본 브랜치 대비 차이만 대상으로 삼을 수 있습니다. 정확한 플래그 이름과 동작은 사용 중인 Biome 버전의 biome ci --help를 기준으로 삼으세요.
캐시 전략으로는 node_modules 캐시, 또는 Biome 바이너리 설치 캐시를 활용하는 방법이 있습니다. 팀에서는 로컬 npm run check와 CI biome ci가 같은 버전을 쓰는지 먼저 확인하는 것이 좋습니다.
8. 모노레포 지원
Biome v2 이후 모노레포를 공식적으로 고려한 설정 모델이 정리되었습니다. 핵심은 루트 biome.json을 기준(base)으로 두고, 패키지별로 세부 설정을 중첩하는 것입니다.
8.1 루트와 패키지별 설정
루트에 공통 규칙·포맷 폭을 정의합니다.
{
"formatter": { "lineWidth": 100, "indentStyle": "space", "indentWidth": 2 },
"linter": { "enabled": true, "rules": { "recommended": true } }
}특정 패키지(packages/logger 등)에만 다른 규칙을 주려면 해당 폴더에 biome.json을 두고, 루트 설정을 상속합니다. 공식 문서에서는 "extends": "//" 마이크로문법으로 루트 구성을 물려받는 패턴이 소개됩니다. 코드 생성물 폴더처럼 포맷을 끄고 싶다면 해당 패키지에서 formatter.enabled를 false로 두는 식으로 조정합니다.
8.2 extends로 공통 파일·npm 패키지 공유
팀 내부 공통 규칙을 common.json으로 두고 여러 앱에서 extends로 불러올 수 있습니다. 더 나아가 npm 패키지의 exports에 Biome 설정을 노출해 @org/shared-configs/biome 형태로 재사용하는 방법도 지원됩니다. 이때 패키지가 node_modules에 올바르게 설치되어 있어야 하며, 해석 기준은 실행 위치(워킹 디렉터리)에 따릅니다.
8.3 실행 위치와 탐색 규칙
Biome은 가장 가까운 biome.json을 파일 경로 쪽에서 탐색합니다. 루트에서 한 번에 전체를 돌릴지, 패키지별로 스크립트를 둘지는 팀 워크플로에 맞게 선택합니다. 루트에서 통합 실행 시에는 각 패키지의 중첩 설정이 기대대로 적용되는지 샘플 PR로 검증하는 것이 좋습니다.
9. 트러블슈팅과 운영 팁
- 버전 불일치: 로컬·CI·IDE가 서로 다른 Biome을 쓰면 진단 결과가 달라집니다.
package.json과 lockfile로 버전을 고정하고, IDE는biome.lsp.bin으로 명시할 수 있습니다. - Prettier와 탭/스페이스 불일치: Biome은 기본값이 Prettier와 다를 수 있습니다.
migrate prettier후에도 팀 스타일이 남아 있다면formatter.indentStyle·javascript.formatter를 다시 확인합니다. - 규칙 과다: 마이그레이션 직후 경고가 폭증하면,
recommended에서 출발해 카테고리별로 단계적으로 켜는 것이 유지보수에 유리합니다. - 대용량 파일: CI에서 특정 생성 파일이 분석에 포함되면 시간이 늘어납니다.
files.ignore와 VCS ignore 연동으로 제외합니다.
10. 정리
Biome은 린트·포맷·임포트 정리를 한 엔진으로 묶어 개발자 피드백 루프와 CI 시간을 줄이는 데 초점을 맞춘 도구입니다. biome.json으로 표준을 고정하고, biome migrate로 기존 ESLint·Prettier 설정을 이전한 뒤, biome ci로 파이프라인을 잠그는 흐름이 실무에서 가장 많이 쓰입니다. 모노레포에서는 루트·패키지 중첩 설정과 extends를 활용해 팀·제품 단위로 유연성을 확보할 수 있습니다.
도입 여부를 결정할 때는 “Biome 규칙 집합이 우리 팀의 코딩 표준을 얼마나 커버하는가”와 “남은 ESLint 플러그인 요구를 대체할 수 있는가”를 기준으로 평가하면 됩니다. 점진적 전환이 필요하면 짧은 스프린트로 마이그레이션·교육·문서화를 묶어 진행하는 것을 권장합니다.