Fully Cleaning Your React Native Project

Stale caches and leftover build artifacts cause a large share of React Native build failures. This guide covers how to clean everything — dependencies, iOS build, Android Gradle, and simulators — and how to automate it with a single terminal alias.

Cleaning Cache and Dependencies

Run the following commands from your project root.

npm

watchman watch-del-all
rm -rf yarn.lock package-lock.json node_modules
rm -rf android/app/build
rm -rf ios/Pods ios/Podfile.lock
rm -rf ~/Library/Developer/Xcode/DerivedData
npm install && cd ios && pod update && cd ..
npm start -- --reset-cache

Or as a single command:

watchman watch-del-all && rm -rf yarn.lock package-lock.json node_modules && rm -rf android/app/build && rm -rf ios/Pods ios/Podfile.lock && rm -rf ~/Library/Developer/Xcode/DerivedData && npm install && cd ios && pod update && cd .. && npm start -- --reset-cache

Yarn

watchman watch-del-all
rm -rf yarn.lock package-lock.json node_modules
rm -rf android/app/build
rm -rf ios/Pods ios/Podfile.lock
rm -rf ~/Library/Developer/Xcode/DerivedData
yarn install && cd ios && pod update && cd ..
yarn start -- --reset-cache

Or as a single command:

watchman watch-del-all && rm -rf yarn.lock package-lock.json node_modules && rm -rf android/app/build && rm -rf ios/Pods ios/Podfile.lock && rm -rf ~/Library/Developer/Xcode/DerivedData && yarn install && cd ios && pod update && cd .. && yarn start -- --reset-cache

Cleaning the iOS Build

Clearing the Xcode build folder resolves most iOS-specific compile errors.

1. Open Xcode 2. Go to Product > Clean Build Folder 3. Or use the keyboard shortcut: Option + Shift + Command + K

Resetting Android Emulator Data

If your Android emulator is behaving unexpectedly, wipe its data.

1. Open Android Studio 2. Go to Tools > AVD Manager 3. Select your emulator and click Wipe Data

Cleaning the Android Build Cache

If the Android build is failing, clear the Gradle cache.

cd android && ./gradlew clean

For a full cache wipe:

cd android && ./gradlew cleanBuildCache

Automating Cleanup with an Alias

If you clean your project regularly, a shell alias saves significant time.

Step 1 — Open your terminal profile

For zsh (macOS default):

open ~/.zprofile

For bash:

open ~/.bash_profile

Step 2 — Add the alias

Paste this into the file:

alias cleanstart="watchman watch-del-all && killall -9 node && rm -rf yarn.lock package-lock.json node_modules ios/Pods ios/Podfile.lock android/app/build && npm install && cd ios && pod update && cd .. && npm start -- --reset-cache"

Step 3 — Apply the changes

source ~/.zprofile    # zsh
source ~/.bash_profile  # bash

Step 4 — Use it

From any project root, run:

cleanstart

When to Run a Full Clean

A full clean is worth doing when you see any of the following:

* Red build errors that appeared after pulling new changes * Metro bundler showing stale module warnings * iOS simulator crashing on launch after a dependency update * Android Gradle sync failing with no clear error message

Summary