skip to content

Before releasing an Expo app, how would you use npx expo-doctor, and how do you act on its dependency, React Native Directory and app-config-sync warnings?

level: seniorimportance: should knowfreq 32%

answer

  1. health check, not a fixer
  2. versions against the SDK
  3. React Native Directory lookup
  4. native folders present plus app config
  5. configure checks under expo.doctor

basics

~20 s

Run npx expo-doctor after upgrades, after adding libraries and before a release. Fix version mismatches with npx expo install --fix, review packages flagged by the React Native Directory check, and resolve config-sync warnings about committed native folders.

solid answer

~40 s

`npx expo-doctor` inspects the project: app config and `package.json` problems, whether dependency versions are compatible with the installed SDK, other configuration files, and overall health, with advice for each finding. Before a release I run it in CI as well as locally. Version mismatches I fix with `npx expo install --fix`, not by hand. The React Native Directory check warns about packages missing from the directory; I review each, and exclude known internal or vetted packages under `expo.doctor.reactNativeDirectoryCheck` in `package.json`. The app-config-sync warning means `android/` or `ios/` exist and are not ignored while an app config is present: EAS Build will then not apply app config changes to those native projects. So either gitignore and regenerate them, or accept that native edits are made by hand and disable that check deliberately.

code

json · 14 lines
json
{
  "expo": {
    "install": {
      "exclude": ["expo-splash-screen"]
    },
    "doctor": {
      "reactNativeDirectoryCheck": {
        "enabled": true,
        "exclude": ["@quiz/internal-ui"],
        "listUnknownPackages": true
      }
    }
  }
}

go deeper

for a junior

Know that npx expo-doctor diagnoses project problems such as incompatible dependency versions, and run it after changes.

for a middle

Explain its main checks and pair it with npx expo install --fix for version mismatches.

for a senior

Make doctor a release and CI gate, triage each warning, and resolve the native-folder sync warning by choosing generated or hand-maintained native code.

for a principal

Decide which checks are team policy and record every exclusion, so warnings stay meaningful rather than becoming noise.

## What expo-doctor is **Expo Doctor** is a diagnostic command-line tool for Expo projects, run from the project root: ```bash npx expo-doctor ``` It checks the codebase for common problems and prints each finding with a description and advice on how to fix it or where to look. The areas it covers, as the Expo docs list them: - **App config and `package.json`** problems. - **Dependency compatibility**: whether installed versions of `react-native`, Expo SDK packages and related libraries match what the project's SDK expects. - **Configuration files** and overall project health. - **React Native Directory** validation of your packages. - **App config sync** when native directories exist. It is a **diagnosis**, not a repair tool. The fixes are separate commands and decisions. ## When to run it 1. **After an SDK upgrade**, right after `npx expo install --fix`, as the Expo upgrade walkthrough does. 2. **After adding or bumping a library**, especially one with native code. 3. **When a native build fails** for no obvious reason; the build troubleshooting guide suggests it to confirm SDK dependency versions. 4. **Before a release**, and ideally in CI, so drift is caught before a build is spent on it. ## Acting on the three common warnings | Warning | What it means | Typical response | |---|---|---| | Dependency version mismatch | a package is outside the range the SDK expects | `npx expo install --fix`, then re-run doctor | | React Native Directory | a package is not listed in the directory | review it; exclude vetted or private packages | | App config fields not synced | `android/` or `ios/` exist, are not in `.gitignore` or `.easignore`, and an app config exists | gitignore and regenerate native folders, or accept manual native edits and disable the check | **Version mismatches.** Hand-editing versions tends to produce another mismatch. `npx expo install --fix` aligns packages to the SDK's expected versions. A package deliberately held at another version can be listed under `expo.install.exclude` in `package.json`, which also removes it from doctor's and `npx expo start`'s version checks. **React Native Directory.** The check compares packages against React Native Directory and, by default, lists unknown packages. For private packages or ones you have vetted, configure `expo.doctor.reactNativeDirectoryCheck` in `package.json`: `enabled`, an `exclude` list (strings or regex-like patterns), and `listUnknownPackages`. **App config not synced.** If native folders are committed while an app config exists, the project looks like it uses prebuild but is not regenerating. EAS Build does not sync app config properties into existing native projects, so a changed icon or version in `app.json` would silently not ship. Either stop committing the folders and let them be generated, or accept that native projects are hand-maintained and set `expo.doctor.appConfigFieldsNotSyncedCheck.enabled` to `false` as a recorded decision. ## Why version alignment matters Each Expo SDK release is built and tested against one React Native version and a set of package versions that ship native code. When a project drifts, for example a library that compiles native code against a different React Native version, the failure usually appears late: a native build error on the build server, or a crash or version-mismatch error at launch. The Expo troubleshooting guide for a React Native version mismatch points to `npx expo-doctor` for this reason: it names the expected version before a build is spent discovering it. Catching drift at the dependency level is far cheaper than diagnosing it from a native build log. ## A release checklist for a quiz app A team that prototyped its quiz app in Snack, moved it to a `default` template project, and added a few libraries might run this before its first store build: 1. `npx expo install --fix` to align versions with the SDK. 2. `npx expo-doctor` and read every finding, not just the count. 3. Resolve or explicitly exclude each React Native Directory warning, with a note on why. 4. Confirm whether `android/` and `ios/` should be committed; fix the sync warning either way. 5. Re-run doctor until the remaining output is only what the team has consciously accepted. ## Mistakes to avoid - Treating a clean doctor run as proof the app works; it checks configuration and dependencies, not behaviour. - Silencing checks globally instead of excluding specific packages. - Committing native folders "temporarily" and forgetting that app config edits no longer reach them.

  • Doctor warns that app config fields are not synced; what goes wrong if you ignore it?
    Native folders exist and are not ignored, so EAS Build uses them as they are and does not apply app config properties to them. A later change to the name, version, icon or permissions in the app config would not reach the built app, which is easy to miss until a store review or a tester notices.
  • Is a clean npx expo-doctor run enough to sign off a release?
    No. Doctor checks configuration, dependency versions and project health; it says nothing about whether screens work, data is correct or performance is acceptable. It is a cheap gate that prevents a class of build and upgrade failures, to be combined with tests and a device check.

saying these in an interview costs you the question

  • expo-doctor automatically fixes every problem it finds
  • A clean doctor run means the app is ready to release
  • Fix version warnings by editing package.json versions by hand
  • Disable the React Native Directory check instead of excluding packages
  • Committed native folders still receive app config changes on EAS Build