Running your app

To build and run your app for any platform, run any of the following commands:

# These commands use the Expo CLI:
node --run ios
node --run android
node --run web

# These commands use the Expo Desktop CLI:
node --run macos
node --run windows

The Expo Desktop CLI commands are broadly used the same way as the expo run:ios and expo run:android commands.

Common arguments

• [PROJECT-ROOT]: This positional arg allows you to run the command in a different directory to the current working directory.
• --configuration: This option specifies whether to do a debug-mode build (--configuration Debug), which is the default; or a release-mode build (--configuration Release).
• --no-build-cache: Clear the native cache before building. Cache clearing is useful for profiling your build times.
  • On macOS, this is under the derived data directory. By default, this is found at ~/Library/Developer/Xcode/DerivedData.
  • On Windows, it runs msbuild.exe <solution> /t:Clean /p:Configuration=<Debug|Release> /p:Platform=<x86|x64|ARM64>. In practice, this cleans:
    • <app-root>/windows/<arch>/<configuration>
    • <app-root>/windows/MyApp/<arch>/<configuration>
    • Each referenced native module’s own intermediate/output directories
    • The MyApp.Package project’s output/intermediate locations
• --no-install: Skip installing dependencies. On macOS, this will also skip running npx pod-install if the dependencies field in the project's package.json has changed.
• --no-bundler: Skip starting the dev server. Enabled automatically if the dev server is already serving the app from a different process.
  This flag is currently ignored on run macos. Bug tracked in Issue #35.

• -o, --output <path>: Directory to copy the built app binary to after the build completes. Useful for CI/CD pipelines or when you want the binary in a predictable location.
• -p, --port <port>: Port to start the development server. Default: 8081. This is only relevant for development builds. Production builds will export the project and embed the files in the native binary before installing it.
• --binary <path>: File path to the binary to install. When this is provided, the build process will be skipped and the binary will attempt to be installed directly.

Running the macOS app (run macos)

The basic command is:

node --run macos
# or
npx expo-desktop run macos

Launching the app in the background (--background)

By default, the app launches in the foreground, meaning it will steal focus once launched. If you'd prefer that it launch in the background, you can override this behaviour like so:

node --run macos -- --background

Launching the app as a new instance (--no-single-instance)

By default, if an existing instance of the app is already open, it will be killed before another launch attempt is made. However, if you'd prefer that a separate instance of the app is launched without killing the existing one, you can override this behaviour like so:

node --run macos -- --no-single-instance

Setting the build scheme (--scheme <scheme>)

By default, the Expo Desktop CLI will automatically select the scheme for the Mac app. However, you can specify an explicit scheme to launch if preferred (e.g. if you have an App Extension to launch).

node --run macos -- --scheme MyAppExtension

Running the Windows app (run windows)

The basic command is:

node --run windows
# or
npx expo-desktop run windows

Setting the target architecture (--arch <architecture>)

By default, the app will target its own host architecture. But you can cross-compile by passing an explicit argument. Cross-compiling may require additional build tools (e.g. Microsoft Visual C++ for the target architecture).

# 64-bit x86 (the most common type of PC)
node --run windows -- --arch x64

# 64-bit ARM (native when running an ARM Windows VM on macOS)
node --run windows -- --arch ARM64

# 32-bit x86 (very old!)
node --run windows -- --arch x86

Opting out of multi-processor builds (--singleproc)

By default, the app will be built in parallel, using multiple processors. However, this can often cause out-of-memory issues on resource-constrained machines (e.g. CI runners) or on ARM64 architecture (where some build tooling is non-native). If you are facing such issues, it's worth opting out of multi-processor builds like so:

node --run windows -- --singleproc

Increasing log verbosity (--logging)

Runs msbuild.exe with -verbosity:normal instead of the default -verbosity:minimal. This flag does not support other verbosity levels.

node --run windows -- --logging

Skip launching the app after building it (--no-launch)

To build the app but not launch it, pass this flag:

node --run windows -- --no-launch

Skip autolinking the app before build (--no-autolink)

By default, the app is autolinked before each build. To skip autolinking, pass this flag:

node --run windows -- --no-autolink

Specify MSBuild properties (--msbuildprops <properties>)

Specify MSBuild properties in the format prop1=value1,prop2=value2. These will be passed to MSBuild as /property:prop1=value1;prop2=value2.

# Pass comma-separated key:value pairs to the Expo Desktop CLI:
node --run windows -- --msbuildprops "WarningLevel=2,OutDir=bin\Debug"

# They will be changed to semicolon-separated when passed to MSBuild:
msbuild.exe /property:WarningLevel=2;OutDir=bin\Debug …

Configure direct debugging (--direct-debugging <port>)

This flag was added to Expo Desktop because the underlying @react-native-windows/cli exposed it, but it turns out that it has no purpose anymore.

node --run windows -- --direct-debugging 8082

Disable telemetry (--no-telemetry)

By default, telemetry is sent when using the underlying @react-native-windows/cli. Pass this flag to disable it.

node --run windows -- --no-telemetry