Nx with Expo

Expo is an open-source framework for apps that run natively on Android, iOS, and the web. In an Expo monorepo, Nx lets you share code across native and web targets while keeping builds and tests fast. Expo brings together the best of mobile and the web and enables many important features for building and scaling an app.

Expo is a set of tools built on top of React Native. The Nx Plugin for Expo contains generators for managing Expo applications and libraries within an Nx workspace.

Requirements

The @nx/expo plugin supports the following package versions.

Package	Supported Versions
`metro-config`	>= 0.82.0
`expo`	^53.0.0 \|\| ^54.0.0 \|\| ^55.0.0

Nx generators install the latest supported versions automatically when scaffolding new projects.

Setting up Expo

To create a new workspace with Expo, run the following command:

 npx create-nx-workspace@latest --preset=expo --appName=your-app-name

Installation

In any Nx workspace, you can install @nx/expo by running the following command:

nx add @nx/expo

This will install the correct version of @nx/expo.

How @nx/expo infers tasks

The @nx/expo plugin will create a task for any project that has an app configuration file present. Any of the following files will be recognized as an app configuration file:

app.config.js
app.config.ts
app.json

The directory must contain both package.json and metro.config.js. Nx treats the project as Expo when the app configuration has an expo key or package.json lists expo as a dependency or development dependency:

{
  "expo": {
    "name": "MyProject",
    "slug": "my-project"
  }
}

View inferred tasks

To view inferred tasks for a project, open the project details view in Nx Console or run nx show project my-project --web in the command line.

@nx/expo configuration

The @nx/expo/plugin is configured in the plugins array in nx.json.

{
  "plugins": [
    {
      "plugin": "@nx/expo/plugin",
      "options": {
        "startTargetName": "start",
        "serveTargetName": "serve",
        "runIosTargetName": "run-ios",
        "runAndroidTargetName": "run-android",
        "exportTargetName": "export",
        "prebuildTargetName": "prebuild",
        "installTargetName": "install",
        "buildTargetName": "build",
        "submitTargetName": "submit",
        "buildDepsTargetName": "build-deps",
        "watchDepsTargetName": "watch-deps"
      }
    }
  ]
}

Option	Default	Inferred behavior
`startTargetName`	`start`	Runs `expo start` continuously.
`serveTargetName`	`serve`	Runs `expo start --web` continuously.
`runIosTargetName`	`run-ios`	Runs `expo run:ios` continuously.
`runAndroidTargetName`	`run-android`	Runs `expo run:android` continuously.
`exportTargetName`	`export`	Runs and caches `expo export`, including its outputs.
`prebuildTargetName`	`prebuild`	Runs `expo prebuild`.
`installTargetName`	`install`	Runs `expo install`.
`buildTargetName`	`build`	Runs `eas build`.
`submitTargetName`	`submit`	Runs `eas submit`.
`buildDepsTargetName`	none	Name of an optional dependency build task.
`watchDepsTargetName`	none	Name of an optional dependency watch task.

Use include and exclude glob patterns on the plugin entry to scope inference. A target defaults plugin filter must use the exact identifier @nx/expo/plugin.

Wait for Metro to be ready

The inferred start and serve targets come with a readyWhen check. With it, a task can wait until Metro accepts connections instead of only until it has started. The check runs when the task runs, with the task's environment and options, and waits for the Metro port. The port comes from the --port flag, then RCT_METRO_PORT, then 8081. It reads RCT_METRO_PORT from the environment first, then from the project's .env files, such as .env.development, the way expo start loads them.

A dependent task waits for the check only when its dependsOn entry sets waitFor to ready. A readyWhen on the target in targetDefaults or in the project configuration replaces the inferred check, and null turns it off. For the other checks, see wait for a continuous task to be ready.

Creating applications

Add a new application to your workspace with the following command:

nx g @nx/expo:app apps/my-app

Start the application by running:

nx start my-app

Generating libraries

To generate a new library run:

npx nx g @nx/expo:lib libs/your-lib-name

Generating components

To generate a new component inside library run:

npx nx g @nx/expo:component libs/your-lib-name/src/your-component-name --export

Replace your-lib-name with the app's name as defined in your tsconfig.base.json file or the name property of your package.json

Using Expo

Start a development server

You can start a development server by running:

nx start <app-name>

Compile app locally

You can compile your app locally with run-ios and run-android commands:

iOS
Android

Compile for iOS:

nx run-ios <app-name>

Compile for Android:

nx run-android <app-name>

To run these commands, you need to have your development environment setup. To run an iOS app,it can only be run on a Mac, and Xcode must be installed. Similarly, to run an Android app, it requires Android Studio and Java to be installed and configured on your computer. Setup steps: https://reactnative.dev/docs/environment-setup.

Compile web assets

You can build your JavaScript bundle using Metro bundler by running:

nx export <app-name>

Compile for all platforms:

nx export <app-name> --platform=all

Compile for iOS:

nx export <app-name> --platform=ios

Compile for Android:

nx export <app-name> --platform=android

Compile for Web:

nx export <app-name> --platform=web

Generate native code

To generate native code, run:

nx prebuild <app-name>

Generate for all platforms:

nx prebuild <app-name> --platform=all

Generate for iOS:

nx prebuild <app-name> --platform=ios

Generate for Android:

nx prebuild <app-name> --platform=android

Install compatible npm packages

To install packages compatible with the current version of Expo, pass the package names after --:

nx install <app-name> -- <package-name>
nx install <app-name> -- <package-name-1> <package-name-2> <package-name-3>

Unlike npm's install command, this install command installs the exact version that matches the installed copy of Expo.

To check and fix package versions, run:

check
fix

Check which packages needed to be updated:

nx install <app-name> --check

Automatically update invalid packages versions:

nx install <app-name> --fix

Run an EAS build

Expo Application Services (EAS) are deeply integrated cloud services for Expo and React Native apps. EAS Build is a hosted service for building app binaries for your Expo and React Native projects.

To run an EAS build:

nx build <app-name>

In a workspace without package manager workspaces, the app's eas-build-pre-install script copies the root dependencies and lock file into the app on the build machine, so EAS installs the versions pinned at the workspace root. The app generator adds this script.

If you are not signed into an EAS account, run the following command to log in:

npx eas login

Submit an EAS build

EAS Submit is a hosted service for uploading and submitting your app binaries to the app stores. Since it's a hosted service, you can submit your app to both stores as long as you can run EAS CLI on your machine.

To submit an EAS build:

nx submit <app-name>

Testing projects

You can run unit tests with:

nx test <project-name>

Expo commands

Below table is a map between expo commands and Nx commands:

Expo Commands	Nx Commands
`expo start`	`nx start <app-name>`
`expo run:ios`	`nx run-ios <app-name>`
`expo run:android`	`nx run-android <app-name>`
`expo export`	`nx export <app-name>`
`expo prebuild`	`nx prebuild <app-name>`
`expo install`	`nx install <app-name>`
`eas build`	`nx build <app-name>`
`eas submit`	`nx submit <app-name>`

Set up CI for your Expo monorepo

In CI, Nx runs nx affected to rebuild and retest only the projects a change touches, and caches results to skip repeated work.

For a complete pipeline, see Set up CI.