Upgrading Project Dependencies
How to update your project dependencies.
This guide covers updating your project's dependencies only. It does not guarantee your project stays in sync with the latest Caracal starter changes.
To benefit from the latest starter improvements, compare your osMetadata.initVersion in package.json with the latest release on GitHub and manually apply any relevant changes.
Easy Way
Upgrading a React Native project can be painful, but Caracal is built on Expo with a custom dev client, which makes the process significantly simpler than a bare React Native project.
To update most starter dependencies:
- Go to GitHub and compare your
osMetadata.initVersionagainst the latest release. - Check whether
package.jsonhas changed. - Copy the updated
dependenciesanddevDependenciesversions into yourpackage.json. - Run the full verification sequence:
rm -rf node_modules # remove node_modules folder
pnpm install # install new dependencies
pnpm run doctor # check for dependency issues
pnpm lint # linting
pnpm type-check # type checking
pnpm test # tests
pnpm prebuild --clean # regenerate ios and android folders
pnpm ios # run iOS build
pnpm android # run Android build
pnpm start -c # start the server with cleared cacheIf your starter version does not include osMetadata.initVersion, skip that step and follow the rest of this guide directly. The remaining sections also apply when you have added custom dependencies to your project.
Upgrade Expo
Check npmjs.com/package/expo for the latest Expo version, then run:
pnpm add expo@latestExpo provides a command that automatically aligns your dependencies to the versions required by the installed Expo release:
pnpm expo install --fixIn some cases this command will flag additional manual changes required. After running it, use expo-doctor to catch any remaining issues with native dependencies and devDependencies:
pnpm run doctorThis outputs a list of packages that need manual version pinning. Once resolved, run the full verification sequence:
rm -rf node_modules
pnpm install
pnpm lint
pnpm type-check
pnpm test
pnpm prebuild --clean
pnpm ios
pnpm android
pnpm start -cIf errors appear, read the error message carefully, identify the packages involved, and check their changelogs for breaking changes in recent major versions.
Upgrade regularly — ideally about a month after each new Expo major release. Smaller, frequent upgrades are far easier to manage than large catch-up upgrades.
Upgrade Non-Native Dependencies
Expo's upgrade process handles native dependencies automatically. JavaScript-only (non-native) dependencies need a separate pass.
Run the interactive pnpm upgrade tool:
pnpm up -iThis lists all dependencies with available updates and lets you select which ones to upgrade:
◯ zod latest 3.19.1 ❯ 3.21.4 https://zod.dev
◯ zustand latest 4.1.4 ❯ 4.3.6 https://github.com/pmndrs/zustand
devDependencies
name range from to url
◯ @babel/core latest 7.20.2 ❯ 7.21.0 https://babel.dev/docs/en/next/babel-core
◯ @commitlint/cli latest 17.2.0 ❯ 17.4.4 https://commitlint.js.org/
◯ @typescript-eslint/eslint-plugin latest 5.42.1 ❯ 5.54.1 https://github.com/typescript-eslint/typescript-eslint#readme
◯ eslint latest 8.27.0 ❯ 8.35.0 https://eslint.orgPay close attention to major version bumps — these may contain breaking changes. Review the changelog for any package jumping a major version before selecting it.
Recommended order:
- Select all
devDependenciesand update them. - Run
pnpm doctorto revert any that conflict with the current Expo version. - Run the full verification sequence.
- If everything passes, update the remaining
dependencies.
rm -rf node_modules
pnpm install
pnpm lint
pnpm type-check
pnpm test
pnpm prebuild --clean
pnpm ios
pnpm android
pnpm start -cIf your app is not fully covered by automated tests, manually exercise the most critical user flows before committing the upgrade. Automated checks catch many regressions but not all.