Biome만으로 ESLint와 Prettier를 완전히 대체할 수 있나요?

많은 프로젝트에서는 가능합니다. 다만 ESLint 플러그인 생태계 전부를 그대로 옮기는 것은 어렵고, 팀 규칙·프레임워크별 규칙은 마이그레이션 후 점검이 필요합니다.

CI에서는 어떤 명령을 쓰는 것이 좋나요?

파일을 수정하지 않는 biome ci가 적합합니다. 포맷·린트·임포트 정리 결과를 검증하고, 실패 시 비제로 종료 코드로 파이프라인을 막을 수 있습니다.

Biome이 “빠른” 이유를 내부적으로 어떻게 설명할 수 있나요?

Rust 단일 바이너리, 손실 없는 파싱과 트리 연산, 데몬·스캐너 타깃팅·변경분만 검사 같은 실행 경로 최적화가 겹칩니다. 다만 체감 속도는 워크스페이스 크기와 규칙·프로젝트 도메인 설정에도 좌우됩니다.

포매터 출력이 Prettier와 항상 동일한가요?

“Prettier 호환”을 목표로 하지만, 버전·엣지 케이스·옵션 조합에 따라 미세한 차이가 남을 수 있습니다. 팀에서는 대표 파일로 스냅샷 비교나 포맷 체크를 한 번 거치는 것이 안전합니다.

Biome 완벽 가이드 — 초고속 린터·포매터

2026년 4월 7일 · 57분 읽기 · 수정 2026년 4월 7일 중급 tutorial

이 글의 핵심

Biome은 JavaScript·TypeScript·JSON·CSS 등을 다루는 통합 도구로, 린트·포맷·임포트 정리를 단일 바이너리로 수행합니다. 이 글에서는 Rust 파서·CST·규칙 엔진·포매터 IR·증분 분석 같은 내부 동작을 짚은 뒤, biome.json, 마이그레이션, 에디터·CI·모노레포, 프로덕션 운용 패턴까지 실무 관점에서 설명합니다.

이 글의 핵심

Biome은 프런트엔드·풀스택 코드베이스에서 흔히 쓰이는 ESLint(린터)와 Prettier(포매터) 역할을 하나의 CLI와 설정 파일로 통합하려는 도구입니다. Rust로 구현되어 실행 속도가 빠르고, 별도의 Node.js 런타임 없이도 동작하는 배포 모델을 갖추고 있어 대규모 저장소에서도 체감 이점이 큽니다.

이 글에서는 Biome의 핵심 개념과 장점, Rust 파서·CST·린트 엔진·포매터 층의 내부 구조, 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. 내부 아키텍처: 파서·분석기·포매터·증분 실행

이 절에서는 CLI 사용법에 앞서, Biome이 왜 한 번의 실행으로 빠르게 린트와 포맷을 함께 처리할 수 있는지 구현 관점에서 정리합니다. 공식 문서의 Architecture와 크레이트 구조를 바탕으로 하되, 버전에 따라 세부 구현은 달라질 수 있으므로 원리 중심으로 이해하는 것이 좋습니다.

2.1 Rust 기반 파서와 CST(rowan)·오류 허용 파싱

Biome의 JavaScript·TypeScript 파싱은 biome_js_parser 등 언어별 파서 크레이트에서 수행되며, 트리 표현은 rowan 라이브러리를 내장 포크한 형태의 Green/Red 트리 패턴을 따릅니다. 여기서 중요한 것은 “추상 문법 트리(AST)만”을 만드는 것이 아니라, 공백·탭·주석까지 포함한 CST(Concrete Syntax Tree, 구체적 구문 트리) 를 유지한다는 점입니다.

CST는 소스 텍스트와 1:1에 가까운 대응을 유지하므로, 포매터가 “원문을 잃지 않고” 다시 인쇄(print)하기에 적합합니다. 트리비아(trivia)는 토큰에 선행(leading)·후행(trailing) 으로 붙으며, 공식 문서에서 설명하듯 한 줄을 왼쪽에서 오른쪽으로 읽을 때의 규칙으로 정리됩니다. 개발자가 직접 Green 트리를 만지기보다는, 문법 정의로부터 생성된 타입 안전 API 로 Red 트리를 탐색하는 사용 모델이 일반적입니다.

파서는 오류 허용(error-tolerant) 과 복구(recoverable) 를 목표로 합니다. 문법 오류가 있어도 가능한 한 나머지 구문을 계속 읽고, 깨진 구간은 Bogus 노드 등으로 격리해 소비자(린터·포매터)가 전체 분석을 중단하지 않도록 합니다. 덕분에 에디터에서 저장 중간 상태의 파일도 어느 정도 진단·포맷 피드백을 받을 수 있습니다. 다만 복구 경로는 “항상 동일한 의미”를 보장하지 않으므로, 깨진 구문에 의존한 규칙 결과는 보조적으로 보는 편이 안전합니다.

2.2 스캐너·프로젝트 메타데이터와 린트의 입력

Biome은 파일을 열기 전에 스캐너가 워크스페이스를 훑어 중첩 biome.json, .gitignore 계열(설정에 따라), 필요 시 package.json·소스 인덱스 등을 수집합니다. 특히 프로젝트(project) 도메인 규칙을 켠 경우에는 매니페스트와 소스 맵을 더 넓게 조사하는 경로로 들어가며, 반대로 해당 규칙이 꺼져 있으면 세션에 필요한 폴더만 타깃으로 삼아 불필요한 크롤을 줄이는 최적화가 적용됩니다. 모노레포에서 특정 패키지 아래만 실행하면, 루트·상위 폴더와 해당 패키지 위주로만 스캔 범위가 잡히는 식입니다.

이 구조는 “린트가 텍스트 파일만 본다”는 단순 모델을 넘어서, 저장소 레이아웃·설정 계층까지 입력으로 삼을 수 있게 합니다. 운영 관점에서는 files.includes와 스캐너의 상호작용을 이해해야, 왜 특정 폴더가 분석에서 빠지거나 반대로 의도보다 넓게 스캔되는지를 설명할 수 있습니다.

2.3 AST·구문 노드 순회와 규칙 엔진

린터 층은 파서가 만든 구문 트리를 따라 규칙(rule)을 적용합니다. 구현 세부는 버전마다 다르지만, 개념적으로는 각 규칙이 특정 노드 종류·패턴을 방문(visit)하며 진단(diagnostic) 과 선택적 수정(fix) 을 생성합니다. 진단은 심각도·카테고리(correctness, suspicious, style 등)와 함께 보고되고, 수정은 안전(safe) 과 안전하지 않음(unsafe) 으로 나뉘어 기본 워크플로에서 다르게 취급됩니다.

규칙은 서로 독립적으로 설계되지만, 같은 CST/구문 모델 위에서 동작하므로 ESLint처럼 “파서는 Babel, 규칙은 ESTree 가정” 같은 이중 스택을 줄이는 효과가 있습니다. 반대로 말하면, 커스텀 ESLint 플러그인에 있던 매크로·타입 정보·특수어트리뷰트에 기대던 규칙은 Biome에 그대로 이식되지 않을 수 있어, 마이그레이션 시 규칙 갭 분석이 필요합니다.

TypeScript의 경우, 파싱 이후 시맨틱/타입 계층(체크된 시맨틱 모델)을 규칙이 참조하는 경로가 있으며, 이는 “단순 텍스트 정규식 린트”와 성격이 다릅니다. 팀 내부에서 규칙을 논할 때는 구문 기반 규칙과 타입·스코프를 아는 규칙을 구분해 기대치를 맞추는 것이 좋습니다.

2.4 포매터 알고리즘과 Prettier 호환 철학

포매터는 별도의 Prettier 프로세스를 띄우지 않고, 동일 바이너리 안의 biome_formatter 계열 인프라로 동작합니다. 코드는 구문 트리에서 포맷 규칙에 따라 중간 표현(일반적으로 IR: 줄바꿈·들여쓰기·그룹핑 등의 문서(document) 모델)으로 올라간 뒤, 설정된 줄 폭(line width) 과 들여쓰기 스타일에 맞춰 문자열로 인쇄됩니다.

Biome은 공개적으로 Prettier와의 호환을 목표로 하며, 옵션도 “팀마다 취향이 갈리기 쉬운 스타일 논쟁”을 줄이기 위해 소수의 언어 중립·언어별 옵션에 두는 철학을 따릅니다. 그러나 바이트 단위 동일성을 보장하는 도구는 아니며, 엣지 케이스·버전 차이·옵션 조합에 따라 Prettier 출력과 미세한 차이가 남을 수 있습니다. 실무에서는 대표 샘플로 스냅샷을 비교하거나, 전환 직후 한동안 포맷 전용 CI 잡을 별도로 두어 차이를 감시하는 패턴이 안전합니다.

포매터가 CST를 유지하는 이유와 연결지어 보면, 주석·줄바꿈 위치를 보존하는 정책이 Prettier 사용자에게 익숙한 결과로 이어지는 경우가 많습니다. 다만 “주석을 어떻게 다룰지”류의 디테일은 구현·버전에 민감하므로, 논쟁이 되는 파일은 팀 합의 후 예외 경로(overrides) 로 빼는 것이 비용 대비 효과가 좋습니다.

2.5 증분 분석: 데몬·CLI 변경분·에디터 세션

“증분(incremental)”은 한 가지 기술 이름이라기보다, 다시 전부 읽지 않도록 만드는 여러 장치의 총칭으로 이해하는 편이 맞습니다.

데몬(daemon): Biome은 장기 실행 서버를 띄워 에디터·CLI 요청을 처리하는 서버–클라이언트 구조를 취합니다. 워크스페이스 인덱스와 세션 상태를 메모리에 유지할 수 있어, 반복 편집에서 고정 비용(amortized cost) 을 줄이는 데 유리합니다.
CLI의 변경분 옵션: CI에서는 --changed·--since 등(정확한 플래그는 biome ci --help 기준)으로 베이스 브랜치 대비 차이만 검사해 시간을 줄입니다. 이는 “파일 단위 캐시”라기보다 검사 대상 집합을 줄이는 층에 가깝습니다.
스캐너 타깃팅: 앞서 설명한 대로, 프로젝트 규칙이 꺼져 있으면 세션에 필요한 폴더 위주로만 중첩 설정·ignore를 조사합니다. 거대 모노레포에서 “왜 이 패키지에서만 빠르다/느리다”를 설명할 때 자주 등장합니다.

증분과 최적화는 결정적(deterministic) 린트 결과와 트레이드오프가 될 수 있으므로, CI에서는 동일 커밋에 대해 로컬과 CI가 같은 파일 집합을 검사하는지(특히 변경분 검사 사용 시)를 점검하는 것이 좋습니다.

2.6 프로덕션에서 통하는 Biome 패턴

내부 구조를 알면, 운영 규칙이 자연스럽게 정리됩니다.

바이너리 단일화: package.json·lockfile·CI·IDE가 동일 @biomejs/biome 버전을 가리키게 하여, 파서·규칙 세트·포맷 IR 해석의 분기를 없앱니다.
데몬과 CI의 역할 분리: 로컬은 LSP·데몬으로 빠른 피드백, CI는 biome ci 로 읽기 전용·결정적 검증. CI에서 포맷을 쓰기(--write)하지 않습니다.
프로젝트 도메인 규칙은 신중하게: package.json 인덱싱 등 스캔 범위가 넓어지는 규칙은 대규모 저장소에서 비용이 커질 수 있습니다. 필요할 때만 켜고, 그렇지 않으면 스캐너 최적화를 살리는 구성을 유지합니다.
Prettier 병행 금지: 동일 파일에 Prettier와 Biome 포매터를 동시에 적용하면 줄바꿈 전쟁이 납니다. 전환 기간에도 경로 단위로 한 도구만 선택합니다.
규칙 롤아웃: recommended에서 출발해 카테고리별로 확장하고, 소음이 큰 규칙은 overrides로 테스트·레거시 경로에만 적용합니다. “한 번에 전부 error”로 올리면 팀이 off로 되돌리기 쉽습니다.
대용량·생성 코드 제외: CST 기반이라도 불필요한 거대 파일은 비용이 듭니다. files·VCS ignore·경로 예외로 분석 입력 자체를 줄입니다.

이후 절에서는 위 원리를 바탕으로, 설치·biome.json·마이그레이션·에디터·CI·모노레포 설정을 실제 명령과 옵션으로 연결합니다.

3. 설치 및 초기화

프로젝트 루트에서 개발 의존성으로 설치합니다. 버전 고정을 위해 --save-exact를 권장합니다.

npm install --save-dev --save-exact @biomejs/biome
npx @biomejs/biome init

init은 기본 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에서는 수정 없이 검증만 하는 편이 안전합니다.

4. `biome.json` 설정 작성

4.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을 가리키면 로컬 스키마로 자동완성할 수 있습니다.

4.2 린터 규칙과 심각도

linter.rules 아래에는 style, suspicious, correctness 등 카테고리별 규칙이 배치됩니다. 팀 합의 하에 특정 규칙을 error·warn·off로 조정합니다. “Prettier와 동일한 스타일”을 우선한다면 포매터 옵션을 먼저 맞추고, 린트는 점진적으로 강화하는 방식이 충돌이 적습니다.

4.3 VCS 연동(`.gitignore` 존중)

ESLint·Prettier가 Git이 무시하는 파일을 건너뛰는 것과 유사하게, Biome도 vcs 설정을 통해 버전 관리 클라이언트와 통합할 수 있습니다. 저장소 루트에 biome.json이 있다면, vcs.useIgnoreFile 등을 켜서 불필요한 파일을 분석 대상에서 제외하는 구성이 일반적입니다. CI에서도 동일한 무시 규칙이 적용되어야 로컬과 결과가 일치합니다.

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

4.4 `overrides`로 경로별 규칙

테스트 코드, 스크립트, 레거시 폴더에만 다른 규칙을 적용하려면 overrides에 include 패턴을 지정합니다. ESLint의 overrides와 같은 역할로 이해하면 됩니다.

{
  "overrides": [
    {
      "include": ["**/*.test.ts", "**/__tests__/**"],
      "linter": {
        "rules": {
          "suspicious": {
            "noExplicitAny": "off"
          }
        }
      }
    }
  ]
}

5. ESLint·Prettier에서 마이그레이션

5.1 자동 마이그레이션 명령

Biome은 기존 설정을 읽어 biome.json으로 옮기는 서브커맨드를 제공합니다.

npx @biomejs/biome migrate eslint --write
npx @biomejs/biome migrate prettier --write

migrate 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 옵션을 검토합니다(프로젝트 규모에 따라 노이즈가 늘 수 있습니다).

5.2 마이그레이션 후 꼭 할 일

biome check로 전체 저장소를 돌려 오류·경고 목록을 확보합니다.
ESLint 주석(eslint-disable)에 의존하던 부분은 Biome 규칙 ID 기준으로 정리합니다. 주석 체계가 다르므로, 숨겨 두었던 기술 부채가 드러날 수 있습니다.
CI에서 biome ci로 최종 검증합니다.
팀 문서(기여 가이드)의 명령어·에디터 설정을 Biome 기준으로 갱신합니다.

일부 팀은 전환 기간에 ESLint를 병행하기도 하지만, 규칙이 두 벌이면 개발자 혼란이 커집니다. 가능하면 단일 도구로 수렴하는 일정을 잡는 것이 좋습니다.

6. VS Code 통합

공식 확장 Biome(biomejs.biome)을 설치합니다. Visual Studio Code Marketplace 또는 Open VSX(VSCodium 등)에서 받을 수 있습니다.

6.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에서 명시적으로 적용하는 전략을 씁니다.

6.2 자주 쓰는 설정

biome.requireConfiguration: true로 두면 biome.json이 있을 때만 포맷·진단을 등록해, 엉뚱한 폴더에서 확장이 개입하는 것을 막을 수 있습니다.
biome.lsp.bin: 모노레포에서 특정 패키지의 Biome 바이너리를 가리킬 때 유용합니다.

멀티 루트 워크스페이스에서는 폴더마다 Biome 인스턴스가 생기므로, 각 패키지에 biome.json을 두는 모노레포 구조와 잘 맞습니다.

7. JetBrains 통합(WebStorm 등)

Biome 팀은 IntelliJ 계열용 플러그인(biomejs/biome-intellij)을 제공합니다. JetBrains Marketplace에서 “Biome”을 검색해 설치합니다. WebStorm 등 최신 IDE 버전과의 호환 범위는 플러그인 페이지의 릴리스 노트를 확인하세요.

7.1 동작 방식과 설정 요지

플러그인은 프로젝트 로컬의 node_modules에 설치된 biome을 우선 탐지하는 방식이 일반적입니다. 팀원마다 전역 설치에 의존하지 않도록, @biomejs/biome를 devDependencies에 고정해 두는 것이 중요합니다.

설정에서 LSP 기반 포맷을 활성화해야 포맷터로 일관되게 동작하는 경우가 많습니다. 저장 시 자동 수정을 켜려면 IDE의 “저장 시 액션” 또는 플러그인 옵션을 함께 조정합니다. VS Code와 마찬가지로 CLI와 IDE의 Biome 버전 불일치가 가장 흔한 불일치 원인이므로, 버전을 레포에서 통일합니다.

8. CI/CD 파이프라인 구성

8.1 `biome ci`를 쓰는 이유

CI에서는 파일을 수정하면 안 되므로 biome ci가 적합합니다. 포맷터·린터·임포트 정리를 읽기 전용으로 실행하며, 문제가 있으면 비제로 종료되어 파이프라인이 실패합니다.

npx @biomejs/biome ci .

8.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 .

8.3 변경 분만 검사하기

대규모 저장소에서는 PR에 포함된 변경 파일만 검사해 시간을 줄일 수 있습니다. Biome CLI의 --changed 또는 --since 계열 옵션을 사용하면, 기본 브랜치 대비 차이만 대상으로 삼을 수 있습니다. 정확한 플래그 이름과 동작은 사용 중인 Biome 버전의 biome ci --help를 기준으로 삼으세요.

캐시 전략으로는 node_modules 캐시, 또는 Biome 바이너리 설치 캐시를 활용하는 방법이 있습니다. 팀에서는 로컬 npm run check와 CI biome ci가 같은 버전을 쓰는지 먼저 확인하는 것이 좋습니다.

9. 모노레포 지원

Biome v2 이후 모노레포를 공식적으로 고려한 설정 모델이 정리되었습니다. 핵심은 루트 biome.json을 기준(base)으로 두고, 패키지별로 세부 설정을 중첩하는 것입니다.

9.1 루트와 패키지별 설정

루트에 공통 규칙·포맷 폭을 정의합니다.

{
  "formatter": { "lineWidth": 100, "indentStyle": "space", "indentWidth": 2 },
  "linter": { "enabled": true, "rules": { "recommended": true } }
}

특정 패키지(packages/logger 등)에만 다른 규칙을 주려면 해당 폴더에 biome.json을 두고, 루트 설정을 상속합니다. 공식 문서에서는 "extends": "//" 마이크로문법으로 루트 구성을 물려받는 패턴이 소개됩니다. 코드 생성물 폴더처럼 포맷을 끄고 싶다면 해당 패키지에서 formatter.enabled를 false로 두는 식으로 조정합니다.

9.2 `extends`로 공통 파일·npm 패키지 공유

팀 내부 공통 규칙을 common.json으로 두고 여러 앱에서 extends로 불러올 수 있습니다. 더 나아가 npm 패키지의 exports에 Biome 설정을 노출해 @org/shared-configs/biome 형태로 재사용하는 방법도 지원됩니다. 이때 패키지가 node_modules에 올바르게 설치되어 있어야 하며, 해석 기준은 실행 위치(워킹 디렉터리)에 따릅니다.

9.3 실행 위치와 탐색 규칙

Biome은 가장 가까운 biome.json을 파일 경로 쪽에서 탐색합니다. 루트에서 한 번에 전체를 돌릴지, 패키지별로 스크립트를 둘지는 팀 워크플로에 맞게 선택합니다. 루트에서 통합 실행 시에는 각 패키지의 중첩 설정이 기대대로 적용되는지 샘플 PR로 검증하는 것이 좋습니다.

10. 트러블슈팅과 운영 팁

버전 불일치: 로컬·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 연동으로 제외합니다.

11. 정리

Biome은 린트·포맷·임포트 정리를 한 엔진으로 묶어 개발자 피드백 루프와 CI 시간을 줄이는 데 초점을 맞춘 도구입니다. 내부적으로는 Rust 파서가 CST를 유지하고, 규칙·포매터가 동일 트리 모델을 공유하며, 스캐너·데몬·변경분 검사가 대규모 저장소에서의 실행 비용을 줄이는 방향으로 맞물립니다. biome.json으로 표준을 고정하고, biome migrate로 기존 ESLint·Prettier 설정을 이전한 뒤, biome ci로 파이프라인을 잠그는 흐름이 실무에서 가장 많이 쓰입니다. 모노레포에서는 루트·패키지 중첩 설정과 extends를 활용해 팀·제품 단위로 유연성을 확보할 수 있습니다.

도입 여부를 결정할 때는 “Biome 규칙 집합이 우리 팀의 코딩 표준을 얼마나 커버하는가”와 “남은 ESLint 플러그인 요구를 대체할 수 있는가”를 기준으로 평가하면 됩니다. 점진적 전환이 필요하면 짧은 스프린트로 마이그레이션·교육·문서화를 묶어 진행하는 것을 권장합니다.

내부 동작과 핵심 메커니즘

이 글의 주제는 「Biome 완벽 가이드 — 초고속 린터·포매터」입니다. 앞선 튜토리얼을 구현·런타임 관점에서 다시 압축합니다. 시스템·런타임 경계(스케줄링, I/O, 메모리, 동시성)를 기준으로 “입력이 어디서 검증되고, 핵심 연산이 어디서 일어나며, 부작용(I/O·네트워크·디스크)·동시성이 어디서 터지는가”를 한 장면으로 그리면 장애 분석이 빨라집니다.

처리 파이프라인(개념도)

flowchart TD
  A[입력·요청·이벤트] --> B[파싱·검증·디코딩]
  B --> C[핵심 연산·상태 전이]
  C --> D[부작용: I/O·네트워크·동시성]
  D --> E[결과·관측·저장]

경계에서의 지연·실패(시퀀스 관점)

sequenceDiagram
  participant C as 클라이언트/호출자
  participant B as 경계(프로세스·런타임·게이트웨이)
  participant D as 의존성(외부 API·DB·큐)
  C->>B: 요청/이벤트
  B->>D: 조회·쓰기·RPC
  D-->>B: 지연·부분 실패·재시도 가능
  B-->>C: 응답 또는 오류(코드·상관 ID)

알고리즘·프로토콜·리소스 관점 체크포인트

불변 조건(Invariant): 각 단계가 만족해야 하는 조건(버퍼 경계, 프로토콜 상태, 트랜잭션 격리, 파일 디스크립터 상한)을 문장으로 적어 두면 디버깅 비용이 줄어듭니다.
결정성: 동일 입력에 동일 출력이 보장되는 순수 층과, 시간·네트워크·스레드 스케줄에 의해 달라질 수 있는 층을 분리해야 테스트와 장애 분석이 쉬워집니다.
경계 비용: 직렬화/역직렬화, 문자 인코딩, syscall 횟수, 락 경합, GC·할당, 캐시 미스처럼 누적 비용을 의심 목록에 넣습니다.
백프레셔: 생산자가 소비자보다 빠를 때(소켓 버퍼, 큐 깊이, 스트림) 어디서 어떤 신호로 속도를 줄일지 정의합니다.

프로덕션 운영 패턴

실서비스에서는 기능과 함께 관측·배포·보안·비용·규제가 동시에 요구됩니다.

영역	운영 관점 질문
관측성	요청 단위 상관 ID, 에러율/지연 분위수(p95/p99), 의존성 타임아웃·재시도가 대시보드에 보이는가
안전성	입력 검증·권한·비밀·감사 로그가 코드 경로마다 일관적인가
신뢰성	재시도는 멱등 연산에만 적용되는가, 서킷 브레이커·백오프·DLQ가 있는가
성능	캐시 계층·배치 크기·커넥션 풀·인덱스·백프레셔가 데이터 규모에 맞는가
배포	롤백 룬북, 카나리/블루그린, 마이그레이션 호환성·플래그가 문서화되어 있는가
용량	피크 트래픽·디스크·파일 디스크립터·스레드 풀 상한을 주기적으로 검증하는가

스테이징은 데이터 양·네트워크 RTT·동시성을 가능한 한 프로덕션에 가깝게 맞추는 것이 재현율을 높입니다.

확장 예시: 엔드투엔드 미니 시나리오

「Biome 완벽 가이드 — 초고속 린터·포매터」을 실제 배포·운영 흐름으로 옮긴 체크리스트형 시나리오입니다. 도메인에 맞게 단계 이름만 바꿔 적용할 수 있습니다.

입력 계약 고정: 스키마·버전·최대 페이로드·타임아웃·에러 코드 표를 API 또는 이벤트 경계에 둔다.
핵심 경로 계측: 요청 ID, 단계별 지연, 외부 호출 결과 코드를 한 화면(로그+메트릭+트레이스)에서 추적한다.
실패 주입: 의존성 타임아웃·5xx·부분 데이터·락 대기를 스테이징에서 재현한다.
호환·롤백: 설정/마이그레이션/클라이언트 버전을 되돌릴 수 있는지(또는 피처 플래그) 확인한다.
부하 후 검증: 피크 대비 p95/p99, 에러율, 리소스 상한, 알림 임계값이 기대 범위인지 본다.

의사코드 스케치(프레임워크 무관)

handle(request):
  ctx = newCorrelationId()
  validated = validateSchema(request)        // 경계에서 거절
  authorize(validated, ctx)                  // 권한·테넌트
  result = domainCore(validated)             // 순수에 가까운 규칙
  persistOrEmit(result, idempotentKey)       // I/O: 멱등·재시도 정책
  recordMetrics(ctx, latency, outcome)
  return result

문제 해결(Troubleshooting)

증상	가능 원인	조치
간헐적 실패	레이스, 타임아웃, 외부 의존성 불안정, DNS	최소 재현 스크립트, 분산 트레이스·로그 상관관계, 재시도·서킷 설정 점검
성능 저하	N+1, 동기 I/O, 락 경합, 과도한 직렬화, 캐시 미스	프로파일러·APM으로 핫스팟 확인 후 한 가지씩 제거
메모리 증가	캐시 무제한, 구독/리스너 누수, 대용량 버퍼, 커넥션 미반납	상한·TTL·힙/FD 스냅샷 비교
빌드·배포만 실패	환경 변수, 권한, 플랫폼 차이, lockfile	CI 로그와 로컬 diff, 런타임·이미지 버전 핀
설정이 로컬과 다름	프로필·시크릿·기본값, 지역 리전	단일 소스(예: 스키마 검증된 설정)와 배포 매트릭스 표준화
데이터 불일치	비멱등 재시도, 부분 쓰기, 캐시 무효화 누락	멱등 키·아웃박스·트랜잭션 경계 재검토

권장 순서: (1) 최소 재현 (2) 최근 변경 범위 축소 (3) 환경·의존성 차이 (4) 관측으로 가설 검증 (5) 수정 후 회귀·부하 테스트.

자주 묻는 질문 (FAQ)

Q. 이 내용을 실무에서 언제 쓰나요?

A. Biome 실무 가이드: Rust 파서·CST·규칙 엔진·포매터 IR까지 내부 구조를 짚고, biome.json·마이그레이션·에디터·CI·모노레포·프로덕션 패턴을 정리합니다. 실무에서는 위 본문의 예제와 선택 가이드를 참고해 적용하면 됩니다.

Q. 선행으로 읽으면 좋은 글은?

A. 각 글 하단의 이전 글 또는 관련 글 링크를 따라가면 순서대로 배울 수 있습니다. C++ 시리즈 목차에서 전체 흐름을 확인할 수 있습니다.

Q. 더 깊이 공부하려면?

A. cppreference와 해당 라이브러리 공식 문서를 참고하세요. 글 말미의 참고 자료 링크도 활용하면 좋습니다.

이 글에서 다루는 키워드 (관련 검색어)

Biome, Linter, Formatter, ESLint, Prettier, Rust, CST 등으로 검색하시면 이 글이 도움이 됩니다.

이 글이 도움이 되셨나요?

여러분의 피드백은 더 나은 콘텐츠를 만드는 데 도움이 됩니다

문제가 있거나 개선 제안이 있으시면 연락처로 알려주세요.

Keyboard Shortcuts

이 글의 핵심

이 글의 핵심

1. Biome이란 무엇인가

1.1 핵심 개념

1.2 ESLint·Prettier 대비 장점

2. 내부 아키텍처: 파서·분석기·포매터·증분 실행

2.1 Rust 기반 파서와 CST(rowan)·오류 허용 파싱

2.2 스캐너·프로젝트 메타데이터와 린트의 입력

2.3 AST·구문 노드 순회와 규칙 엔진

2.4 포매터 알고리즘과 Prettier 호환 철학

2.5 증분 분석: 데몬·CLI 변경분·에디터 세션

2.6 프로덕션에서 통하는 Biome 패턴

3. 설치 및 초기화

4. biome.json 설정 작성

4.1 최소 구성 예시

4.2 린터 규칙과 심각도

4.3 VCS 연동(.gitignore 존중)

4.4 overrides로 경로별 규칙

5. ESLint·Prettier에서 마이그레이션

5.1 자동 마이그레이션 명령

5.2 마이그레이션 후 꼭 할 일

6. VS Code 통합

6.1 저장 시 포맷·안전 수정·임포트 정리

6.2 자주 쓰는 설정

7. JetBrains 통합(WebStorm 등)

7.1 동작 방식과 설정 요지

8. CI/CD 파이프라인 구성

8.1 biome ci를 쓰는 이유

8.2 GitHub Actions 예시

8.3 변경 분만 검사하기

9. 모노레포 지원

9.1 루트와 패키지별 설정

9.2 extends로 공통 파일·npm 패키지 공유

9.3 실행 위치와 탐색 규칙

10. 트러블슈팅과 운영 팁

11. 정리

내부 동작과 핵심 메커니즘

처리 파이프라인(개념도)

경계에서의 지연·실패(시퀀스 관점)

알고리즘·프로토콜·리소스 관점 체크포인트

프로덕션 운영 패턴

확장 예시: 엔드투엔드 미니 시나리오

의사코드 스케치(프레임워크 무관)

문제 해결(Troubleshooting)

자주 묻는 질문 (FAQ)

Q. 이 내용을 실무에서 언제 쓰나요?

Q. 선행으로 읽으면 좋은 글은?

Q. 더 깊이 공부하려면?

이 글에서 다루는 키워드 (관련 검색어)

이 글이 도움이 되셨나요?

4. `biome.json` 설정 작성

4.3 VCS 연동(`.gitignore` 존중)

4.4 `overrides`로 경로별 규칙

8.1 `biome ci`를 쓰는 이유

9.2 `extends`로 공통 파일·npm 패키지 공유