Understanding Dependencies in React Native

Dependencies are external libraries or modules that your project relies on to add functionality, streamline development, or improve performance. In React Native, dependencies are typically managed via npm or yarn – JavaScript package managers that handle library installation, updates, version control, and sometimes even native code linking. Unlike a standard web app, React Native projects often bundle JavaScript dependencies alongside native dependencies (iOS CocoaPods, Android Gradle files), making dependency management more nuanced.

Dependencies fall into two categories:

  • JavaScript dependencies – pure JS libraries (e.g., axios, lodash) that work without any native configuration.
  • Native dependencies – libraries that require bridging to native code (e.g., react-native-camera, @react-native-community/geolocation). These often need additional setup steps like npx pod-install or manual Gradle changes.

The React Native documentation provides details on initializing a project and its default dependency tree.

Installing Dependencies

To add a new library to your React Native project, use the package manager's install command. For example, to install react-navigation, run:

npm install @react-navigation/native @react-navigation/stack

or with yarn:

yarn add @react-navigation/native @react-navigation/stack

After installation, some libraries require linking of native code. In React Native 0.60+, auto-linking automatically handles most native dependencies. However, certain libraries (especially those with custom native views or third‑party SDKs) still require manual steps:

  • For iOS: run npx pod-install or cd ios && pod install to install the CocoaPods pods.
  • For Android: the library's android/build.gradle is automatically merged, but you may need to add a maven repository or modify MainApplication.java if the library’s React Native package isn’t auto‑registered.

Always check the library’s installation guide – many popular libraries post‑install steps to avoid runtime crashes.

For projects using React Native <0.60, you must manually link native dependencies with npx react-native link library-name. This command modifies your Podfile and/or android/settings.gradle. If you’re maintaining a legacy project, consider migrating to auto‑linking with npx react-native upgrade.

Saving Dependencies

By default, npm and yarn save installed packages to your package.json file under the dependencies or devDependencies section. This keeps track of all dependencies and their version ranges, ensuring that other developers or deployment environments can install the same set of packages with a single command (npm install or yarn).

When you install a package without explicitly marking it as a dev dependency, it is saved under dependencies. For tools used only during development (e.g., jest, @babel/core, metro-react-native-babel-preset), use:

npm install --save-dev package-name
yarn add --dev package-name

Maintaining a clear separation between runtime and dev dependencies reduces bundle size in production and prevents accidental inclusion of build‑time utilities in the app store archive.

Managing Dependency Versions

Specifying exact versions in your package.json helps prevent unexpected issues caused by updates. You can use semantic versioning (semver) to control updates:

  • ^1.0.0 – accepts any minor or patch version above 1.0.0 (e.g., 1.1.0, 1.2.5) but not 2.0.0.
  • ~1.0.0 – accepts only patch versions above 1.0.0 (e.g., 1.0.1, 1.0.9) but not 1.1.0.
  • 1.0.0 – pinned to exactly version 1.0.0 (no updates).

For production apps, pin your direct dependencies to exact versions (e.g., "react": "18.2.0") to avoid accidental breaking changes during deployment. Use a lock file (package-lock.json or yarn.lock) to guarantee that every install produces identical node_modules trees.

Resolving Version Conflicts

When two libraries require different versions of the same package, you may encounter peer dependency warnings or runtime errors. Tools to resolve conflicts:

  • npm ls package-name – displays the dependency tree and highlights duplicates.
  • yarn why package-name – explains why a package is installed.
  • npm dedupe / yarn-deduplicate – flattens duplicate packages where possible.

For React Native, pay extra attention to conflicting versions of react-native, react, or native modules like react-native-safe-area-context. Inconsistent versions can cause cryptic errors like “Native module cannot be found.”

Updating Dependencies

Regularly updating dependencies is vital for security, performance, and access to new features. Use the following approaches:

  • Minor/Patch updates: npm update or yarn upgrade – safe for non‑breaking changes.
  • Major updates: manually bump the version in package.json and run npm install. Review the library’s changelog for breaking API changes.
  • Interactive upgrade: use npx npm-check-updates (installed separately) to see which packages have latest versions, then selectively update.

When updating core React Native itself (react-native package), always follow the official React Native upgrade guide and use npx react-native upgrade to merge changes into your project’s template files. Test thoroughly on both iOS and Android simulators and real devices after any major update.

Automating Updates with CI/CD

In a continuous integration pipeline, set up a job that runs npm outdated or yarn outdated periodically, creates a pull request for minor updates, and triggers full test suites. This prevents dependency rot while maintaining a stable environment.

Removing Unused Dependencies

When a library is no longer used, remove it to reduce bundle size and simplify maintenance:

npm uninstall library-name
yarn remove library-name

Unused packages can linger in node_modules even after removal if they were transitive dependencies. Run npm prune or yarn autoclean --init to delete extraneous packages. For a more thorough cleanup, consider:

  • depcheck – a tool that identifies unused dependencies in your codebase.
  • npx react-native unlink library-name (legacy) – removes any native linking artifacts.

Best Practices for Dependency Management

  • Regularly review and update dependencies. Schedule a monthly “dependency audit” – check for security advisories (npm audit), update to latest stable versions, and clean up obsolete packages.
  • Keep dependencies to the minimum required. Avoid “kitchen sink” libraries; choose focused, well‑maintained alternatives (e.g., react-native-vector-icons for icons instead of importing an entire UI kit).
  • Use semantic versioning to control updates. Pin major versions and rely on lock files for reproducibility.
  • Test thoroughly after updating dependencies. Run unit tests, integration tests, and manual UI testing on both platforms. Pay attention to altered native module behavior.
  • Maintain a clean package.json and lock files. Avoid manual edits that can introduce inconsistencies. Commit package-lock.json or yarn.lock to version control to ensure identical installs across environments.
  • Prefer yarn over npm if you need deterministic installs and workspaces. Yarn Berry (v2+) offers Plug'n'Play, which can speed up installs but may require compatibility checks with React Native.
  • Use npx react-native doctor to diagnose common dependency and environment issues before debugging.

Handling Native Dependencies with CocoaPods and Gradle

For iOS, always commit ios/Podfile.lock to lock the versions of native pods. Run cd ios && pod update when you upgrade a React Native library to get the latest compatible pod version. For Android, ensure that your android/app/build.gradle does not have conflicting compileSdkVersion or targetSdkVersion values across libraries.

Using monorepos with React Native

If your project uses a monorepo (e.g., Nx, Turborepo, Lerna), manage dependencies at the root level with workspaces. Be careful with hoisting – some React Native libraries may require nohoist options to avoid transitive dependency conflicts.

Common Pitfalls and How to Avoid Them

  • “Cannot find module” errors after npm install: Delete node_modules, package-lock.json, and run fresh install. If using yarn, delete yarn.lock as well (but be cautious with lock files).
  • iOS build fails after adding a library: Ensure you ran npx pod-install and that the library’s podfile is correctly referenced. Check Xcode build logs for “library not found” errors.
  • Android runtime crash due to missing native module: Verify that the library’s Android package is auto‑registered or that you manually added its ReactPackage in MainApplication.java.
  • Duplicate symbol or method conflicts: Use npx react-native-community/cli doctor and resolve conflicting native codes by upgrading or downgrading one of the libraries.

External Resources

Effective dependency management helps keep your React Native project secure, efficient, and maintainable. Following these practices will streamline development, reduce potential issues caused by outdated or incompatible libraries, and allow your team to focus on building features rather than fighting dependency hell.