Why should a React Native library, such as an in-house PDF viewer, declare react-native as a peerDependency rather than a regular dependency?

## Three kinds of dependency A `package.json` can declare packages in three relevant places: | Field | Installed for consumers? | Meaning | |---|---|---| | `dependencies` | yes, possibly a private copy | "I need my own copy of this" | | `peerDependencies` | no; the app provides it | "I run inside a host that provides this, in this range" | | `devDependencies` | no | "I need this only to develop and test the package" | For a React Native library, `react-native` and `react` are the **host**: the library is code that runs inside an app that already has them. ## Why a private copy breaks things Suppose three apps share an in-house PDF-viewer package and the package lists `react-native: 0.86.3` under `dependencies`. An app on 0.87.1 installs it and the package manager, unable to satisfy both, puts a second `react-native` inside the library's own `node_modules`. Now: - **Metro may bundle two copies** of React Native's JavaScript, and if two copies of `react` end up in one app, hooks and context break with runtime errors. - **Native code exists once**: the binary contains one React Native native runtime, built from the app's version, so JavaScript from a second, different version would run against native code it was not written for. - **Codegen** runs in the app's build using the app's React Native, so the library's own copy only adds confusion. The Expo monorepo guide states the rule plainly: duplicate React Native versions in one monorepo are not supported, and duplicate React versions in one app cause runtime errors. ## What a peer dependency gives you 1. **One copy.** The library uses the app's `react-native`. 2. **A stated range.** `"react-native": ">=0.85.0"` documents what the library was built and tested against. 3. **A warning, not a silent duplicate.** When an app falls outside the range, the package manager reports a peer conflict at install time. The library still needs React Native to build its example app and run tests, so it pins a version in `devDependencies` as well. ## Native libraries your library needs If the PDF viewer builds on another native library, making it a peer dependency matters for a second reason: the community CLI autolinks the **app's** declared dependencies, so a native library that sits only inside your package's `dependencies` may never be linked. As a peer, the app installs it directly and autolinking sees it. Expo Autolinking resolves transitive dependencies, but a peer still keeps one copy per app. ## includesGeneratedCode and version ranges Normally a library ships only its spec files, and the **app** runs Codegen at build time with its own React Native version. Setting `"includesGeneratedCode": true` in the library's `codegenConfig` changes that: the library runs Codegen itself (for example with `npx @react-native-community/cli codegen`) and publishes the generated native code. - **Benefits:** the app no longer needs to generate anything for it, the implementation always matches its generated interfaces, and the native part can be shipped prebuilt. - **Drawback:** the generated code comes from the library's React Native version, and the React Native docs warn it may not work in apps on an **older** version. So a library that ships generated code should set its peer range's lower bound to the React Native version it generated with. The docs also warn against committing generated code casually for the same reason and point to `peerDependencies` as the way to restrict compatibility. ## Common mistakes - Declaring `react-native: "*"` as a peer: it promises support for versions nobody tested. - Pinning an exact peer version, which turns every app upgrade into a library release. - Forgetting `react` as a peer, so a second React slips in through the library. - Bundling another native library privately, where the app's autolinking may not see it. - Shipping generated code without raising the peer floor to the generating version. ## A practical package.json The library lists `react` and `react-native` as peers with a floor it has tested, pins exact versions under `devDependencies` for its example app, and keeps pure-JavaScript helpers in `dependencies`, where a private copy harms nothing.