Skip to content

Start here

Getting started

Run rn-doctor against a React Native project in two minutes: one npx command, what the output means, and how exit codes map to CI.

rn-doctor needs nothing but Node >= 20 and a package.json. The package name and the binary name differ, so a one-off run uses --package:

npx --yes --package react-native-doctor-ci rn-doctor

For a repo that uses it regularly, install it and call the bin directly:

npm install --save-dev react-native-doctor-ci
npx rn-doctor

Reading the output

Each finding is a block: a severity badge, the package, what fired and why, and an evidence link (npm, the RN Directory, or GitHub) backing the claim. Warnings about missing data — say, GitHub fields skipped because there's no token — are listed separately from policy findings, because "we couldn't check" and "this is broken" are different statements.

The run ends with a summary line: packages checked, errors, warnings, notes.

Exit codes

The exit code contract is stable — CI can depend on it:

CodeMeaning
0Clean. Warnings, notes, and allowlisted findings do not fail the run.
1At least one unsuppressed policy error.
2Tool failure: bad flags, unreadable package.json, invalid policy file, git failure under --changed-only.

Scope and caching

By default only dependencies are checked (devDependencies never ship in your app), and only packages that actually couple to React Native — listed in the RN Directory, peer-depending on react-native, or shipping android/ios directories. Switch to everything with scope: all-deps in the policy file.

Enrichment results are cached in .rn-doctor-cache.json for 24 hours, so repeat runs are fast. Add it to .gitignore; --no-cache bypasses the cache entirely.

Set GITHUB_TOKEN to enable the GitHub checks (archived repo, last push). Without it those fields are unknown and reported as warnings — the run still completes.

Next: put it in CI with the GitHub Action.