How to Clean a React Native Project Safely
React Native projects collect several kinds of local state while you work: Metro
cache, Watchman watches, node_modules, CocoaPods, Gradle build output, and
Xcode DerivedData. Cleaning all of them at once can fix some painful build
issues, but it can also create new problems if you delete lockfiles or update
native dependencies accidentally.
This guide shows a safer cleanup order. Start with the smallest cache reset that matches the symptom, then move down the checklist only if the problem remains.
Quick Answer
Do not start by deleting yarn.lock, package-lock.json, pnpm-lock.yaml, or
ios/Podfile.lock. Those files describe the dependency graph that your app was
tested with. For current Instamobile projects, start from the app folder and use
the commands from the included README, then try this order:
corepack enable
corepack yarn install --immutable
corepack yarn start --reset-cache
If the issue is native, clean only the native side that is failing:
# iOS
cd ios
pod install
cd ..
# Android
cd android
./gradlew clean
cd ..
For the full setup flow, use the React Native development environment guide and the current React Native stack. For error-specific fixes, use the React Native troubleshooting guide.
When a Clean Rebuild Makes Sense
A clean rebuild is useful when the app was previously built with a different native dependency set, Metro is resolving stale files, CocoaPods is out of sync, or Android Gradle is using stale build output.
Typical signals include:
- Metro says
Unable to resolve moduleeven though the package is installed. - iOS builds fail after a dependency or Podfile change.
- Android builds fail after changing native packages, SDK settings, or Firebase config files.
- You switched branches and the app uses a different dependency graph.
- The simulator keeps launching an older bundle.
Avoid using a full clean as a daily habit. If you need it constantly, there is usually a root cause in Node versions, package manager usage, native dependency state, or a misconfigured app path.
Mega Bundle Sale is ON! Get ALL of our React Native codebases at 90% OFF discount 🔥
Get the Mega BundleStep 1: Confirm You Are in the App Folder
Run cleanup commands from the root of the app you received, not from a parent workspace or a random cloned folder.
pwd
ls package.json
Then check the app's package manager. Current Instamobile projects are Corepack/Yarn based:
corepack enable
corepack yarn install --immutable
If you are working in a different React Native app, follow that app's lockfile:
npm ci for package-lock.json, pnpm install --frozen-lockfile for
pnpm-lock.yaml, or the documented Yarn command for yarn.lock.
Step 2: Reset Metro First
Metro cache issues are common and cheap to fix. Stop the existing Metro terminal and restart it with a reset:
corepack yarn start --reset-cache
For a generic React Native app, the equivalent is:
npx react-native start --reset-cache
If another Metro instance is already holding the port, close that terminal or stop the process before restarting. The detailed checklist is in Metro and Bundler Errors.
Step 3: Refresh Watchman Watches
Watchman helps React Native notice file changes quickly. If Metro keeps recrawling or misses file updates, reset the watches:
watchman watch-del-all
Then start Metro again. If Watchman is not installed on your machine, skip this step and continue with the platform-specific cleanup.
Step 4: Reinstall JavaScript Dependencies Carefully
Only remove node_modules when the install itself is suspect or you switched
branches with a different dependency graph.
rm -rf node_modules
corepack yarn install --immutable
Do not delete lockfiles as part of a routine clean. Deleting them can silently upgrade transitive dependencies and make the app different from the version that was tested.
Step 5: Clean iOS Pods Without Updating Everything
If the failure is iOS-specific, refresh CocoaPods from the existing lockfile:
cd ios
pod install
cd ..
Use pod update only when you intentionally want to update pods and understand
the version changes. Most build fixes need pod install, not pod update.
If Xcode still fails after pods are correct, remove DerivedData:
rm -rf ~/Library/Developer/Xcode/DerivedData
Then rebuild from Xcode or with the app's iOS command. See iOS and CocoaPods Errors for the full decision tree.
Step 6: Clean Android Build Output
If the failure is Android-specific, clean Gradle output from the Android folder:
cd android
./gradlew clean
cd ..
Then run the app again:
corepack yarn android
If Android Studio cannot find the SDK, adb, or the emulator, use
Android and Gradle Errors.
A Safe Full Clean Sequence
When the smaller fixes do not work, use a full clean that preserves lockfiles:
watchman watch-del-all || true
rm -rf node_modules
corepack yarn install --immutable
cd ios
pod install
cd ..
cd android
./gradlew clean
cd ..
corepack yarn start --reset-cache
After Metro starts, rebuild the affected platform:
corepack yarn ios
corepack yarn android
Run the verification commands from your app before spending time in the simulator:
corepack yarn typecheck
corepack yarn react-native config
Looking for a custom mobile application?
Our team of expert mobile developers can help you build a custom mobile app that meets your specific needs.
Get in TouchFAQ
Should I delete lockfiles when cleaning a React Native project?
No. Lockfiles keep the app on the dependency graph that was tested. Delete a lockfile only when you are intentionally upgrading dependencies and plan to test the result.
Should I use pod update or pod install?
Use pod install for normal rebuilds. pod update changes pod versions and can
introduce new native behavior.
Why does cleaning fix some React Native errors?
React Native combines JavaScript bundling, native build systems, generated files, and device caches. A stale cache in one layer can make another layer look broken. Cleaning the smallest affected layer keeps the fix controlled.