Upgrade Compatibility

## The problem npx expo install solves On the web, a newer version of a library usually still works with an older framework. **React Native is not backwards compatible** in that way: a package that contains native code is compiled against a particular `react-native` version, and a release built for a newer React Native can fail to compile, or crash at launch, on an older one. An Expo project pins one React Native version per SDK (SDK 57 ships `react-native` 0.86.3), so every native library needs the release that matches it. `npm install some-lib` knows nothing about that. It resolves the newest release allowed by the version range, often the latest, whatever React Native it targets. ## What npx expo install does `npx expo install <package>` is a drop-in replacement for your package manager's add command: 1. It reads the project's SDK version from the installed `expo` package. 2. It loads the **known versions** for that SDK: the `bundledNativeModules.json` file shipped inside `expo`, combined with a list fetched for that SDK. The fetched list wins where both have an entry, which lets fixes reach projects without a new `expo` release, and the local file is used when offline. 3. For each package in that map, it rewrites the request to the mapped range, for example `expo-camera@~57.0.5` on SDK 57. 4. It runs your package manager (`npm`, `yarn`, `pnpm` or `bun`, chosen from the lockfile or forced with `--npm` and similar flags) to install the result. Arguments after `--` go straight to the package manager, so `npx expo install typescript -- -D` adds a dev dependency. ## What it does not do | Situation | Behaviour | |---|---| | Package is in the SDK's map | installs the mapped version or range | | Package is not in the map | passed through unchanged; the package manager picks the version | | You type `[email protected]` explicitly | installs 1.2.3 and logs that you overrode the expected version | | Package is in `expo.install.exclude` | installs what you asked for and logs the exclusion | So `npx expo install` is a **best-effort** tool. For libraries outside the map, compatibility is still your job: check the library's README and React Native Directory. ## Versions that match the SDK Since SDK 55, Expo's own packages carry the SDK major as their version (`expo-router` and `expo-camera` are `~57.0.x` on SDK 57), which makes a mismatch easy to see in `package.json`. Third-party packages in the map, such as `react-native-reanimated` or `react-native-screens`, keep their own numbering, which is exactly why a lookup table is needed. ## Where the same map is used The known-versions map is not only for installs: - `npx expo start` checks installed versions against it at startup and prints the packages that "should be updated for best compatibility" with the installed `expo` version. - `npx expo install --check` and `--fix` validate and correct the whole project against it. ## When the map and a library disagree Occasionally a library's own documentation recommends a newer release than the SDK maps, usually for a bug fix. The map is the tested combination; the newer release is not. The sensible order is: 1. Try the mapped version first and see whether the bug really affects you. 2. If you need the newer release, install it explicitly and add the package to `expo.install.exclude`, so every later check shows the deviation as deliberate. 3. Revisit the exclusion at the next SDK upgrade, when the map may have caught up and the exception can be removed. ## Mistakes to avoid - Installing native libraries with plain `npm install`, then chasing the start-up warning or a native build error. - Pinning an explicit version "to be safe" and silently opting out of the SDK's mapping. - Assuming a passed-through package is compatible because the install succeeded; installation does not check native compatibility. ## A small example A pet-adoption app on SDK 57 adds the camera for profile photos. `npx expo install expo-camera` installs `~57.0.5`, the range SDK 57 expects. `npm install expo-camera` might fetch a newer major built for a later SDK, and the app would then warn at start-up or fail during the native build.