React Doctor: React 코드베이스에 필요한 누락된 건강 검진 도구일까?

만약 지저분한 React 코드베이스를 물려받았거나, 단순히 자신의 프로젝트가 시간이 지나면서 나쁜 패턴으로 변질되었는지 궁금해했다면, React Doctor는 알아둘 만한 가치가 있는 도구입니다. 하나의 명령어와 0점에서 100점 사이의 점수, 그리고 수정해야 할 문제 목록이 제공됩니다. 이것이 이 도구의 핵심입니다. 실제로 기대에 부응하는지 깊이 파헤쳐 보겠습니다.

React Doctor란 무엇인가요?

React Doctor는 Million.js 팀에서 만든 오픈 소스 CLI(Command Line Interface) 도구입니다. 이 도구는 React 프로젝트를 스캔하여 건강 점수와 구조화된 문제 목록을 함께 제공합니다. 이는 일반적인 JavaScript 규칙뿐만 아니라 React 패턴을 특별히 이해하는, 일종의 '슈퍼린터'라고 생각할 수 있습니다.

npx -y react-doctor@latest .

이것이 실행하는 데 필요한 전부입니다. 설치나 설정 파일이 필요하지 않습니다.

작동 원리 (How It Works Under the Hood)

React Doctor를 프로젝트에 실행하면 두 가지 작업을 병렬로 수행합니다.

1. 린트 패스 (Lint pass)

이것은 다음 범주별로 정리된 60개 이상의 규칙을 확인합니다: 상태 및 효과(state and effects), 성능(performance), 아키텍처(architecture), 번들 크기(bundle size), 보안(security), 정확성(correctness), 접근성(accessibility), 그리고 프레임워크별 관심사(Next.js, React Native)입니다. 중요한 점은 이 도구가 프로젝트의 프레임워크, React 버전, 컴파일러 설정을 자동으로 감지하고 그에 따라 규칙을 전환한다는 것입니다. 따라서 Next.js를 사용한다면, 아무것도 설정할 필요 없이 Next.js 전용 규칙이 적용됩니다.

2. 데드 코드 탐지 (Dead code detection)

사용되지 않는 파일, 사용되지 않는 내보내기(unused exports), 사용되지 않는 타입, 그리고 전체 코드베이스의 중복을 찾기 위해 별도의 패스를 실행합니다.

두 패스가 모두 완료된 후, 설정한 모든 구성(config)을 통해 결과를 필터링하고 심각도에 따라 가중치가 적용된 점수를 계산합니다: 75점 이상 : Great 50점에서 74점 : Needs work 50점 미만 : Critical 오류는 경고보다 더 큰 비중을 차지하므로, 단 하나의 심각한 문제만으로도 수많은 사소한 문제들보다 점수를 크게 떨어뜨립니다. 상세 출력 보기 기본적으로 요약본이 제공됩니다. --verbose를 추가하면 관련된 정확한 파일과 라인 번호를 볼 수 있습니다: npx -y react-doctor@latest . --verbose 이 모드는 실제로 수정 작업을 할 때 필요한 방식입니다. 왜냐하면 요약만으로는 어디를 살펴봐야 하는지 알려주지 않기 때문입니다.

실제 프로젝트 점수 인기 있는 오픈 소스 React 프로젝트에 대한 스캔 리더보드를 저장소에 포함하고 있습니다. 여기 스냅샷이 있습니다:

Project	Score
tldraw	84
excalidraw	84
twenty	78
plane	78
formbricks	75
posthog	72
supabase	69
payload	68
sentry	64
cal.com	63
dub	62

심지어 tldraw와 excalidraw — 숙련된 팀이 유지 관리하는 프로젝트 —도 100점이 아닌 중반 80점대를 기록합니다. 이는 유용한 기준점(calibration)입니다. 완벽한 점수를 기대해서는 안 됩니다. 목표는 특정 프로젝트에서 실제로 중요한 것이 무엇인지 식별하는 것입니다.

CI에 통합하기 GitHub Actions를 사용하여 React Doctor가 모든 워크플로우에 추가할 수 있는 GitHub Action을 제공합니다:

• uses: actions/checkout@v5
  with: fetch-depth: 0
• uses: millionco/react-doctor@main
  with: diff: main
  github-token: ${{ secrets.GITHUB_TOKEN }}

diff 옵션은 특히 유용합니다. 이 옵션은 기본 브랜치(base branch)와 비교하여 변경된 파일만 스캔하도록 액션에 지시합니다.

이는 풀 리퀘스트(PR)의 경우, 전체 저장소(repo)에 존재하는 기존 문제가 아닌, 해당 PR이 도입한 새로운 문제만을 플래그 지정한다는 의미입니다. 또한 github-token을 설정하면 액션은 발견된 사항들을 PR 코멘트로 게시합니다. 이 액션은 후속 단계에서 사용할 수 있는 점수 값(score value)을 출력하며—예를 들어, PR로 인해 점수가 사용자가 정의한 임계값 이하로 떨어지면 빌드를 실패시킬 수 있습니다. 설정 파일 프로젝트 루트에 react-doctor.config.json 파일을 통해 특정 규칙을 무시하거나 파일을 제외할 수 있습니다: json { "ignore" : {"rules" : [ "react/no-danger" , "jsx-a11y/no-autofocus" ], "files" : [ "src/generated/**" ] } } 또는, 다른 설정 파일을 추가하는 것이 꺼려진다면 package.json 내의 `

AI 코딩 에이전트에게 React 모범 사례를 가르치기: 간과하기 쉬운 기능 중 하나는 React Doctor가 코딩 에이전트에 '스킬'을 설치할 수 있다는 것입니다. Cursor, Claude Code, Windsurf, Copilot 등 여러 도구가 지원됩니다: curl -fsSL https://react.doctor/install-skill.sh | bash 이렇게 하면 에이전트에게 47가지 이상의 React 모범 사례 규칙을 가르쳐서, 코드를 작성한 후에 문제가 발생하는 것이 아니라 능동적으로 문제를 포착할 수 있게 됩니다. 프로젝트에 추가할 가치가 있을까요? 솔직한 평가를 해드리겠습니다. 진정으로 도움이 되는 경우: 레거시 코드베이스 온보딩(Onboarding). 한 번 실행하면 카테고리별로 가장 큰 문제점들의 지도를 즉시 얻을 수 있습니다. 팀 전체의 표준 강제화. diff 모드를 지원하는 CI 통합 덕분에, 아무도 알아차리지 못하게 새로운 안티패턴이 도입된 PR은 없습니다. 데드 코드(Dead code). 대부분의 린터는 프로젝트 전체에 걸친 사용되지 않은 파일과 내보내기(exports)를 포착하지 못합니다. React Doctor는 이를 기본적으로 수행합니다. 프레임워크별 규칙. Next.js를 사용한다면, 일반적인 린터로는 많은 것을 놓칩니다. React Doctor는 Next.js 패턴에 대해 알고 적절하게 플래그 지정합니다. 기대치를 조절해야 하는 경우: 잘 구성된 ESLint 설정의 대체재가 아닙니다. 보완재입니다. 이미 엄격한 ESLint 규칙이 있다면, 일부 중복은 불가피합니다. 점수는 정확한 측정 기준이 아니라 대략적인 가이드일 뿐입니다. 72점과 75점의 차이가 큰 의미를 갖지는 않습니다. 숫자가 아닌 특정 진단에 집중하세요. 비교적 새롭습니다 (여전히 활발하게 개발 중이며 열린 이슈와 PR이 있습니다).

일부 규칙은 노이즈가 심하거나 컨텍스트 의존적일 수 있기 때문에 config ignore 리스트가 존재합니다. --fix 플래그는 AI 에이전트(Ami)에게 문제를 자동 수정하도록 맡깁니다. 이 부분은 더 실험적이며 외부 도구에 의존합니다. 결론적으로, 지금 당장 프로젝트에서 npx -y react-doctor@latest . --verbose를 실행했는데 아무것도 놀라운 것이 없다면, 아마도 필요하지 않았을 것입니다. 하지만 사용되지 않는 export 50개, 리스트 내 키가 누락된 컴포넌트 3개, 그리고 깜빡하고 놓친 useEffect 의존성 문제가 몇 가지 발견된다면, 그것은 그렇지 않았다면 찾지 못했을 기술 부채 정리 아침이 될 것입니다. CI(Continuous Integration) 사용 사례만으로도 — 설정 없이 PR에서 React 관련 회귀를 자동으로 플래그 지정하는 것만으로 — 프론트엔드 워크플로우에서 그 자리를 얻습니다. 60초 만에 시작하기 # 프로젝트에 실행하기 npx -y react-doctor@latest . --verbose # 워크스페이스를 사용하는 경우, 특정 패키지 선택하기 npx -y react-doctor@latest . --project my-app # main 대비 변경된 파일만 스캔하기 npx -y react-doctor@latest . --diff main # 점수만 출력하기 (스크립트에 유용함) `npx -y react-doctor@latest . --score GitHub 레포는 github.com/millionco/react-doctor에 있습니다.