Migrate from React Native CLI to Expo CLI

Learn how to migrate from React Native CLI (@react-native-community/cli) to Expo CLI for any React Native project.

To migrate from React Native CLI (npx @react-native-community/cli@latest init) to Expo CLI, you'll need to install the expo package, which includes the Expo Modules API and Expo CLI. This guide covers the installation step, the benefits of using Expo CLI, and how to compile and run your project after migrating to Expo CLI.

It is strongly recommended to use Expo CLI when using other Expo tools. It is required for many tools, such as EAS Update, Expo Router, and expo-dev-client, and other features may not work as well without it.

Install the expo package

In most cases, executing the following command in a project directory to install the package is all you need to do:

For a detailed installation guide, see Install Expo modules.

After installing the expo package, you'll need to configure your project to use Expo CLI. This includes setting up Metro config, Babel preset, and native project configurations. See the Configure Expo CLI for bundling on Android and iOS section for the complete setup instructions.

Why Expo CLI instead of React Native CLI

Expo CLI commands provide several benefits over the similar commands in @react-native-community/cli, which includes:

• Instant access to Hermes debugger with j keystroke.
• The debugger ships with React Native DevTools.
• Continuous Native Generation (CNG) support with expo prebuild for upgrades, white-labeling, easy third-party package setup, and better maintainability of the codebase (by reducing the surface area).
• Support for file-based routing with expo-router.
  • Async bundling in development.
• Built-in environment variable support and .env file integration.
• View native logs directly in the terminal alongside JavaScript logs.
• Improved native build log formatting using Expo CLI's xcpretty-style tool built specifically for React Native apps. For example, when compiling a Pod, you can see which Node module included it.
• First-class TypeScript support.
• Support for tsconfig.json aliases with paths and baseUrl built-in to Metro.
• Web support with Metro. Fully typed for React Native Web.
• Modern CSS support with Tailwind, PostCSS, CSS Modules, SASS, and more.
• Static site generation with Expo Router and Metro web.
• Out of the box support for monorepos.
• Support for Expo tooling such as expo-dev-client, the Expo Updates protocol and EAS Update.
• Automated pod install execution when using npx expo run:ios.
• npx expo install selects compatible dependency versions for well-known packages.
• Automatic port detection when running npx expo run:[android|ios] and npx expo start. If another app is running on the default port, a different port is used.
• Android or iOS device launch selection shortcuts using Shift + a or Shift + i from the interactive prompt.
• Built-in support for serving your app over an ngrok tunnel.
• Develop on any port with any entry JavaScript file.

We recommend Expo CLI for most React Native projects that target Android, iOS, and/or web. It does not yet have built-in support for the most popular out-of-tree platforms, such as Windows and macOS. If building for these platforms, you can utilize Expo CLI for the supported platforms and @react-native-community/cli for the others.

Compile and run your app

After installing the expo package, you can use the following commands which are alternatives to npx react-native run-android and npx react-native run-ios:

When building your project, you can choose a device or simulator by using the --device flag. This also applies to any iOS device that is connected to your computer.

Start the bundler independently

npx expo run:[android|ios] automatically starts the bundler/development server. If you want to independently start the bundler with npx expo start command, pass the --no-bundler to the npx expo run:[android|ios] command.

Common questions

module.exports = {
  dependencies: {
    expo: {
      platforms: {
        android: null,
        ios: null,
        macos: null,
      },
    },
  },
};

Next steps

Now, with the expo package installed and configured in your project, you can start using all features from Expo CLI and SDK. Here are some recommended next steps to dive deep: