## Intro Expo is a framework that wraps React Native and provides a curated set of tools and services to build, deploy, and iterate on mobile apps faster. For developers, DevOps consultants, and technical startup teams, understanding Expo architecture means more than staying on the happy path. It means being able to answer concrete questions before and after a change: which Expo SDK and runtime version are installed, where does configuration live, how do different components interact, and what do you do when a build, bundle, or update fails? This guide walks through a practical implementation workflow. Each section follows the same operational pattern: name the component, state the supported version range and prerequisites, capture the current state with a read-only command, make the smallest justified change, and verify the outcome. Examples use placeholder values such as my-app , project-name , and your-org instead of real credentials, tokens, or production identifiers. The goal is operational safety: observe before changing, limit the blast radius, protect secrets, verify results, and define recovery before an incident forces a decision. ## Version and Environment Inventory Before touching configuration or code, establish what you are running. The first step is a read-only inventory of the installed Expo CLI, the project SDK version, and the runtime environment. This creates a baseline you can roll back to if a later change causes unexpected behavior. For a typical Expo project, start by checking the globally installed Expo CLI version: npx expo --version Expected output for Expo SDK 49 in late 2023 is 0.11.7 or similar. If you see a much older version such as 0.3.5 , update the CLI before proceeding because newer project templates and commands may not be available. Next, inspect the project itself. In the project root, run: npx expo config --type public This prints the resolved public app configuration, including the expo field from app.json or app.config.js . Look for the sdkVersion value. For a project created with create-expo-app in SDK 49, you should see "sdkVersion": "49.0.0" . If the project is older, for example SDK 46, plan an incremental upgrade path rather than jumping multiple versions. Also record the installed Node.js version because Expo CLI has a supported range. For SDK 49, Node.js 16 or newer is required. Check with: node --version A version below the supported range often produces cryptic ESM or dependency errors during package installation, so fix Node first. Capture the current state and timestamps before making any change. For example, save the output of the commands above to a log file with a date stamp: { echo "Inventory $(date -u +%Y-%m-%dT%H:%M:%SZ)"; echo "CLI: $(npx expo --version)"; echo "Node: $(node --version)"; echo "Project config:"; npx expo config --type public; } > inventory-$(date +%Y%m%d).txt This log is useful when reporting issues or rolling back. Never redirect output into a file that is committed to the repository if it contains sensitive values from environment variables or extra fields. The public config command intentionally omits secrets by default, but always review before sharing. Prerequisites: Node.js within the supported range for the target SDK, Expo CLI installed globally or via npx , and the project directory with a valid package.json and app.json or app.config.js . Blast radius: Read-only inventory changes nothing. The only risk is misreading an environment variable or accidentally running a command from the wrong directory. Always run pwd and ls first to confirm you are in the project root. Verification: The inventory is successful if the CLI version, project SDK version, and Node version all match the documented supported ranges for the tools you plan to use. For example, if you intend to use EAS Build, the CLI version must be at least the one bundled with the EAS CLI, typically the latest. Recovery: If the inventory reveals a mismatch, do not proceed with changes. Install the correct Node version using a version manager like nvm , update the Expo CLI with npm install -g expo-cli@latest , or migrate the project SDK version following the official upgrade guide. ## Safe Configuration Path Expo configuration is split across multiple files and layers. The primary source of truth is app.json or app.config.js in the project root. Dynamic configuration can also be provided via app.config.ts or an app.config.js that exports a function. The configuration is resolved at build time, and the result is used by Expo Go, EAS Build, and other tools. A safe configuration path means knowing which file to edit, which environment to change, and how to verify that the change took effect without breaking other environments. The smallest justified change is often a single field update, such as adding an iOS bundle identifier or changing the app name. A larger change, such as enabling a new plugin, requires a review of the plugin's prerequisites and side effects. ### Configuration file structure A minimal app.json for a new Expo project looks like this: { "expo": { "name": "My App", "slug": "my-app", "version": "1.0.0", "orientation": "portrait", "icon": "./assets/icon.png", "userInterfaceStyle": "light", "splash": { "image": "./assets/splash.png", "resizeMode": "contain", "backgroundColor": "#ffffff" }, "assetBundlePatterns": ["**/*"], "ios": { "supportsTablet": true, "bundleIdentifier": "com.example.myapp" }, "android": { "adaptiveIcon": { "foregroundImage": "./assets/adaptive-icon.png", "backgroundColor": "#ffffff" }, "package": "com.example.myapp" }, "web": { "favicon": "./assets/favicon.png" } } } The slug is used for the Expo project URL and should be URL-friendly. The bundleIdentifier and package must be unique if you plan to submit to the stores. Changing these values later is possible but requires careful coordination with store listings, so choose them early and follow a naming convention such as reverse domain: com.yourorg.appname . ### Safe change example: update app name A frequent small change is updating the display name of the app. In app.json , locate the "name" field and change it from "My App" to "My App - Staging" for a staging build. Before editing, create a backup of the current file: cp app.json app.json.bak After editing, run the configuration resolver to see the effective configuration: npx expo config --type public Verify that the output contains the new name under "name" . If it does not, check for a dynamic config file ( app.config.js or app.config.ts ) that may override app.json . Prerequisites: The project must have a valid app.json or app.config.js . If both exist, the dynamic file takes precedence, and the static file is used as the default export. Blast radius: Changing the name field affects the user-visible app name in all builds going forward. It does not affect the slug, bundle identifiers, or package name, so existing builds and store listings remain valid. However, if you change the slug accidentally, you may break deep links and the Expo project association. Verification: Run npx expo config --type public and check the resolved name field. Also run npx expo start and open the app in Expo Go to see the updated name on the home screen. For a build, run eas build --profile preview and install the resulting binary to confirm the name change. Recovery: If the change causes issues, restore from backup: cp app.json.bak app.json . Then re-run the config command to confirm the rollback. ### Using environment variables safely Expo supports environment variables through .env files and the EXPO_PUBLIC_ prefix for variables that should be embedded in the client bundle. For example, to set an API endpoint that is safe to expose, create a .env file in the project root: EXPO_PUBLIC_API_URL=https://api.example.com Then reference it in your code: const apiUrl = process.env.EXPO_PUBLIC_API_URL; console.log('API URL:', apiUrl); After adding or changing .env , restart the development server with cache clearing: npx expo start --clear Warning: Never put secrets such as API keys, tokens, or passwords in EXPO_PUBLIC_ variables. Those values are visible in the app bundle and can be extracted by end users. For secrets, use EAS secrets or server-side proxy. ### Configuration checklist - [ ] Backup the existing config file before editing. - [ ] Decide whether the change belongs in app.json or app.config.js . - [ ] Use placeholders for secrets and environment-specific values. - [ ] Run npx expo config --type public to review the resolved configuration. - [ ] Test on a simulator or device after the change. - [ ] If the change is for a specific build profile (e.g., staging), use eas.json and environment-specific config via app.config.js . Owner and review cadence: The configuration owner should be a specific engineer, for example the mobile lead, who reviews configuration changes weekly via a pull request process. Major config changes (new plugins, permission additions) should be discussed in a monthly architecture review. ## Verification and Diagnostics Verification means proving that the system is working as expected. In Expo, this often involves starting the development server, building the app, or running diagnostics to identify configuration or dependency issues. Diagnostics is the process of isolating the cause when something goes wrong. ### Basic development server verification The most common verification is starting the Metro bundler: npx expo start Expected output includes a QR code and a list of keyboard shortcuts. If the QR code does not appear, the server may not have started due to a port conflict or missing dependencies. Check the terminal for errors such as EADDRINUSE or Cannot find module . To verify that the app actually loads in a simulator, press i for iOS simulator or a for Android emulator. If the app crashes or shows a red error screen, capture the error message and stack trace. For example, a common error is "Unable to resolve module 'react-native-vector-icons'" which indicates a missing dependency. ### Running diagnostics with expo-doctor Expo provides expo-doctor to diagnose common project issues. Run it from the project root: npx expo-doctor Expected output includes a list of checks, for example: - Checking package versions - Checking project structure - Checking for duplicate dependencies If issues are found, expo-doctor prints specific recommendations. For example, it may report that a package version is incompatible with the installed Expo SDK and suggest a fix such as npx expo install --fix . ### Verifying builds with EAS For cloud builds, use EAS CLI to submit a build and then check the status. After configuring eas.json , run: eas build --platform android --profile preview The command returns a build ID and a URL to monitor progress. To check the status later: eas build:list --platform android Look for the build status finished or errored . If errored , click the build URL to view logs. Common errors include invalid credentials, missing environment variables, or native module compatibility issues. ### Diagnostic workflow example: app crashes on startup - Start the development server with npx expo start . - Open the app on a simulator and observe the error. - If the error is a JavaScript exception, read the stack trace. Note the module and line number. - Check if the module is listed in package.json and installed. Run npm ls to see the installed version. - Compare the version with the Expo SDK compatibility list using npx expo install --check . - If a version mismatch is found, run npx expo install to install the compatible version. - Restart the server with npx expo start --clear and retest. Owner and review cadence: Diagnostic runbooks should be maintained by the release engineer or platform lead. After every incident, the runbook should be updated within one week, and a postmortem review should be held monthly to identify recurring failure patterns. ## Failure Modes and Recovery Even with careful planning, failures happen. This section describes common failure modes in Expo projects and provides recovery steps. The key is to isolate the failure domain: JavaScript bundle, native build, configuration, or infrastructure. ### Failure mode 1: Metro bundler fails to start Symptom: Running npx expo start exits with an error such as Error: listen EADDRINUSE: address already in use :::8081 . Cause: Another process is using the default Metro port 8081. Recovery: Find the process using the port and kill it, or start Expo on a different port. On macOS and Linux, find the process ID: lsof -i :8081 Kill the process: kill -9 On Windows, use netstat -ano | findstr :8081 to find the PID, then taskkill /PID /F . Alternatively, start Expo with a different port: npx expo start --port 8082 Then open the app in Expo Go by scanning the new QR code. ### Failure mode 2: Missing module error Symptom: The app shows a red screen: Unable to resolve module 'some-module' . Cause: The module is not installed or not listed in package.json . Recovery: Install the module using Expo's compatible version resolver: npx expo install some-module Then restart the bundler with npx expo start --clear . If the module is a custom local module, ensure the path is correct and the file exists. ### Failure mode 3: Build fails due to invalid credentials Symptom: EAS Build fails with an error like Authentication with Apple Developer Portal failed or Invalid Google Service Account credentials . Cause: The credentials stored in EAS are expired, revoked, or have insufficient permissions. Recovery: Update the credentials using EAS CLI. For iOS, run eas credentials and select the appropriate option to update the Apple credentials. For Android, if using a Google Service Account JSON, upload a new valid JSON: eas credentials --platform android Follow the prompts to replace the service account. After updating, resubmit the build. ### Failure mode 4: App runs in Expo Go but fails in production build Symptom: The app works in development but crashes or behaves differently in a standalone build. Cause: Difference in environment (e.g., missing environment variables, different API endpoints, or native module not included). Recovery: Compare the production build's configuration with the development configuration. Run: npx expo config --type public Check that environment variables are set correctly for production. If using EAS Build, verify that secrets are available in the build profile. Look at the build logs for errors. Also, test the production bundle locally using the --no-dev --minify flags: npx expo start --no-dev --minify This mimics the production JavaScript bundle and can reveal issues like missing polyfills or minification problems. ### Recovery checklist - [ ] Capture the exact error message and timestamp. - [ ] Identify the failure domain (JS, native, config, infra). - [ ] Search official Expo GitHub issues and forums for matching errors. - [ ] Apply the smallest fix that addresses the root cause. - [ ] Verify the fix in a staging environment first. - [ ] Document the incident and update runbooks within one week. ## Operations Checklist This checklist summarizes the operational tasks needed to keep an Expo project healthy. Each item includes a concrete command or step and a verification signal. Assign each task to a specific owner and set a review cadence, for example weekly or before each release. ### Weekly operations - Dependency health check: Run npx expo install --check to verify package versions. Expected output is a list of packages with versions that match SDK compatibility, or a warning for mismatches. Owner: lead developer. Review: every Monday. - Upgrade review: Check the latest Expo SDK version with npm view expo version . Compare with the project's SDK version. If a newer SDK is available, plan an upgrade within two weeks. Owner: platform engineer. Review: monthly. - Config drift check: Run npx expo config --type public and compare the output with the last known good config stored in a secure location. Any unexpected difference should be investigated. Owner: DevOps engineer. Review: weekly. - Secret rotation: List EAS secrets with eas secrets list (if available) and review which are still needed. Rotate any secret older than 90 days. Owner: security lead. Review: quarterly. ### Pre-release operations - Environment variable verification: Ensure all required EXPO_PUBLIC_ variables and EAS secrets are set for the release profile. Command: eas env:list --environment production (if using EAS environment variables). Owner: release manager. Review: before every release. - Build from clean checkout: Clone the repository into a fresh directory and run npm ci && npx expo prebuild --clean && eas build --profile production --platform all . This catches issues caused by local machine state. Owner: CI/CD engineer. Review: before every release. - Store metadata validation: Run eas submit --platform ios --latest --dry-run (if EAS Submit dry-run is supported) to validate credentials and metadata. Owner: release manager. Review: before submission. ### Post-release operations - Monitor crash reports: Integrate a crash reporting tool such as Sentry or Bugsnag and check the dashboard within 24 hours of release. Owner: mobile developer on rotation. Review: daily for first week, then weekly. - Rollback readiness: If a release causes critical issues, have a plan to roll back using EAS Update or a previous store build. Document the rollback command, e.g., eas update --branch production --message "Rollback to stable" . Owner: release engineer. Review: after every release. ### Owner and review cadence Each checklist item should have a single accountable owner, not a group. For example, the dependency health check is owned by Alice (lead developer), and the secret rotation is owned by Bob (security lead). The entire checklist should be reviewed in a monthly operations meeting attended by the owners. Adjust frequencies based on team size and risk tolerance. ## Common Pitfalls and How to Avoid Them ### Pitfall 1: Mixing app.json and app.config.js inconsistently Why it happens: Teams start with a static app.json , then add dynamic logic in app.config.js but forget to remove or update the static file. The dynamic config may override or merge unexpectedly. How to avoid: Choose one source of truth. If you need dynamic configuration, delete app.json and keep all configuration in app.config.js or app.config.ts . Document the decision in the README. Recovery: If you find both files, run npx expo config --type public and compare with your intended configuration. Remove the static file if it is not used, or update it to match the dynamic defaults. ### Pitfall 2: Committing secrets to the repository Why it happens: Developers hardcode API keys or tokens in app.json or .env during development and forget to remove them before committing. How to avoid: Use a .gitignore that excludes .env and any files containing secrets. Use EAS secrets for production. For development, use environment variables that are not committed or use a local untracked file. Recovery: If a secret is committed, revoke the secret immediately, remove it from the repository history using a tool like git filter-repo , and rotate the credential. Then add a pre-commit hook to scan for secrets. ### Pitfall 3: Ignoring SDK compatibility when adding packages Why it happens: Developers run npm install for a package without checking if it works with the current Expo SDK. This can lead to native module mismatches and build failures. How to avoid: Always use npx expo install for packages listed in the Expo SDK reference. For third-party packages, check the compatibility table in the Expo documentation or the package's README. Recovery: If a package causes issues, remove it with npm uninstall , then reinstall with npx expo install . If the package is not supported, look for an alternative or use a development build. ### Pitfall 4: Not testing production builds before release Why it happens: Teams rely on Expo Go for testing, but Expo Go does not include custom native modules and may have different behavior. How to avoid: Use EAS Build to create a development build or preview build for testing. Test the exact production bundle locally with npx expo start --no-dev --minify . Recovery: If a production bug is found after release, use EAS Update to push a fix quickly for the JavaScript bundle, or submit a new store build if native changes are needed. ### Pitfall 5: Overlooking environment-specific configuration Why it happens: The same configuration is used for development, staging, and production, leading to wrong API endpoints or debug settings in production. How to avoid: Use app.config.js to conditionally set values based on the APP_ENV environment variable. Define eas.json build profiles for each environment and set the appropriate environment variables in EAS. Recovery: If a wrong environment is deployed, immediately update the environment variables via EAS and trigger a new build or update. Review the CI/CD pipeline to ensure the correct profile is used automatically. ## Conclusion Expo architecture is best understood through practical operations: inventory the environment, adjust configuration safely, verify with concrete commands, and recover from failures systematically. This guide has provided a version-scoped, observable, and reversible workflow that reduces the risk of changes and makes failures visible. The next step is to pick one low-risk verification from the operations checklist and perform it on a real project. Record the current state, run the documented check, compare the result with the expected signal, and document any discrepancy. Over time, these small verifications build a culture of operational safety. A reliable technical workflow protect sensitive values, limits changes to the intended resource, and defines recovery verification before an incident forces the decision. By following the patterns in this article, you can keep your Expo projects healthy and your team confident in every release.