TypeScript 7 & Next.js 16 환경에서 ESLint 대신 Biome(바이옴) 도입 후기
최근 프로젝트에서 TypeScript 7.0과 Next.js 16.3 버전 업그레이드를 진행하면서 기존 정적 분석 및 포맷팅 도구였던 ESLint 생태계와의 호환성 문제와 느린 실행 속도를 해결하기 위해 Rust 기반 초고속 툴체인인 Biome으로 도구를 교체했습니다.
그 과정에서 경험한 설정 노하우와 도입 후기를 공유합니다.
---
1. Biome을 도입하게 된 이유
최신 TypeScript 7 호환성: `@typescript-eslint` 패키지의 공식 지원을 기다리는 대신, 자체 파서로 TypeScript/TSX를 직접 분석하는 독립적인 도구가 필요했습니다.
통합 툴체인 (Linter + Formatter): ESLint와 Prettier를 조합하는 복잡한 플러그인 설정 없이 단일 바이너리로 린팅과 코드 포맷팅을 한 번에 처리할 수 있습니다.
압도적인 실행 속도: 100여 개가 넘는 프로젝트 파일의 정적 분석 및 포맷팅이 불과 30~40ms 만에 완료됩니다.
---
2. 프로젝트 설정 방법 (`biome.json`)
`npm install -D --save-exact @biomejs/biome` 설치 후 `npx biome init`을 실행하여 설정 파일을 생성합니다. Next.js 및 Tailwind CSS 프로젝트에 맞춘 실전 설정 팁입니다.
`biome.json` 핵심 설정
{
"$schema": "https://biomejs.dev/schemas/2.5.6/schema.json",
"vcs": {
"enabled": true,
"clientKind": "git",
"useIgnoreFile": true
},
"formatter": {
"enabled": true,
"indentStyle": "space",
"indentWidth": 2
},
"linter": {
"enabled": true,
"rules": {
"preset": "recommended",
"a11y": {
"recommended": false
},
"performance": {
"noImgElement": "off"
}
}
},
"javascript": {
"formatter": {
"quoteStyle": "double",
"semicolons": "asNeeded"
}
},
"css": {
"parser": {
"tailwindDirectives": true
}
}
}
주요 커스텀 옵션 포인트:
Tailwind CSS v4 지원: `css.parser.tailwindDirectives: true`를 추가하여 `@ theme`, `@ utility`, `@ apply` 지시어 파싱 오류를 방지했습니다.
Static Export 환경 예외 처리: Static Site Export(`output: 'export'`)를 사용하는 경우 dynamic image optimization이 불가능하므로 `performance.noImgElement: "off"`로 설정하여 `` 태그 관련 경고를 예외 처리했습니다.
세미콜론 안 붙이기 (Semi-less): `javascript.formatter.semicolons: "asNeeded"`로 필요 시에만 세미콜론을 붙이도록 설정했습니다.
---
3. NPM 스크립트 및 CI 연동
`package.json`에 다음 스크립트를 추가하여 간편하게 실행합니다:
`npm run lint` -> `biome check .`
`npm run lint:fix` -> `biome check --write .`
또한 GitHub Actions(`ci.yaml`)에 `npm run lint` 및 `npx tsc --noEmit` 검증 단계를 추가하여 모든 PR에 대해 정적 분석과 타입 검사를 자동으로 통과하도록 구축했습니다.
---
4. 결론
Biome으로 전환한 후 개발 환경이 훨씬 깔끔해졌고, 코드 체크 및 포맷팅 속도가 비약적으로 향상되었습니다. 최신 TypeScript/Next.js 프로젝트를 진행 중이라면 Biome 도입을 강력히 추천합니다!
