React Native Auditor

A local-first React Native & Expo project auditor for release readiness, dependency health, and risk reports.

Audit React Native and Expo projects before release issues waste your time.

Quick start

Start React Native Auditor in guided mode:

npx react-native-auditor

The guided menu is the easiest way to explore common actions in a React Native or Expo project.

You can also run commands directly:

npx react-native-auditor audit
npx react-native-auditor audit --fix
npx react-native-auditor audit --fix --interactive
npx react-native-auditor report --html
npx react-native-auditor report --json

Guided CLI Menu

Running React Native Auditor without a subcommand opens a keyboard-driven guided menu in interactive terminals:

rn-auditor

From the menu, you can:

• Run an audit
• Preview safe fixes
• Apply safe fixes interactively
• Generate an HTML report
• Generate a JSON report

Guided mode is an onboarding and discovery layer. It does not replace direct CLI commands.

Direct commands remain the recommended interface for CI, scripts, repeatable checks, and advanced workflows:

rn-auditor audit --fail-on warning
rn-auditor report --json --fail-on error

CI quality gates

Use --fail-on <info|warning|error|none> when CI should fail based on reported issue severity:

rn-auditor audit --fail-on error
rn-auditor audit --fail-on warning
rn-auditor audit --fail-on info
rn-auditor audit --fail-on none
rn-auditor scan --fail-on error
rn-auditor report --json --fail-on error
rn-auditor report --html --fail-on error

Threshold behavior:

• error fails when at least one Error issue is reported.
• warning fails when at least one Warning or Error issue is reported.
• info fails when any Info, Warning, or Error issue is reported.
• none never fails because of reported issues.

If --fail-on is omitted, React Native Auditor keeps its default exit behavior.

Example GitHub Actions workflow:

name: React Native Auditor

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  audit:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run React Native Auditor
        run: npx react-native-auditor audit --fail-on warning

What it does

React Native Auditor uses conservative static checks to:

• Detect Expo, React Native, and unknown project types.
• Detect the package manager and conflicting root lockfiles.
• Check Expo and EAS release-readiness configuration.
• Find missing environment variable documentation.
• Flag a common Reanimated and Babel setup risk.
• Generate readable terminal output and a local static HTML report.

Fixes

rn-auditor audit --fix prints safe fix suggestions as a preview and does not modify files.

rn-auditor audit --fix --interactive asks before applying each safe fix. React Native Auditor only applies conservative fixes that can be safely reviewed before writing. For environment files, values are never copied and existing files are not overwritten.

rn-auditor scan --fix and rn-auditor scan --fix --interactive behave the same way because scan is an alias for audit.

Why React Native Auditor

react-native doctor is useful for checking the development environment. React Native Auditor has a different scope: it audits project-level files for dependency, configuration, and release-readiness risks.

• Project-focused: inspects the repository state that travels with the app.
• Local-first: project data stays on the machine running the audit.
• Static by default: reads selected files without running the target project.
• Native CLI: the npm package launches a bundled Rust binary for fast, predictable execution.
• No service dependency: no account, dashboard, or SaaS connection is required.

React Native Auditor is intentionally focused. It does not replace React Native Doctor, Expo Doctor, platform build validation, or a real release build.

Example output

React Native Auditor

Scanning path:
  /work/mobile-app

Project summary:
  Project type: Expo
  Package manager: Multiple / Ambiguous

Issues:
  [Warning] RNA_LOCKFILE_001 - Multiple lockfiles detected
      Multiple package manager lockfiles were found.
  [Warning] RNA_ENV_001 - Missing .env.example
      This project uses a .env file but does not document required variables.

Output varies by project. This example is shortened for readability.

Current Checks

Project detection

• Detects Expo, React Native, and unknown project types from package.json.
• Reports a missing or invalid package.json.
• Accepts the current directory or an explicit project path.

Dependency and lockfile health

• Detects npm, Yarn, pnpm, and Bun from root lockfiles.
• Reports multiple package manager lockfiles as an ambiguous setup.

Environment files

• Reports when .env exists but .env.example is missing.
• Never parses or prints environment variable values.

Expo app config

• Parses static app.json as JSON.
• Checks release metadata: expo.name, expo.slug, expo.version, expo.ios.buildNumber, and expo.android.versionCode.
• Checks release identities: expo.ios.bundleIdentifier and expo.android.package.
• Detects dynamic app.config.js and app.config.ts without evaluating them.

Dynamic app config limits the static checks that can be performed.

EAS release readiness

• Parses static eas.json as JSON.
• Reports a missing eas.json for Expo projects.
• Reports a missing build.production profile.
• Reports an empty build.production profile for review before release.

Reanimated setup

• Checks for react-native-reanimated in project dependencies.
• Uses narrow text scanning to look for react-native-reanimated/plugin in babel.config.js.
• Reports when the expected Babel setup cannot be found.

Reports

• Terminal report with project summary, detected files, lockfiles, and issues.
• Static local HTML report containing the same audit results.
• Pretty-printed JSON report with detected files, lockfiles, issue counts by severity, and the full issue list.

HTML report

rn-auditor report --html /path/to/project --output report.html

The report is a static HTML file written locally. It does not require a server or upload project data. Without --output, the file is written as rn-auditor-report.html in the current directory.

JSON report

rn-auditor report --json
rn-auditor report --json --output rn-auditor-report.json
rn-auditor report --json /path/to/project

Without --output, the pretty-printed JSON report is written to standard output. The report includes detected files, lockfiles, issue counts by severity, and the full issue list.

GitHub Actions

Use the JSON report in CI when you want a machine-readable audit artifact:

name: React Native Auditor

on:
  pull_request:
  push:
    branches: [main]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run React Native Auditor
        run: npx react-native-auditor@latest report --json --output rn-auditor-report.json

      - name: Upload JSON report
        uses: actions/upload-artifact@v4
        with:
          name: rn-auditor-json-report
          path: rn-auditor-report.json

You can also upload the optional HTML report for easier manual review:

      - name: Generate HTML report
        run: npx react-native-auditor@latest report --html --output rn-auditor-report.html

      - name: Upload HTML report
        uses: actions/upload-artifact@v4
        with:
          name: rn-auditor-html-report
          path: rn-auditor-report.html

See examples/reports/sample-report.json for a sample JSON report.

Security model

React Native Auditor treats project configuration as untrusted input.

• Does not upload project data.
• Does not require a SaaS account or service.
• Does not execute commands from the target project.
• Does not run npm, Yarn, pnpm, or Bun commands from the target project.
• Does not run Expo CLI, EAS CLI, or React Native CLI.
• Does not evaluate app.config.js or app.config.ts.
• Does not execute babel.config.js.
• Does not print .env values.

Static JSON parsing and narrow text scanning are used where a rule needs file contents. JavaScript and TypeScript configuration files are never loaded as executable modules.

Installation

The npm wrapper selects the bundled Rust binary for the current platform and forwards CLI arguments to it.

npx

npx react-native-auditor
npx react-native-auditor audit

Global npm install

npm install -g react-native-auditor
rn-auditor
rn-auditor audit

Other package runners

The published package exposes the standard rn-auditor npm binary and can also be launched with:

yarn dlx react-native-auditor
pnpm dlx react-native-auditor
bunx react-native-auditor

The npm wrapper selects the bundled Rust binary for the current platform and forwards CLI arguments to it. The v0.1 package includes binaries for macOS arm64/x64, Linux x64, and Windows x64.

Commands

Command	Description
rn-auditor	Open the guided menu in an interactive terminal.
rn-auditor audit [path] [--fail-on <level>] [--fix] [--interactive]	Audit a project and print the terminal report.
rn-auditor scan [path] [--fail-on <level>] [--fix] [--interactive]	Alias for audit.
rn-auditor report --html [path] [--output <file>] [--fail-on <level>]	Write a local static HTML report.
rn-auditor report --json [path] [--output <file>] [--fail-on <level>]	Print or write a pretty-printed JSON report.

If no path is provided, the current directory is audited. Exactly one of --html or --json is required for the report command. In non-interactive environments, running rn-auditor without a subcommand prints guidance and exits successfully instead of opening the menu.

Roadmap

Planned work remains deliberately focused:

• More high-value static rules.
• Stronger release-readiness checks.
• Log analysis as a later capability.
• More conservative, interactive fixes for high-confidence project maintenance tasks.

There is no plugin system planned for v1. Commands such as analyze-log and release-check are roadmap items, not v0.8.0 features. See docs/ROADMAP.md for current development notes.

Contributing

Contributions should prefer small, focused rules with clear findings. Checks must remain static-safe and must not execute code or commands from the target project.

Before submitting a Rust change, run:

cargo fmt --all -- --check
cargo check --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

License

MIT