development-builds

94 notes in this subject, read out of this brain and free to use. This is page 2 of 2.

bare-expo relationship to test-suite

bare-expo is a bare React Native app that links all Expo SDK dependencies in packages/ to run projects in apps/. It runs test-suite (an Expo app with custom code as a test runner) and native-component-list. When you run expo start in test-suite directory you can load it in Expo Go. bare-expo imports test-suite's app root component and uses it as its own root component.

Development environment does not support Windows

The development environment for the Expo repository does not support Windows; WSL is required to contribute from Windows.

Required tools for Expo SDK contribution

To contribute to Expo SDK development, install: direnv (brew install direnv on macOS, then install shell hook), Ruby 3.3 or later (brew install ruby@3.3 on macOS), Node LTS, and Bun (optional, required for some scripts but not most tasks).

Android setup for Expo development

For Android development, run pnpm run setup:native. This command downloads submodules (like react-native), ensures pnpm is installed, sets up React Native environment (installs Android NDK if not present), and downloads Node packages. Recommended JDK is version 17 (e.g., zulu17). Install with: brew tap homebrew/cask-versions && brew install --cask zulu@17. Add JAVA_HOME environment variable in ~/.bash_profile or ~/.zshrc: export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home. ANDROID_SDK_ROOT environmental variable should be set or configured via local.properties file in android folder of the native project.

Speed up Android native builds with ccache

To speed up Android native builds, install ccache (brew install ccache). Add to ~/.zshrc or ~/.bashrc: export CMAKE_C_COMPILER_LAUNCHER="ccache" and export CMAKE_CXX_COMPILER_LAUNCHER="ccache". Enable precompiled header support required by modules like expo-modules-core: ccache -o sloppiness=pch_defines,time_macros. The repo's .envrc automatically sets CCACHE_BASEDIR via direnv, sharing cache across git worktrees.

iOS setup requirements for Expo development

For iOS development, ensure Ruby 3.3 is installed (macOS comes with Ruby 2.6 which is not supported). Install with brew install ruby@3.3 if using Homebrew. Also install the latest stable version of Xcode and Xcode command line tools.

Verify native installation for Expo development

To verify native installation is successful, navigate to apps/bare-expo and run the project on any native platform: pnpm ios for iOS, pnpm android for Android, or pnpm android with TERMINAL environment variable set on Linux (e.g., export TERMINAL="konsole"). This runs test-suite app via bare-expo project.

Editing Expo SDK packages workflow

All Expo SDK packages are in packages/ directory and are automatically linked to apps/ projects. To edit: navigate to the package (e.g., cd packages/expo-constants), compile TypeScript after editing with pnpm build (if script exists), edit code in package's src/ directory, then test changes through bare-expo or test-suite app. For native changes, rebuild the native project. For JavaScript-only changes, run test-suite from apps/test-suite with expo start. Run full test suite with pnpm test:<android|ios>.

Common Expo package npm scripts

Expo packages expose these npm scripts orchestrated by Turborepo: build (compiles src/ → build/), typecheck (type-checks with tsc), test (runs Jest unit tests), lint (lints package, pass --fix to autofix), format (formats package, pass --check to check without modifying), depscheck (verifies declared dependencies match imports). Run from repo root with pnpm <script> to run across all packages respecting cache and dependency graph, or from single package with pnpm run <script>. Use et check-packages <...packages> for one-shot check on touched packages.

Test files location and platform-specific testing

Create unit tests in the appropriate package's src/__tests__ directory with *-test.ts or *-test.tsx extension. Run with pnpm test ensuring it handles all platforms (iOS, Android, web). Exclude unsupported platforms by using platform extensions like .test.ios.ts, .test.native.ts, .test.web.ts. Press X to select one platform at a time.

E2E testing in Expo development

Write E2E tests in apps/test-suite/tests using a non-feature-complete version of Jasmine that runs on Android and iOS clients (no snapshot testing). Add new test files in apps/test-suite/TestUtils.js. Add tests that run automatically from bare-expo testing in apps/bare-expo/e2e/TestSuite-test.native.js. Run tests locally from bare-expo directory with pnpm test:android or pnpm test:ios before pushing to CI.

Jest mocking for bridged native functions

Any new bridged native functions must be added to jest-expo package (packages/jest-expo/src/preset/expoModules.js) to ensure they are mocked. A tool and guide exist for this: Generating Jest Mocks in the repository guides.

Native code editing in bare-expo

Edit a package's native code directly from its folder in packages/ or by opening bare-expo in a native editor. From bare-expo directory, use pnpm edit:android for Android Studio or pnpm edit:ios for Xcode. Remember to rebuild the native project whenever making native changes.

Expo documentation setup and environment

Documentation is built with Next.js in the docs directory. Running docs pnpm commands requires a specific Node version found under volta section in ./docs/package.json. Navigate to docs directory, run pnpm install, then start with pnpm dev (ensure no other server runs on port 3002). Requires Node 22.13.1 or higher.

Updating Expo documentation

Navigate to docs directory, run pnpm install and pnpm dev. Edit docs in docs/pages/. If updating an older version, copy relevant changes to docs/pages/versions/unversioned/ for API docs. Package API docs are generated from sources: run et generate-docs-api-data -p <package-name> for next SDK version or et generate-docs-api-data -p <package-name> -s <number> for specific SDK version.

Git commit message format for Expo

Format commit messages as [platform][api] Title. For example, for a bug fix in expo-video for iOS: [ios][video] Fixed black screen bug that appears on older devices.

PR requirements before submitting to Expo

Before submitting PR: add concise description of user-facing changes to CHANGELOG.md in changed package or root's CHANGELOG.md if changes don't apply to specific package (especially for breaking changes). Run et check-packages (or pnpm build, pnpm typecheck, pnpm test, pnpm lint, pnpm format) for changed packages. Run pnpm lint --fix and pnpm format. Remove all console.log statements and commented code blocks. For docs changes, copy changes to unversioned copy and ensure links aren't broken and format is correct.

Expo repository review scope

Expo currently reviews PRs for packages/, docs/, templates/, guides/, apps/, and markdown files.

Native component list for manual smoke testing

Manual smoke tests are included in apps/native-component-list, which is a good fit for demos or tests requiring physical interactions, particularly useful for testing UI component interactions or verifying difficult-to-automate scenarios through manual interaction.

Expo style guides for contributing

All modules should adhere to: Expo Module Infrastructure style guide, Expo JS Style Guide (mostly applies to TypeScript), Expo Swift Style Guide, and Updating Changelogs guide.

React Native fork in Expo repository

Expo uses a fork of react-native located at react-native-lab/react-native. This fork diverges minimally from the react-native version in its package.json and can be modified or have cherry-picks applied.

expo-module-scripts for build tooling

Expo uses expo-module-scripts, a unified set of basic Bash scripts and configs, to ensure everything runs smoothly including TypeScript, Babel, Jest, etc.

iOS Developer Mode requirement

Devices running iOS 16 or above require enabling OS-level Developer Mode before running development builds. This requirement applies to: - Internal distribution builds (including those built with EAS) - Local development builds after installation Exceptions: - Builds signed using enterprise provisioning - Any builds installed on an iOS Simulator

Sandbox app purpose and setup

The sandbox app in the expo repository is a blank app configured with yarn workspaces to use local working copies of expo-sdk and all universal modules. It is designed for quickly testing something you are developing locally.

Sandbox app requires custom App.js

The sandbox app requires you to add an App.js file locally. Everything in the sandbox folder other than already committed files is ignored. The easiest way to create the App.js is to copy it from the blank project template.

Expo Go SDK version compatibility requirement

Each build of Expo Go supports one SDK version. The project and Expo Go SDK versions must match. On Android device, Android Emulator, or iOS Simulator, install a compatible version from expo.dev/go or use the expo-go CLI. On a physical iPhone or iPad, projects using SDK 55 or later can install a compatible build from sign.expo.dev.

Expo Go no server-side middleware support

Expo Go does not handle server-side middleware. This is a limitation of the Expo Go environment as a client-side playground application.

Expo Go vs development builds comparison

Expo Go is a playground app for students and learners to get started quickly with a fixed set of native libraries built in. A development build is a fully featured development environment for working on production-grade Expo apps. Expo Go is a pre-built native app that cannot be changed after installation.

Native app and JavaScript bundle roles

The native app is what you install on your device. Expo Go is a pre-built native app that works like a playground and cannot be modified after installation. To add new native libraries or change app name and icon, you need to build your own native app. The JavaScript bundler (expo start) contains your app's UI code and business logic. In production, there is one main.js bundle shipped with the app. In development, the JS bundle is live reloaded from your local machine. React Native provides a way for JavaScript code to access native APIs such as Image, Camera, and Notifications. Only APIs and libraries bundled in the native app can be used.

Libraries with native code not in Expo Go

Libraries that contain native code but are not included in Expo Go cannot be used in Expo Go. For example, react-native-firebase includes native code that does not exist in the Expo Go bundle. When you try to use such a library, the JS code will error immediately when it tries to call the native code because there is no way to get the native code into the Expo Go app unless it was already included in the bundle uploaded to the app stores. In contrast, libraries that are included in Expo Go like react-native-webview will work because the native code was already bundled with the app.

App icon, name, and splash screen testing limitations in Expo Go

Native assets like app icon, name, and splash screen are shipped with the native bundle and are immutable once the app is installed. These cannot be tested in Expo Go during development, though you can build a store version that will use the provided values and images. Expo Go shows a dev-only emulation of a splash screen with your app icon on a solid color background, but this is limited and does not support features like SplashScreen.setOptions for animating the splash screen.

Remote push notifications not available in Expo Go

While in-app notifications are available in Expo Go, remote push notifications (sending a push notification from a server to the app) are not available in Expo Go. This is because a push notification service must be tied to your own push notification certificates. It is recommended to test remote push notifications in development builds to ensure parity in behavior between development and production.

App Links and Universal Links require native app modifications

Both Android App Links and iOS Universal Links require a two-way association between the native app and the website, including the native app including the linked website's URL. This is impossible with Expo Go due to the native code immutability of the Expo Go app.

Development build contains expo-dev-client

A development build is a debug version of a project optimized for quick iterations when creating an app. It contains the expo-dev-client library/package, which offers a robust and complete development environment. This setup allows integrating any native library or changing code inside native directories as required. A development build is an evolution of Expo Go that does not have Expo Go's limitations and can be customized to your application's needs. It is the recommended approach for building production-grade apps with Expo.

Give your agent this brain