rn-healer

rn-healer is a production-grade CLI toolkit for diagnosing and repairing React Native and Expo projects across Android, iOS, and macOS development environments.

It is designed as a modular diagnostics platform: commands are thin, services own orchestration, analyzers own domain rules, integrations talk to external registries, and plugins can add organization-specific checks without forking the CLI.

Install

npm install -D rn-healer

Or run directly:

npx rn-healer doctor

Commands

npx rn-healer doctor
npx rn-healer check-deps
npx rn-healer clean --android
npx rn-healer clean --ios
npx rn-healer clean --full
npx rn-healer diagnose build.log
cat metro.log | npx rn-healer diagnose
npx rn-healer health --min-score 80
npx rn-healer upgrade-check --target 0.76.0

What It Checks

doctor inspects Node.js, npm, Yarn, pnpm, Java, Android SDK, Xcode, CocoaPods, Ruby, Watchman, Gradle, React Native, and Expo SDK signals.

check-deps scans package.json, installed React Native ecosystem packages, npm metadata, React Native Directory data, Expo compatibility, Hermes/New Architecture signals, deprecated packages, duplicate native capabilities, and peer dependency risks.

diagnose parses Gradle, Xcode, Metro, npm, and yarn logs and maps known failure patterns to root causes and exact fixes.

health produces stability and dependency scores plus architecture and performance warnings.

upgrade-check generates an upgrade checklist, dependency risk report, and migration guardrails for a target React Native version.

Architecture

src/
  commands/       Commander.js command adapters
  analyzers/      Dependency and domain analyzers
  services/       Orchestration, project inspection, telemetry, CI, upgrade logic
  utils/          Filesystem, command, output, and version helpers
  constants/      Recommended versions, docs, scoring weights
  types/          Shared contracts for diagnostics, plugins, reports
  parsers/        Log parsers and pattern rules
  integrations/   npm registry and React Native Directory clients
  fixes/          Fix plan registry

The core model is intentionally AI-ready. Diagnostics, log findings, fix plans, and project metadata are structured data, so a future SaaS backend, VSCode extension, or AI remediation agent can consume the same engine without scraping terminal output.

Plugin Support

Create rn-healer.config.mjs in a project root:

export default {
  plugins: [
    {
      name: 'company-mobile-rules',
      async diagnostics(context, project) {
        return [
          {
            id: 'company.min-node',
            title: 'Company Node baseline',
            status: 'pass',
            severity: 'info',
            message: `Checked ${project.root}`
          }
        ];
      },
      logRules() {
        return [
          {
            id: 'company.internal-sdk',
            category: 'company',
            severity: 'error',
            patterns: [/InternalSDK initialization failed/i],
            title: 'Internal SDK initialization failed',
            rootCause: 'The internal SDK native config is missing.',
            fix: 'Regenerate native config and rebuild the app.'
          }
        ];
      }
    }
  ]
};

CI/CD

Use health scoring as a release gate:

npx rn-healer doctor --ci
npx rn-healer health --min-score 80
npx rn-healer check-deps --json > rn-healer-deps.json

The included GitHub Actions workflow runs type checking, unit tests, and package builds on Node 18, 20, and 22. Tagged releases publish to npm with provenance.

NPM Publish Setup

1. Create an npm automation token and save it as NPM_TOKEN in GitHub repository secrets.
2. Update author, repository metadata, and package version in package.json.
3. Run npm run build and npm test.
4. Create a semver tag:

git tag v0.1.0
git push origin v0.1.0

The publish workflow publishes the package from tags that start with v.

Development

npm install
npm run typecheck
npm test
npm run build
npm run dev -- doctor --verbose

Unit Test Examples

Tests live under tests/ and use Vitest. Current examples cover log root-cause matching and semver parsing. Add analyzer tests by injecting mock npm registry and React Native Directory clients into DependencyAnalyzer.

Roadmap

• Persistable JSON and SARIF reports.
• VSCode extension host adapter.
• SaaS workspace inventory and fleet health dashboards.
• AI remediation plans from structured diagnostics.
• More granular Expo SDK compatibility mappings.
• Native build graph diffing for Android and iOS.