@expo/cli

中文文档
58.1.21发布于 2026/11/17MITCommonJS构建来源已验证近 30 天下载 5889.3万

The Expo CLI

原始使用文档
文档目录7 节
  1. Design
  2. Format
  3. Environment
  4. Testing
  5. Unit Testing Guidelines
  6. E2E Testing Guidelines
  7. Coming from Expo CLI

Expo CLI

The fastest way to build and run universal React Native apps for Android, iOS, and the web

📚 Read the Documentation  •  Learn more on our blog  •  Contribute to Expo CLI

Discord

Expo on X   Expo on GitHub   Expo on Reddit   Expo on LinkedIn   Expo on LinkedIn

⭐️ Be sure to star the Expo GitHub repo if you enjoy using the project! ⭐️


The @expo/cli package is a CLI binary that should be used via the expo package, like npx expo start (or npx expo for short).

npx expo

⭐️ Be sure to star the Expo GitHub repo if you enjoy using the project!

Design

This CLI has the following purposes:

  • Be a minimal interface for starting a local development server that emulates a production EAS Updates server. The development server is the proxy between a native runtime (Expo Go, Dev Client) and a JS Bundler (Metro, Webpack).
    • To accomplish secure manifest signing for the web, like AsyncStorage or Permissions where both require https/SSL, we need an authenticated Expo account. This is the only reason we include the authentication commands login, logout, whoami, register. Standard web CLIs don't have authentication commands because they either don't set up https or they use emulation via packages like devcert.
  • Orchestrating various native tools like Xcode, Simulator.app, Android Studio, ADB, etc. to make native builds as painless as possible. run:ios, run:android commands.
  • Implementing a versioned prebuild command that can reliably work with a project for long periods of time. Prebuild is like a bundler for native code, it generates the android and ios folders based on the project Expo config (app.json).
    • npx expo config is auxiliary to npx expo prebuild and used for debugging/introspection.
  • Installing versioned libraries with npx expo install this is a minimal utility born out of pure necessity since versioning in React Native is hard to get right.

Contributing

To develop the CLI run (defaults to watch mode):

pnpm build

We highly recommend setting up an alias for the Expo CLI so you can try it in projects all around your computer. Open your .zshrc or other config file and add:

alias nexpo="/path/to/expo/packages/@expo/cli/build/bin/cli"

Then use it with nexpo like nexpo config. You can also set up a debug version:

alias expo-inspect="node --inspect /path/to/expo/packages/@expo/cli/build/bin/cli"

Then you can run it and visit chrome://inspect/#devices in Chrome, and press "Open dedicated DevTools for Node" to get a debugger attached to your process. When debugging the CLI, you'll want to disable workers whenever possible, this will make all code run on the same thread, this is mostly applicable to the start command, i.e. expo-inspect start --max-workers 0.

Format

  • Be sure to update the CHANGELOG.md with changes for every PR. You only need to add the message, our GitHub bot will automatically suggest adding your name and PR number to the diff.
  • End async functions with Async like runAsync. This is just how we format functions at Expo.
  • When throwing errors, always opt for CommandError instead of Error -- this helps with debugging and making the experience feel more coherent.
  • Utilize the unified Log module instead of console.log.
  • When logging with variables, utilize the following format Something happened (foo: bar, baz: foz).
    • Avoid other formats like Something happened: bar, foz or Something happened: foo=bar, baz=foz.
  • Main UI components like command names (expo start), arguments (--port), and --help messages should be modified internally, by the Expo team to ensure the developer experience is unified across Expo tooling. External contributions modifying these core aspects may be rejected.
  • Use the profile utility method with the EXPO_PROFILE=1 environment variable to measure execution time.
  • Avoid globals and singletons as these make testing harder and less predictable. The only global we have (at the time of writing this) is the isOffline boolean.

Environment

  • Always be cautious of the transitive size of dependencies. packagephobia is a great resource for determining if a package is lean. Try to minimize adding dependencies to the CLI.
  • We build the CLI using taskr + swc, this is partially inspired by Next.js' local CLI.
  • The build pipeline will inline the CLI version as an environment variable that is accessible anywhere in the CLI codebase. You can access it via process.env.__EXPO_VERSION instead of reading the local package.json at runtime.
  • Unlike the legacy global Expo CLI, this CLI is shipped with expo meaning the SDK Version is always present.
    • Reduce SDK specific tasks since only one SDK should be accounted for in a single version of @expo/cli.
    • The @expo/config method getConfig does not need the skipSDKVersionRequirement in any case since expo should always be installed. Ex: getConfig('...', { skipSDKVersionRequirement: true }); shouldn't be used.
  • Also unlike the global Expo CLI we can assume that node modules are always installed since this CLI should be used via a project's local node_modules folder.
    • This means we can't perform operations that upgrade the expo package as these may kill the running process. Features that need this pattern (like expo upgrade) should live in standalone global tools.

Testing

There are three testing scripts:

  • pnpm test: Controlled unit and integration tests
  • pnpm test:e2e: End to end testing for CLI commands
  • pnpm test:playwright: End to end testing for Expo SDK in general with the CLI

  • You can target a specific set of tests with the --watch flag. Example: pnpm test --watch config.
  • We use backticks for it blocks. Example it(works).
  • If a pull request is fully self-contained to the packages/@expo/cli/ folder (i.e. no pnpm-lock.yaml modifications, etc.) then most native CI tests will be skipped, making CI pass faster in PRs.

Unit Testing Guidelines

  • Use nock for network requests.
  • No top level describe blocks that wrap all the tests in a file.
  • When testing a function, pass the function to the describe block instead of a stringified function name:
    • describe(foobar, () => {}) instead of describe('foobar', () => {})
  • Use virtual fs via memfs whenever possible.
  • We have a lot of global module mocks already in place, consider them when writing tests.
  • GitHub Copilot can make writing tests a little less tedious.

E2E Testing Guidelines

  • E2E tests should be resilient and reliable, be sure to give them plenty of time for network requests.
  • When testing locally you had to have Bun installed.
  • When testing locally you should attempt to reuse node modules for faster results. In the npx expo prebuild and npx expo start commands for instance, we utilize a helper method that will default to reusing a project + node_modules when run locally. This can be toggled off to bootstrap a fresh project every time.
  • When bootstrapping test projects, utilize the temporary folder os.tmpdir() as this folder is automatically cleaned up when the computer restarts.

Coming from Expo CLI

TL;DR: expo-cli was 'make it work', whereas @expo/cli is 'make it right, make it fast'.

The legacy global expo-cli package was deprecated in favor of this versioned @expo/cli package for the following reasons:

  • expo-cli was too big and took way too long to install. This made CI frustrating to set up since you needed to also target global node modules for caching.
  • expo-cli worked for almost all versions of the expo package, meaning it was getting more complex with every release.
  • expo-cli combined service commands (like the legacy build, submit, publish) with project-level commands like expo start. We've since divided services into eas-cli and project commands into npx expo (@expo/cli). This structure is more optimal/faster for developers since they can install/update commands when they need them.
  • This CLI utilizes more Node.js standard features like $EDITOR instead of the custom $EXPO_EDITOR environment variable. Also transitioning away from $EXPO_DEBUG and more towards $DEBUG=expo:*. These types of changes make Expo CLI play nicer with existing tooling.
  • The DevTools UI has been deprecated to reduce the net installation size, minimize complexity, and make room for future debugging UIs (Hermes/v8 Chrome debugger).
  • The expo start:web and expo web commands have been rolled into npx expo start as we now lazily load platforms until the device requests them.
  • Other missing or beta features from expo-cli may still be getting migrated over to this new CLI. For a more comprehensive breakdown see the start command PR.

版本与发布记录

@expo/cli 共发布 555 个版本,首次发布于 2022/03/24;过去 12 个月发布了 214 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
58.1.21latest2026/11/17今天
57.0.342026/11/125 天前
58.1.202026/11/115 天前
57.0.332026/11/0512 天前
58.1.192026/11/0413 天前
58.1.182026/10/3117 天前

其他发布通道:sdk-50 → 0.17.7,sdk-53 → 0.24.24,sdk-52 → 0.22.28,canary-sdk-55 → 55.0.13-canary-20260429-a5e59cf,canary-sdk-56 → 56.1.13-canary-20260701-9100865,canary → 58.0.0-canary-20260909-ea7a89a。

关于 @expo/cli 的常见问题

@expo/cli 是什么?

The Expo CLI

如何安装 @expo/cli?

在项目目录运行 npm install @expo/cli,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:expo(*)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。它还提供命令行工具 expo-internal,可以用 npx expo-internal 直接运行。

@expo/cli 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/expo__cli 是否存在。

@expo/cli 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@expo/cli 可以商用吗?

@expo/cli 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@expo/cli 的下载量有多少?

根据 npm 官方下载统计,@expo/cli 在 2026/10/14 – 2026/11/12 这 30 天内被下载 58,892,669 次,日均约 1,963,089 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@expo/cli 还在维护吗?

最新版本 58.1.21 发布于 2026/11/17(今天);至今共发布 555 个版本,其中过去 12 个月发布了 214 个;首次发布于 2022/03/24。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。