Cách dùng React Doctor để tìm lỗi react tự động

93 ngày, gần 10k sao. README của react-doctor chỉ có một câu: "agent của bạn viết React tệ, cái này xử đẹp". Không giới thiệu, không pitch. Câu đó là đủ.

Đây là công cụ mã nguồn mở do millionco phát hành, cùng tổ chức đứng sau Million.js và React Scan. Chức năng cốt lõi là quét toàn bộ codebase React rồi trả về điểm sức khỏe từ 0 tới 100. Trên 75 là tốt, từ 50 tới 74 là cần xem lại, dưới 50 là đang có vấn đề nghiêm trọng.

Vấn đề nó giải quyết thì ai làm React năm 2026 cũng gặp. Các AI coding agent như Claude Code, Cursor, Codex, Windsurf viết code nhanh đến mức không tưởng, nhưng chất lượng thì không có gì đảm bảo. useEffect bị dùng sai mục đích, state được tính toán lại thay vì derive từ state có sẵn, setState bị gọi bên trong quá trình render thay vì trong event handler, index của mảng bị dùng làm key trong danh sách JSX. Code chạy được, không báo lỗi đỏ, nhưng ẩn đầy lỗi tiềm tàng. Review tay không xuể vì agent ship nhanh hơn tốc độ người đọc.

Cách dùng thì đơn giản một cách kỳ lạ. Vào thư mục dự án, gõ:

npx -y react-doctor@latest .

Không cần cài trước, không cần file config. Tool tự nhận diện dự án đang chạy Next.js, Vite, Remix hay React Native, xác định phiên bản React và compiler đang dùng, rồi chạy song song hai bước phân tích. Bước một là lint với hơn 60 rule trải qua các nhóm: state và effects, hiệu năng, kiến trúc, bundle size, bảo mật, tính đúng đắn của logic, accessibility, và rule riêng cho từng khung như Next.js hay React Native. Bước hai là phát hiện code chết, tức là file, hàm, kiểu dữ liệu không còn được dùng tới đâu, kể cả các đoạn code trùng lặp. Kết quả in ra kèm đường dẫn dạng tên-file:số-dòng bấm thẳng vào VS Code. Thêm cờ --verbose nếu muốn xem chi tiết từng file.

Điểm được tính dựa trên mức độ nghiêm trọng của lỗi. Lỗi nặng trừ điểm nhiều hơn cảnh báo. Điểm cuối cùng phản ánh tổng thể bức tranh sức khỏe của codebase, không phải đếm thô số lần vi phạm. Tức là bạn có năm mươi chỗ cùng mắc một lỗi, sửa bốn mươi chín chỗ cũng không thay đổi điểm. Phải dập sạch hoàn toàn một loại lỗi thì mới rút được phần trừ tương ứng.

Tính năng thứ hai mới là lý do repo viral. Để dạy coding agent của bạn biết các rule React trước khi nó viết code, chạy lệnh:

curl -fsSL https://react.doctor/install-skill.sh | bash

Lệnh này hỏi bạn đang dùng agent nào, rồi tự tạo file rule tương ứng vào dự án: SKILL.md cho Claude Code, AGENTS.md cho Codex, .cursorrules cho Cursor, và tương tự với Windsurf, Gemini CLI, OpenCode, Amp Code. Agent đọc file đó sẽ biết cần tránh gì ngay từ lúc viết code thay vì đợi đến lúc lint mới phát hiện. Về bản chất đây là cách nhúng kiến thức về React anti-pattern vào bộ nhớ làm việc của agent.

Với team lớn, repo có sẵn một GitHub Action. Thêm vào file workflow:

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

Thế là mỗi pull request sẽ có bình luận tự động hiển thị điểm và danh sách lỗi mới so với nhánh chính. PR nào sinh thêm lỗi mới thì bị chặn. Bình luận đó cập nhật tại chỗ thay vì xóa rồi tạo lại khi có commit mới. Action cũng output điểm dưới dạng biến để dùng trong các bước tiếp theo của pipeline, ví dụ chặn merge nếu điểm tụt dưới ngưỡng.

Điểm khác biệt so với ESLint hay oxlint ở chỗ nào? ESLint kiểm tra style và quy ước viết code. react-doctor tập trung vào các anti-pattern React mà AI agent hay sinh ra mà ESLint không bắt hoặc bắt không đúng ngữ cảnh. Điểm tổng hợp 0 tới 100 cũng dễ dùng hơn để làm ngưỡng cứng trong CI. Cùng bộ rule còn được đóng gói thành package riêng để nhúng vào pipeline ESLint hoặc oxlint đang có, nên hai cách dùng không loại trừ nhau.

Vài điều cần biết trước khi đưa vào dùng thật. Phần tính điểm gọi API ngoài, nên môi trường CI không có mạng thì bỏ qua được bằng cờ --offline, nhưng lúc đó sẽ không có điểm. Mỗi phiên bản mới có thể bổ sung rule mới, điểm có thể tụt dù code không thay đổi gì, vì vậy nếu cần điểm ổn định thì nên ghim phiên bản cụ thể trong CI thay vì dùng @latest. Để tham khảo mức điểm thực tế, tldraw và excalidraw đang ở 84, supabase ở 69, sentry ở 64, cal.com ở 63.

Repo hiện chạy với 169 commit và đang phát triển rất nhanh, nhưng phần lớn commit vẫn tập trung ở một người duy nhất là aidenybai. Đây là điểm rủi ro cần tính đến nếu dự án phụ thuộc lâu dài vào tool này.