Running Expo on Devin

devin-expo.md

Devin can build, test, and iterate on Expo and React Native apps. This guide walks through how to configure Devin's environment so it's ready to work on your Expo project from the first session.

Why Expo works well with Devin

Expo provides a managed workflow that simplifies React Native development. For Devin, the key advantage is Expo's web preview — Devin can run your app in its built-in browser without needing a physical device or emulator. This means Devin can visually verify UI changes, test navigation flows, and debug layout issues during a session.

---

Setting up your Expo repo

1. Add the repository

First, make sure Devin has access to your repo via Settings > Integrations. Then go to Settings > Devin's Machine and add your Expo repository.

2. Install dependencies

In the Install Dependencies step, use the package manager your project uses:

# npm (default for most Expo projects)
npm install

# yarn
yarn install

# pnpm
pnpm install

If your project uses a specific Node.js version, install it first:

nvm install 20
nvm use 20
npm install

3. Maintain dependencies

In the Maintain Dependencies step, use the same install command. Optionally add npx expo install --check to fix any mismatched dependency versions:

npm install
npx expo install --check

4. Set up lint

If your project uses ESLint (most Expo projects created with create-expo-app include it):

npx expo lint

Or if you have a custom lint script in package.json:

npm run lint

5. Set up tests

Most Expo projects use Jest via jest-expo:

npm test

6. Run the local app

This is where Expo shines for Devin. Use the web preview so Devin can interact with your app in its browser:

npx expo start --web

The `--web` flag launches the app in Devin's browser, which is the easiest way for Devin to visually verify changes. If you need platform-specific testing, see the [native builds](#working-with-native-builds) section below.

7. Additional notes

Add any project-specific context Devin should know. For example:

- This project uses Expo Router for file-based navigation
- The app connects to a staging API at https://api.staging.example.com
- Use the test account: test@example.com (password stored in secrets)
- Run `npx expo start --web` to preview UI changes in the browser

---

Environment variables

If your Expo project uses environment variables (e.g., via .env files with expo-env), you have two options:

Option A: Use Devin secrets + direnv

Store sensitive values as Secrets and reference them in a .envrc file:

# .envrc in your repo root
export EXPO_PUBLIC_API_URL="https://api.staging.example.com"
export EXPO_PUBLIC_ANALYTICS_KEY="$ANALYTICS_KEY"  # references a Devin secret

Then run direnv allow in the terminal during environment setup.

Option B: Use an .env file

Create a .env file in the repo root during environment setup:

EXPO_PUBLIC_API_URL=https://api.staging.example.com
EXPO_PUBLIC_ANALYTICS_KEY=your-key-here

Add `.env` to your `.gitignore` so Devin doesn't accidentally commit secrets to the repository.

---

Testing on your mobile device

You don't have to rely solely on the web preview — Devin can share the Expo development server URL so you can open the app on your physical device using the Expo Go app.

When Devin runs npx expo start, the terminal outputs a QR code and an exp:// URL. Ask Devin to share that URL or QR code in the session chat, and you can scan it with the Expo Go app on your phone to see the app running live.

Example prompt:

Run npx expo start and share the Expo QR code and URL with me so I can test on my phone.

Your mobile device must be on the same network as Devin's machine, or you can use tunnel mode: `npx expo start --tunnel`. Tunnel mode routes traffic through Expo's servers so your device can connect from any network. Note that `--tunnel` requires `@expo/ngrok` — Devin will install it automatically if it's not already present. This is a great workflow for reviewing UI changes in real time: Devin makes changes, and you see them update live on your device via Expo's fast refresh.

---

Working with Expo Router

If your project uses Expo Router, Devin can navigate directly to specific routes via URL in its browser. This is useful for testing specific screens without clicking through the app:

http://localhost:8081/settings
http://localhost:8081/profile/123

Add a note in the Additional Notes step telling Devin about your route structure so it can navigate efficiently.

---

Working with native builds

For projects that use native modules or require a development build, additional setup is needed.

Expo prebuild (bare workflow)

If your project uses native modules that aren't supported in Expo Go, run prebuild during environment setup:

npx expo prebuild

Android development builds

To run Android builds on Devin's machine, you'll need the Android SDK:

# Install during environment setup
sudo apt-get update && sudo apt-get install -y openjdk-17-jdk

Set the required environment variables in ~/.bashrc:

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools

For most Expo projects, the web preview (`npx expo start --web`) is sufficient for Devin to verify UI changes. Only set up Android builds if your project requires platform-specific native testing.

EAS Build (cloud builds)

If you use EAS Build for production builds, install the EAS CLI and store your Expo token:

# Install EAS CLI during environment setup
npm install -g eas-cli

Add your EXPO_TOKEN as a Secret so Devin can trigger cloud builds:

eas build --platform android --profile preview --non-interactive

---

Example prompts

Here are some effective prompts for working with Expo projects:

UI changes:

Add a dark mode toggle to the settings screen. Use the existing theme context at src/contexts/ThemeContext.tsx. Run npx expo start --web and verify the toggle works in the browser.

New feature:

Create a new "Notifications" tab using Expo Router. Add it to the bottom tab navigator in app/(tabs)/_layout.tsx. The screen should fetch notifications from the /api/notifications endpoint and display them in a FlatList.

Bug fix:

The login form on the auth screen doesn't show validation errors. Check app/(auth)/login.tsx and fix the form validation. Test by running the web preview and trying to submit with an empty email field.

Testing:

Add unit tests for the useAuth hook in src/hooks/useAuth.ts. Use jest-expo and mock the AsyncStorage calls. Run npm test to verify they pass.

---

Troubleshooting

Node.js version mismatch

If you see warnings like EBADENGINE Unsupported engine during npm install, your Expo project's dependencies require a newer version of Node.js than what's installed on Devin's machine. For example:

npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: 'eslint-visitor-keys@5.0.1',
npm warn EBADENGINE   required: { node: '^20.19.0 || ^22.13.0 || >=24' },
npm warn EBADENGINE   current: { node: 'v22.12.0', npm: '10.8.3' }
npm warn EBADENGINE }

To fix this, update Node in the Install Dependencies step before running npm install:

nvm install 22
nvm use 22
npm install

You should also add the nvm use command to your Maintain Dependencies step so the correct version is used every session:

nvm use 22
npm install

Check your project's `package.json` for an `engines` field to see which Node version is required. Alternatively, if the project includes an `.nvmrc` or `.node-version` file, use `nvm install` and `nvm use` without a version number — it will pick up the correct version automatically.

Git working directory not clean after npm install

If the repo setup fails with ERROR: Git working directory was not clean in the end, it means npm install modified tracked files — most commonly package-lock.json. This happens when the lockfile was generated with a different npm version or when Expo postinstall scripts modify project files.

Quick fix — add git checkout -- . after npm install to reset any file changes while keeping node_modules intact:

nvm install 22 && nvm use 22 && npm install && git checkout -- .

Permanent fix — run npm install locally on your machine, commit the updated package-lock.json, and push. Once the lockfile matches the npm version on Devin's machine, subsequent installs won't produce changes.

To see exactly what changed, run `cd ~/repos/your-repo && npm install && git diff` in Devin's terminal during environment setup. This helps you decide whether to commit the changes or reset them.

Expo CLI not found

If Devin reports that expo is not found, the Expo CLI may not be installed globally. Since Expo SDK 46+, the CLI is included as a local dependency — use npx expo instead of expo directly:

# Use this
npx expo start --web

# Not this
expo start --web

---

Tips for best results

• Use the web preview — Always include npx expo start --web in your run command so Devin can visually verify changes
• Reference Expo Router paths — Tell Devin which URL paths to check after making changes
• Store credentials as secrets — API keys, test account passwords, and EXPO_TOKEN should be in Secrets
• Keep dependencies fresh — Use npx expo install --check in maintain dependencies to avoid version mismatches
• Add knowledge notes — Document your project's architecture, API endpoints, and testing conventions as Knowledge so Devin can reference them across sessions