xref: /expo/docs/pages/bare/using-expo-cli.mdx (revision 8e519a31) 
1---
2title: Migrate to Expo CLI
3description: Learn how to migrate to use Expo CLI instead of @react-native-community/cli in any React Native project.
4---
5
6import { Terminal } from '~/ui/components/Snippet';
7import { Collapsible } from '~/ui/components/Collapsible';
8import { BoxLink } from '~/ui/components/BoxLink';
9import { DEMI } from '~/ui/components/Text';
10
11To migrate from `npx react-native 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.
12
13## Install the `expo` package
14
15In most cases, executing the following command in a project directory to install the package is all you need to do:
16
17<Terminal cmd={['npx install-expo-modules@latest']} />
18
19For a detailed installation guide, see [Install Expo modules](/bare/installing-expo-modules).
20
21## Why Expo CLI instead of `npx react-native`
22
23Expo CLI commands provide several benefits over the similar commands in `@react-native-community/cli`, which includes:
24
25- Instant access to Hermes debugger with <kbd>j</kbd> keystroke.
26- The debugger ships with React Developer Tools (`react-devtools`) already installed.
27- [Continuous Native Generation (CNG)](/workflow/continuous-native-generation/) support with [`expo prebuild`](/workflow/prebuild/) for upgrades, white-labeling, easy third-party package setup, and better maintainability of the codebase (by reducing the surface area).
28- Support for file-based routing with [`expo-router`](/routing/introduction/).
29  - [Async bundling](/router/reference/async-routes) in development.
30- Built-in [environment variable support](/guides/environment-variables) and **.env** file integration.
31- View native logs directly in the terminal alongside JavaScript logs.
32- 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.
33- [First-class TypeScript support](/guides/typescript).
34- Support for **tsconfig.json** aliases with `paths` and `baseUrl` [built-in to Metro](/guides/typescript#path-aliases).
35- [Web support](/guides/customizing-metro/#adding-web-support-to-metro) with Metro. Fully typed for React Native Web.
36- Modern [CSS support](/versions/latest/config/metro#css) with Tailwind, PostCSS, CSS Modules, SASS, and more.
37- Static site generation with Expo Router and Metro web.
38- Out of the box [support for monorepos](/guides/monorepos).
39- Support for Expo tooling such as [`expo-dev-client`](/develop/development-builds/introduction), the [Expo Updates protocol](/technical-specs/expo-updates-1) and [EAS Update](/eas-update/introduction).
40- Automated `pod install` execution when using `npx expo run:ios`.
41- `npx expo install` selects compatible dependency versions for well-known packages.
42- 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.
43- Android or iOS device launch selection shortcuts using <kbd>Shift</kbd> + <kbd>a</kbd> or <kbd>Shift</kbd> + <kbd>i</kbd> from the interactive prompt.
44- Built-in support for serving your app over an [ngrok tunnel](/develop/development-builds/development-workflows/#tunnel-urls).
45- Develop on any port with any entry JavaScript file.
46
47We 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
48Windows and macOS. If building for these platforms, you can utilize Expo CLI for the supported platforms and `@react-native-community/cli` for the others.
49
50## Compile and run your app
51
52After 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`:
53
54<Terminal cmd={['# for Android', 'npx expo run:android', '', '# for iOS', 'npx expo run:ios']} />
55
56When 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.
57
58## Start the bundler independently
59
60`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.
61
62> For SDK 48 and lower, use the `npx expo start --dev-client` command to start the bundler when using a development build or having `expo-dev-client` library installed in your project.
63
64## Common questions
65
66<Collapsible summary="Can I use Expo CLI without installing the Expo Modules API?">
67
68Expo Modules API is also installed when you install the `expo` package with `npx install-expo-modules`. If you want to try out Expo CLI for now without installing Expo Modules API, install the `expo` package with `npm install` and then configure the **react-native.config.js** to exclude the package from autolinking:
69
70```js react-native.config.js
71module.exports = {
72  dependencies: {
73    expo: {
74      platforms: {
75        android: null,
76        ios: null,
77        macos: null,
78      },
79    },
80  },
81};
82```
83
84> **Note:** Without Expo API Modules installed, certain features such as `expo-dev-client` or `expo-router` are unavailable.
85
86</Collapsible>
87
88<Collapsible summary="Can I use prebuild for out-of-tree platforms, such as macOS or Windows?">
89
90Yes! Refer to the [Customized Prebuild Example repository](https://github.com/byCedric/custom-prebuild-example) for more information.
91
92</Collapsible>
93
94## Next steps
95
96Now, 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:
97
98<BoxLink
99  title="Expo CLI Reference"
100  description="Learn more about the commands and flags available in Expo CLI."
101  href="/more/expo-cli"
102/>
103<BoxLink
104  title="Adopt Prebuild"
105  description={
106    <>
107      Automate your native directories using the <DEMI>app.json</DEMI>.
108    </>
109  }
110  href="/guides/adopting-prebuild"
111/>
112<BoxLink
113  title="Use Expo SDK"
114  description="Try out libraries from the Expo SDK in your app."
115  href="/versions/"
116/>
117<BoxLink
118  title="Expo Router"
119  description="Expo Router brings the best routing concepts from the web to native Android and iOS apps."
120  href="/routing/introduction/"
121/>
122