팀에 맞는 ESLint, Prettier 설정을 찾고 검사 자동화
팀이 빠르게 성장할 수 있도록 린터와 포매터 플러그인을 적극 도입하고, Lint-staged와 Husky로 pre-commit 단계에서 검사를 자동화해 휴먼 에러를 줄인 경험을 정리했습니다.
팀에 맞는 ESLint, Prettier 설정 만들기
ESLint: 팀 합의에 기반하여 코드 품질을 높이는 방향으로 설정
프로젝트 초기에 개발 환경을 구축하며 ESLint와 Prettier 설정을 맡은 적이 있습니다. ESLint 설정을 엄격하게 적용해 프로젝트 전체 코드 품질을 끌어올리려고, 기본적인 React 권장 설정에 더해 airbnb 플러그인을 적용했습니다. 그런데 린트 에러 처리에 시간이 오래 걸리자, 빠른 해결을 위한 타협으로 코드베이스에 disable 주석이 쌓이기 시작했습니다. 게다가 린트 에러를 끝까지 해결하지 못해 일부 규칙을 끄기 시작하면서 ESLint를 꼭 써야 하나?라는 의견까지 나왔습니다. 결국 ESLint 설정을 최소화해 개발 속도를 높이자는 의견에 따라 일부 플러그인을 아예 제거했습니다.
이후 팀의 숙련도가 오르며 코드 품질을 더 고민하게 되고, 코드 스타일 통일의 필요성도 커지면서, 널리 쓰이는 플러그인을 단계적으로 추가해 ESLint 규칙을 다시 엄격하게 조정했습니다. 최종적으로 아래 조합으로 설정을 확정했습니다.
eslint-plugin-import-x: ESM import 경로 오류를 조기에 잡는 규칙 세트eslint-plugin-unicorn: 안전한 자바스크립트 패턴과 일관된 스타일을 강제하는 모음eslint-plugin-sonarjs: 복잡도, 중복 코드, 잠재 버그 패턴을 탐지@typescript-eslint: 타입 정보를 활용해 JS 규칙을 타입 안전하게 확장eslint-plugin-prettier: Prettier 포매팅을 ESLint 단계에서 강제로 적용하며 충돌을 방지@tanstack/eslint-plugin-query: React Query에서 훅 사용 시 권장 패턴 검증
React 환경
eslint-plugin-react: JSX/컴포넌트 패턴 일반 규칙eslint-plugin-react-hooks: Hooks 규칙eslint-plugin-react-refresh: 개발 중 HMR 관련 경고
Next.js 환경
eslint-config-next+eslint-config-next/core-web-vitals: Next.js 및 React 베스트 프랙티스와 웹 바이탈 최적화 권장 규칙
ESLint 설정을 엄격하게 조정하면서 좋았던 점은, 코드 스타일에 대한 고민을 줄이면서 팀의 코드 스타일을 통일할 수 있었다는 점입니다. 플러그인에서 권장하는 대로 코드를 작성하다 보니 점차 코드 스타일을 의논할 일이 줄었고, 코드 리뷰 시간도 단축할 수 있었습니다. 미처 지우지 못한 console.log()나 불필요한 주석을 잡아내기도 쉬워졌습니다. 팀 합의를 바탕으로, 팀의 성장 단계에 맞춰 엄격함의 수준을 조절하며 코드 품질을 개선해 나갈 수 있었습니다.
Prettier: 대규모 프로젝트를 벤치마킹하며 개발 편의성 증가
포매팅 규칙을 정하는 과정은 비교적 순조로웠습니다. es-toolkit 같은 국내 대규모 오픈소스 프로젝트를 참고해 엔터프라이즈 환경에 맞는 설정을 확정했습니다. 여기에 추가로 2개의 플러그인을 사용하며 개발 편의성도 함께 높였습니다.
@trivago/prettier-plugin-sort-imports: import 정렬을 자동화prettier-plugin-tailwindcss: 잘못된 Tailwind 클래스 조합을 개발 단계에서 바로 잡기
초반에는 팀원들의 VS Code 설정이 제각각이라 Prettier format on save가 제대로 작동하지 않기도 했습니다. .vscode 폴더를 만들어 공통 VS Code 설정을 강제할지 검토했지만, 단발성 문제로 판단해 우선 각자의 Prettier format on save 설정 문제를 해결하는 선에서 마무리했습니다.
운영 중 마주친 이슈와 해결 방법
PR Merge 후 ESLint 에러로 빌드 실패
간헐적으로 ESLint 에러를 수정하지 않은 채 main 브랜치에 merge되어, CI/CD 단계에서 빌드에 실패하는 문제가 발생했습니다. 원인은 로컬에서 린트 실행을 깜빡하는 휴먼 에러였습니다.
휴먼 에러를 검사 자동화로 해소
이 문제를 해결하기 위해 두 가지 방법을 고민했습니다. 첫 번째는 Lint-staged와 Husky를 사용해 pre-commit hook에서 staged된 파일에 ESLint 검사를 실행하는 방법입니다. 이 경우 ESLint 검사가 실패하면 commit 자체를 막을 수 있습니다. 두 번째는 GitHub Actions 워크플로우에서 PR 생성/수정 시 ESLint 검사를 실행해, 검사가 통과해야만 PR merge가 가능하도록 하는 방법이었습니다.
최종적으로는 Lint-staged와 Husky를 사용해 pre-commit 단계에서 ESLint 검사를 실행하는 방식을 선택했습니다. GitHub Actions만으로 해결할 경우, 매 PR이 생성될 때마다 ESLint 검사를 위한 전체 패키지 설치가 필요하고, 전체 프로젝트를 대상으로 검사가 수행돼 불필요한 작업이 반복되기 때문이었습니다. 변경된 파일에만 ESLint 검사를 실행하도록 해, 빠르고 가벼운 검사 자동화 프로세스를 구축하면서 빌드 실패 문제를 해소할 수 있었습니다.
참고
현재는 ESLint의 새로운 설정 방식인 flat config를 적용해 아래와 같이 사용하고 있습니다.