This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Using Bun
Edit page
A guide on using Bun with Expo and Expo Services.
Bun is a JavaScript runtime and a drop-in alternative for Node.js. In Expo projects, Bun can be used to install npm packages and run Node.js scripts. The benefits of using Bun are faster package installation than npm, pnpm, or Yarn and at least 4x faster startup time compared to Node.js, which gives a huge boost to your local development experience.
2 requirements
2 requirements
1.
Install Bun to create a new app.
2.
A Node.js (LTS) version is still required for the bun create expo and
bun expo prebuild commands, which use npm pack to download project templates.
Start a new Expo project with Bun
To create a new project, run the command:
You can also run any package.json script with bun run:
To install any Expo library, you can use bun expo install:
Use Bun with Expo Build
Expo Build decides which package manager to use based on the lockfile in your codebase. If you want Expo Build to use Bun, run bun install in your codebase. This will create a Bun lockfile: bun.lock in Bun versions 1.2 and newer, or bun.lockb when using an older Bun. As long as one of these lockfiles is in your codebase, Bun will be used as the package manager for your builds. Make sure to delete any lockfiles generated by other package managers.
Customize Bun version on Expo Build
Bun is installed by default when using Expo Build. See the Android server images and iOS server images to learn which version of Bun is used by your build's image.
To use an exact version of Bun with Expo Build, add the version number in eas.json under the build profile's configuration. For example, the configuration below specifies Bun version 1.0.0 for the development build profile:
Trusted dependencies
Unlike other package managers, Bun does not automatically execute lifecycle scripts from installed libraries, as this is considered a security risk. However, if a package you are installing has a postinstall script that you want to run, you have to explicitly state that by including that library in your trustedDependencies array in your package.json.
For example, if you install packageA, which has a dependency on packageB and packageB has a postinstall script, you must add packageB in your trustedDependencies.
To add a trusted dependency in your package.json, add:
Then, remove your lockfile and re-install the dependencies:
Common errors
Expo Build fails when using Sentry and Bun
If you're using sentry-expo or @sentry/react-native, these depend on @sentry/cli, which updates source maps to Sentry during your build. The @sentry/cli package has a postinstall script which needs to run for the "upload source maps" script to become available.
To fix this, add @sentry/cli to your trusted dependencies array in package.json:
Expo Build fails with a runtime version mismatch when using patched dependencies
When Bun installs a package that has a patch in patchedDependencies, it writes an empty tag file named .bun-tag-<hash> in the package directory. The name of the tag file depends on the Bun version, so two Bun versions write different names for the same patch.
The fingerprint includes the tag file when the patched package is a native module or config plugin, in SDK 57 and earlier or with the strict preset in SDK 58 and later. If the fingerprint includes the tag file and Expo Build uses a different Bun version than your machine, the two fingerprints differ. With the fingerprint runtime version policy, the build then fails in the Configure expo-updates build phase with this error:
Runtime version calculated on local machine not equal to runtime version calculated during build.
To fix this, add the tag files to .fingerprintignore in your project root:
The leading **/ also matches tag files in a parent node_modules directory, such as at the root of a monorepo. You can also use the same Bun version on Expo Build as on your machine.