This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Install Expo modules in an existing React Native project

Edit page

Learn how to prepare your existing React Native project to install and use any Expo module.


To use Expo modules in your app, you will need to install and configure the expo package.

The expo package has a small footprint; it includes only a minimal set of packages that are needed in nearly every app and the module and autolinking infrastructure that other Expo SDK packages are built with. Once the expo package is installed and configured in your project, you can use npx expo install to add any other Expo module from the SDK.

Depending on how you initialized the project, there are two ways you can install the Expo modules: automatically or manually.

Automatic installation

To install and use Expo modules, the easiest way to get up and running is with the install-expo-modules command.

Terminal
# Install and configure the expo package automatically
- npx install-expo-modules@latest
  • When the command succeeds, you will be able to add any Expo module in your app! Proceed to Usage for more information.

  • If the command fails, follow the manual installation instructions. Updating code programmatically can be tricky, and if your project deviates significantly from a default React Native project, then you need to perform manual installation and adapt the instructions here to your codebase.

Manual installation

The following instructions apply to React Native 0.88. For previous versions, check the native upgrade helper to see how these files are customized.

Terminal
- npm install expo

Once installation is complete, apply the changes from the following diffs to configure Expo modules in your project. This is expected to take about five minutes, and you may need to adapt it slightly depending on how customized your project is.

Configuration for Android

android/app/src/main/java/com/myapp/MainActivity.kt
11package com.myapp
2import expo.modules.ReactActivityDelegateWrapper
23
34import com.facebook.react.ReactActivity
45import com.facebook.react.ReactActivityDelegate
1819 * which allows you to enable New Architecture with a single boolean flags [fabricEnabled]
1920 */
2021 override fun createReactActivityDelegate(): ReactActivityDelegate =
21 DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled)
22 ReactActivityDelegateWrapper(this, BuildConfig.IS_NEW_ARCHITECTURE_ENABLED, DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled))
2223}
android/app/src/main/java/com/myapp/MainApplication.kt
11package com.myapp
2import android.content.res.Configuration
3import expo.modules.ApplicationLifecycleDispatcher
4import expo.modules.ExpoReactHostFactory
25
36import android.app.Application
47import com.facebook.react.PackageList
1013class MainApplication : Application(), ReactApplication {
1114
1215 override val reactHost: ReactHost by lazy {
13 getDefaultReactHost(
16 ExpoReactHostFactory.getDefaultReactHost(
1417 context = applicationContext,
1518 packageList =
1619 PackageList(this).packages.apply {
2326 override fun onCreate() {
2427 super.onCreate()
2528 loadReactNative(this)
29 ApplicationLifecycleDispatcher.onApplicationCreate(this)
30 }
31
32 override fun onConfigurationChanged(newConfig: Configuration) {
33 super.onConfigurationChanged(newConfig)
34 ApplicationLifecycleDispatcher.onConfigurationChanged(this, newConfig)
2635 }
2736}
android/settings.gradle
1pluginManagement { includeBuild("../node_modules/@react-native/gradle-plugin") }
2plugins { id("com.facebook.react.settings") }
3extensions.configure(com.facebook.react.ReactSettingsExtension){ ex -> ex.autolinkLibrariesFromCommand() }
1pluginManagement { includeBuild("../node_modules/@react-native/gradle-plugin")
2 def expoPluginsPath = new File(
3 providers.exec {
4 workingDir(rootDir)
5 commandLine("node", "--print", "require.resolve('expo-modules-autolinking/package.json', { paths: [require.resolve('expo/package.json')] })")
6 }.standardOutput.asText.get().trim(),
7 "../android/expo-gradle-plugin"
8 ).absolutePath
9 includeBuild(expoPluginsPath)
10}
11plugins { id("com.facebook.react.settings")
12id("expo-autolinking-settings")
13}
14extensions.configure(com.facebook.react.ReactSettingsExtension){ ex -> ex.autolinkLibrariesFromCommand(expoAutolinking.rnConfigCommand) }
415rootProject.name = 'myapp'
516include ':app'
617includeBuild('../node_modules/@react-native/gradle-plugin')
18expoAutolinking.useExpoModules()
19expoAutolinking.useExpoVersionCatalog()
20includeBuild(expoAutolinking.reactNativeGradlePlugin)
android/build.gradle
1919}
2020
2121apply plugin: "com.facebook.react.rootproject"
22apply plugin: "expo-root-project"
2223

Configuration for iOS

ExpoAppSceneDelegate creates the window and starts React Native. The app delegate creates the React Native factory.

ios/Podfile
1require File.join(File.dirname(`node --print "require.resolve('expo/package.json')"`), "scripts/autolinking")
12# Resolve react_native_pods.rb with node to allow for hoisting
23require Pod::Executable.execute_command('node', ['-p',
34 'require.resolve(
56 {paths: [process.argv[1]]},
67 )', __dir__]).strip
78
8platform :ios, min_ios_version_supported
9platform :ios, '16.4'
910prepare_react_native_project!
1011
1112linkage = ENV['USE_FRAMEWORKS']
1516end
1617
1718target 'myapp' do
18 config = use_native_modules!
19 use_expo_modules!
20
21 if ENV['EXPO_USE_COMMUNITY_AUTOLINKING'] == '1'
22 config_command = ['node', '-e', "process.argv=['', '', 'config'];require('@react-native-community/cli').run()"];
23 else
24 config_command = [
25 'node',
26 '--no-warnings',
27 '--eval',
28 'require(require.resolve(\'expo-modules-autolinking\', { paths: [require.resolve(\'expo/package.json\')] }))(process.argv.slice(1))',
29 'react-native-config',
30 '--json',
31 '--platform',
32 'ios'
33 ]
34 end
35
36 config = use_native_modules!(config_command)
1937
2038 use_react_native!(
2139 :path => config[:reactNativePath],
ios/myapp/AppDelegate.swift
11import UIKit
2internal import Expo
3import React
4import React_RCTAppDelegate
5import ReactAppDependencyProvider
26
37@main
4class AppDelegate: UIResponder, UIApplicationDelegate {
5 func application(
8class AppDelegate: ExpoAppDelegate, ExpoReactNativeFactoryProvider {
9 var window: UIWindow?
10
11 var reactNativeDelegate: ReactNativeDelegate?
12 var reactNativeFactory: RCTReactNativeFactory?
13 let reactNativeFactoryModuleName = "myapp"
14
15 override func application(
616 _ application: UIApplication,
717 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
818 ) -> Bool {
9 true
19 let delegate = ReactNativeDelegate()
20 let factory = ExpoReactNativeFactory(delegate: delegate)
21 delegate.dependencyProvider = RCTAppDependencyProvider()
22
23 reactNativeDelegate = delegate
24 reactNativeFactory = factory
25
26 return super.application(application, didFinishLaunchingWithOptions: launchOptions)
1027 }
1128}
29
30class ReactNativeDelegate: ExpoReactNativeFactoryDelegate {
31 override func bundleURL() -> URL? {
32#if DEBUG
33 RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
34#else
35 Bundle.main.url(forResource: "main", withExtension: "jsbundle")
36#endif
37 }
38}
ios/myapp/SceneDelegate.swift
1import React
2import React_RCTAppDelegate
3import ReactAppDependencyProvider
4import UIKit
1internal import Expo
52
6class SceneDelegate: RCTDefaultReactNativeFactoryDelegate, UIWindowSceneDelegate {
7 var window: UIWindow?
8 var reactNativeFactory: RCTReactNativeFactory?
9
10 func scene(
11 _ scene: UIScene,
12 willConnectTo session: UISceneSession,
13 options connectionOptions: UIScene.ConnectionOptions
14 ) {
15 guard let windowScene = scene as? UIWindowScene else {
16 return
17 }
18
19 dependencyProvider = RCTAppDependencyProvider()
20 reactNativeFactory = RCTReactNativeFactory(delegate: self)
21 window = UIWindow(windowScene: windowScene)
22
23 #if DEBUG
24 let devMenuConfiguration = RCTDevMenuConfiguration(
25 devMenuEnabled: true,
26 shakeGestureEnabled: true,
27 keyboardShortcutsEnabled: true
28 )
29 reactNativeFactory?.devMenuConfiguration = devMenuConfiguration
30 #endif
31
32 reactNativeFactory?.startReactNative(
33 withModuleName: "myapp",
34 in: window,
35 connectionOptions: connectionOptions
36 )
37
38
39 }
40
41 func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
42 RCTLinkingManager.scene(scene, openURLContexts: URLContexts)
43 }
44
45 func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
46 RCTLinkingManager.scene(scene, continue: userActivity)
47 }
48
49 override func bundleURL() -> URL? {
50 #if DEBUG
51 RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
52 #else
53 Bundle.main.url(forResource: "main", withExtension: "jsbundle")
54 #endif
55 }
3@objc(SceneDelegate)
4class SceneDelegate: ExpoAppSceneDelegate {
565}
576

If your React Native factory delegate has custom bundle selection in sourceURL(for:), move that logic to bundleURL() before removing sourceURL(for:).

Keep SceneDelegate.swift in your app target. In Info.plist, set UISceneDelegateClassName to $(PRODUCT_MODULE_NAME).SceneDelegate for the application scene in UIApplicationSceneManifest.

See the AppDelegate.swift and SceneDelegate.swift templates for reference.

Save all of your changes and update your iOS Deployment Target in Xcode to iOS 16.4:

  • Open your-project-name.xcworkspace in Xcode, select your project in the left sidebar.
  • Select Targets > your-project-name > Build Settings > iOS Deployment Target and ensure it is set to iOS 16.4.

The last step is to install the project's CocoaPods again to pull in Expo modules that are detected by use_expo_modules! directive that we added to the Podfile:

Terminal
# Install pods
- npx pod-install

# Alternatively, the run command will install them for you
- npx expo run:ios

Configure Expo CLI for bundling on Android and iOS

We recommend using Expo CLI and related tooling configurations to bundle your app JavaScript code and assets. This adds support for using the "main" field in package.json to use Expo Router library. Not using Expo CLI for bundling may result in unexpected behavior. Learn more about Expo CLI.

Use babel-preset-expo in your babel.config.js
babel.config.js
11module.exports = {
2 presets: ['module:@react-native/babel-preset'],
2 presets: ['babel-preset-expo'],
33};
Extend expo/metro-config in your metro.config.js
metro.config.js
1const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
1const { getDefaultConfig } = require('expo/metro-config');
2const { mergeConfig } = require('@react-native/metro-config');
23
34/**
45 * Metro configuration
Configure Android project to bundle with Expo CLI
android/app/build.gradle
5252
5353 /* Autolinking */
5454 autolinkLibrariesWithApp()
55 //
56 // Added by install-expo-modules
57 entryFile = file(["node", "-e", "require('expo/scripts/resolveAppEntry')", rootDir.getAbsoluteFile().getParentFile().getAbsolutePath(), "android", "absolute"].execute(null, rootDir).text.trim())
58 cliFile = new File(["node", "--print", "require.resolve('@expo/cli')"].execute(null, rootDir).text.trim())
59 bundleCommand = "export:embed"
5560}
5661
5762/**
Configure iOS project to bundle with Expo CLI

Replace the shell script under Build Phases > Bundle React Native code and images in Xcode with the following:

/bin/sh
if [[ -f "$PODS_ROOT/../.xcode.env" ]]; then source "$PODS_ROOT/../.xcode.env" fi if [[ -f "$PODS_ROOT/../.xcode.env.local" ]]; then source "$PODS_ROOT/../.xcode.env.local" fi # The project root by default is one level up from the ios directory export PROJECT_ROOT="$PROJECT_DIR"/.. if [[ "$CONFIGURATION" = *Debug* ]]; then export SKIP_BUNDLING=1 fi if [[ -z "$ENTRY_FILE" ]]; then # Set the entry JS file using the bundler's entry resolution. export ENTRY_FILE="$("$NODE_BINARY" -e "require('expo/scripts/resolveAppEntry')" "$PROJECT_ROOT" ios relative | tail -n 1)" fi if [[ -z "$CLI_PATH" ]]; then # Use Expo CLI export CLI_PATH="$("$NODE_BINARY" --print "require.resolve('@expo/cli')")" fi if [[ -z "$BUNDLE_COMMAND" ]]; then # Default Expo CLI command for bundling export BUNDLE_COMMAND="export:embed" fi `"$NODE_BINARY" --print "require('path').dirname(require.resolve('react-native/package.json')) + '/scripts/react-native-xcode.sh'"`

And add support the "main" field in package.json by making the following change to AppDelegate.swift:

ios/AppDelegate.swift
11override func bundleURL() -> URL? {
22#if DEBUG
3 RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
3 RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: ".expo/.virtual-metro-entry")
44#else
55 Bundle.main.url(forResource: "main", withExtension: "jsbundle")
66#endif
77}

Usage

Verifying installation

You can verify that the installation was successful by logging a value from expo-constants.

  • Run npx expo install expo-constants
  • Then, run npx expo run and modify your app JavaScript code to add the following:
import Constants from 'expo-constants'; console.log(Constants.systemFonts);

Using Expo SDK packages

Once the expo package is installed and configured in your project, you can use npx expo install to add any other Expo module from the SDK. See Using Libraries for more information.

Expo modules included in the expo package

The following Expo modules are brought in as dependencies of the expo package:

  • expo-asset - A JavaScript-only package that builds around expo-file-system and provides a common foundation for assets across all Expo modules.
  • expo-constants - Provides access to the manifest.
  • expo-file-system - Interact with the device file system. Used by expo-asset and many other Expo modules. Commonly used directly by developers in application code.
  • expo-font - Load fonts at runtime. This module is optional and can be safely removed. However, it is recommended if you use expo-dev-client for development and it is required by @expo/vector-icons.
  • expo-keep-awake - Prevents your device from going to sleep while developing your app. This module is optional and can be safely removed.

To exclude any of these modules, refer to the following guide on excluding modules from autolinking.

Excluding specific modules from autolinking

If you need to exclude native code from Expo modules you are not using, but were installed by other dependencies, you can use the expo.autolinking.exclude property in package.json:

package.json
{ "name": "...", "dependencies": {}, "expo": { "autolinking": { "exclude": ["expo-keep-awake"] } } }