Adopting Prebuild

There are many advantages of using Expo Prebuild to generate your native projects. This guide will show you how to adopt Expo Prebuild in a project that was bootstrapped with npx react-native init. The amount of time it will take to convert your project depends on the amount of custom native changes that you have made to your iOS and Android native projects — on a brand new project, this may take a minute or two, and on a large project it could be much longer.

Adopting prebuild will automatically add support for developing modules with the Expo native module API by linking expo-modules-core natively. You can also use any command from Expo CLI in your project.

Bootstrap a new project

This will create a new React Native project.

Not all versions of react-native are explicitly supported. Make sure to use a version of react-native that has a corresponding Expo SDK version.

Install the expo package

The expo package contains the npx expo prebuild command and indicates which prebuild template to use:

Ensure you install the version of expo that works for your currently installed version of react-native: supported versions.

Update the entry file

Modify the entry file to use registerRootComponent instead of AppRegistry.registerComponent:

+ import {registerRootComponent} from 'expo';

- import {AppRegistry} from 'react-native';
import App from './App';
- import {name as appName} from './app.json';

- AppRegistry.registerComponent(appName, () => App);
+ registerRootComponent(App);

Learn more about registerRootComponent.

Prebuild

Make sure you've committed your changes in case you want to revert, the command will warn you about this too!

If you're migrating an existing project, then you may want to refer to migrating native customizations first.

Run the following command to regenerate the /ios and /android directories based on the Expo config (app.json) configuration:

You can test that everything worked by building the projects locally:

Learn more about compiling native apps.

Extra changes

The following changes are optional but recommended.

.gitignore

You can add .expo/ to your .gitignore to prevent generated values from Expo CLI from being committed. You can also add ios/ and android/ to the .gitignore if you want to ensure they aren't committed between prebuilds.

app.json

Remove all fields that are outside of the top-level expo object as these will not be used in npx expo prebuild.

{
-  "name": "myapp",
-  "displayName": "myapp"
+  "expo": {
+    "name": "myapp"
+  }
}

metro.config.js

See: Customizing Metro

package.json

You may want to change the scripts to use the Expo CLI run commands:

  "scripts": {
    "start": "expo start --dev-client",
-    "android": "react-native run-android",
-    "ios": "react-native run-ios",
+    "android": "expo run:android",
+    "ios": "expo run:ios",
  },

These commands have better logging, auto code signing, better simulator handling, and they ensure you run npx expo start to serve files.

Migrating native customizations

If your project has any native modifications (changes to the ios or android directories, such as app icon configuration or splash screen) then you'll need to configure your Expo config (app.json) to reflect those native changes.

• Check to see if your changes overlap with the built-in Expo config fields. For example, if you have an app icon, be sure to define it as expo.icon in the app.json then re-run npx expo prebuild.
• Look up if any of the packages you're using require an Expo Config Plugin. If a package in your project required additional changes inside of the ios/ or android/ folders, then you will probably need a Config Plugin. Some plugins can be automatically added by running npx expo install with all of the packages in your package.json dependencies. If a package requires a plugin but doesn't supply one, then you can try checking the community plugins at expo/config-plugins to see if one already exists.
• You can use the VS Code Expo extension to introspect your changes and debug if prebuild is generating the native code you expect. Just press Cmd ⌘ + Shift + P, type "Expo: Preview Modifier", and select the native file you wish to introspect.
• Additionally, you can develop local config plugins to fit your needs. Learn more.

Adding More Features

Prebuild is the tip of the automation iceberg, here are some features you can adopt next:

• EAS Build: Code signing and cloud building.
• EAS Update: Send over-the-air updates instantly.
• Expo for web: Run your app in the browser.
• Expo Dev Client: Create your own personal "Expo Go" type app around your native runtime.
• Expo native module API: Write modules with Swift and Kotlin. This is automatically supported when using npx expo prebuild.