Learn how to compile and build your app locally when using Expo.
To build your project into an app locally using your machine, you have to manually generate native code before testing the debug build or creating a production build for it to submit to the app store. There are two ways you can build your app locally. This guide provides a brief introduction to both methods and references to other guides that are necessary to create this workflow.
To follow the steps described in this guide, see the instructions below on how to set your development environment.
To set up your development environment on macOS for Android, you will install Node.js, Watchman, JDK, and Android Studio.
Use a package manager such as Homebrew to install the following dependencies.
1
Install the LTS release of Node.js using a version management tool such as nvm
or volta
. If you have already installed Node.js on your system, make sure the version is 16 or above.
2
Install Watchman using a tool such as Homebrew:
-
brew install watchman
3
Install OpenJDK distribution called Azul Zulu using Homebrew. This distribution offers JDKs for both M1 and Intel Macs.
We recommend JDK 11 (you may encounter problems with higher JDK versions). Run the following commands in a terminal window to install it:
-
brew tap homebrew/cask-versions
-
brew install --cask zulu11
After you install the JDK, add the JAVA_HOME
environment variable in ~/.bash_profile (or ~/.zshrc if you use Zsh):
export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-11.jdk/Contents/Home
Android Studio allows installing Android SDK, Android SDK Platform, and Android Virtual Device. They are required to set up the Android development environment. Follow the instructions on the Android Studio Emulator to install these tools.
To set up your development environment on Windows for Android, you will install Node.js, JDK, and Android Studio.
Use a package manager such as Chocolatey to install the following dependencies.
1
Install the LTS version of Node.js using Chocolatey:
-
choco install -y nodejs
If you have already installed Node.js on your system, make sure the version is 16 or above. If you want to be able to switch between different versions, you might want to install Node.js using a version manager such as nvm-windows
.
2
Install Java SE Development Kit (JDK):
-
choco install -y microsoft-openjdk11
If you already have JDK installed on your system, we recommend JDK11.
Android Studio allows installing Android SDK, Android SDK Platform, and Android Virtual Device. They are required to set up the Android development environment. Follow the instructions on the Android Studio Emulator to install these tools.
To set up your development environment on Linux for Android, you will install Node.js, Watchman, JDK, and Android Studio.
1
Install Node.js 16 or above by following installation instructions for your Linux distribution.
2
Follow installation instructions from the Watchman installation guide to compile and install it from the source.
3
Install Java SE Development Kit (JDK) version 11. You can download and install OpenJDK from AdoptOpenJDK or your system packager.
-
choco install -y microsoft-openjdk11
If you already have JDK installed on your system, we recommend JDK11.
Android Studio allows installing Android SDK, Android SDK Platform, and Android Virtual Device. They are required to set up the Android development environment. Follow the instructions on the Android Studio Emulator to install these tools.
A macOS is required to build projects with native code for iOS. You can create a development build to install the build on an iOS device.
To set up your development environment on macOS for iOS, you'll need to install Node.js, Watchman, Xcode, and CocoaPods.
Use a package manager such as Homebrew to install the following dependencies.
1
Install the LTS release of Node.js using a version management tool such as nvm
or volta
. If you have already installed Node.js on your system, make sure the version is 16 or above.
2
Install Watchman using a tool such as Homebrew:
-
brew install watchman
3
Install Xcode using the App Store. This tool will also install the iOS Simulator. You will also need to install Command Line Tools.
4
Install CocoaPods. You can install using the version of Ruby that ships with the latest macOS version.
To build your project locally you can use compile commands from Expo CLI which generates the android and ios directories:
# Build native Android project
-
npx expo run:android
# Build native iOS project
-
npx expo run:ios
The above commands compile your project, using your locally installed Android SDK or Xcode, into a debug build of your app.
npx expo prebuild
to generate native directories (android and ios) before building, if they do not exist yet. If they already exist, this will be skipped.--device
flag to select a device to run the app on — you can select a physically connected device or emulator/simulator.--variant release
(Android) or --configuration Release
(iOS) to build a production version of your app.To modify your project's configuration or native code after the first build, you will have to rebuild your project. Running npx expo prebuild
again layers the changes on top of existing files. It may also produce different results after the build.
To avoid this, add native directories to the project's .gitignore and use npx expo prebuild --clean
command. This ensures that the project is always managed, and the --clean
flag will delete existing directories before regenerating them. You can use app config or create a config plugin to modify your project's configuration or code inside the native directories.
To learn more about how compilation and prebuild works, see the following guides:
Learn how Expo CLI uses run
commands to compile your app locally, arguments you can pass to the CLI and more.
Learn how Expo CLI generates native code of your project before compiling it.
expo-dev-client
If you install expo-dev-client
to your project, then a debug build of your project will include the expo-dev-client
UI and tooling, and we call these development builds.
-
npx expo install expo-dev-client
To create a development build, you can use local app compilation commands (npx expo run:[android|ios]
) which will create a debug build and start the development server.
Learn how to run EAS Build on your custom infrastructure or locally on your machine with the --local
flag.