expo-development

# Expo Development

## Topic Routing

Read the matching reference before writing code for any of these topics:

| Topic | Reference |
|-------|-----------|
| EAS Build & deployment | `references/eas-build.md` |
| Expo Router & navigation | `references/routing.md` |
| Native modules & CNG | `references/native-modules.md` |

## Critical Rules

**Project Setup**
- Use `npx create-expo-app@latest` for new projects — always target the latest SDK
- Use Continuous Native Generation (CNG) — never eject; prefer `npx expo prebuild` when native config is needed
- Configure `app.json` / `app.config.ts` for all project metadata — never modify native projects directly when using CNG

**Expo Router**
- File-based routing in `app/` — define `_layout.tsx` in each directory for `<Stack>`, `<Tabs>`, or `<Drawer>`
- Use `Link` for declarative navigation, `useRouter()` for imperative — configure `scheme` in app.json for deep links

**EAS Build**
- Define `development` / `preview` / `production` profiles in `eas.json`
- Preview: `"distribution": "internal"` + `"channel": "preview"` — Development: add `"developmentClient": true`
- Production: `"channel": "production"` + `"autoIncrement": true`

**EAS Update (OTA)**
- `eas update --channel production` for JS-only changes — no app store review
- Set `"runtimeVersion": { "policy": "fingerprint" }` — mismatched runtimeVersion forces a new binary build

**Native Modules**
- Prefer Expo SDK packages over community alternatives — install with `npx expo install` for version resolution
- Config plugins (`app.plugin.js`) modify native projects at prebuild time — never edit `ios/` or `android/` directly
- Custom native code: `npx create-expo-module` scaffolds Swift + Kotlin module

**Security**
- Store API keys and secrets in EAS Secrets — never hardcode in `app.json` or source code
- Use `expo-secure-store` for device-side secret storage

## Workflow: New Project → Build → Deploy

1. **Scaffold** — `npx create-expo-app@latest my-app --template default@sdk-55`
2. **Verify local** — `cd my-app && npx expo start` → confirm app loads in simulator
3. **Init EAS** — `eas init && eas build:configure` → creates `eas.json` with profiles
4. **Build preview** — `eas build --profile preview --platform ios`
5. **Check status** — `eas build:list` → wait for `finished` status; if `errored` → `eas build:view <id>` → fix config → rebuild
6. **Test** — install preview build on device via QR code or TestFlight
7. **Build production** — `eas build --profile production --platform all`
8. **Submit** — `eas submit --platform ios && eas submit --platform android`

## Workflow: OTA Update

1. **Make JS-only changes** — modify components, styles, or logic (no native module changes)
2. **Deploy** — `eas update --channel production --message "Fix: button alignment"`
3. **Verify** — `eas update:list` → confirm update published with correct `runtimeVersion`
4. **Rollback if needed** — `eas update:republish --group <previous-group-id>`

> If `runtimeVersion` mismatch: a new binary build is required — OTA cannot bridge native changes.

## Build Failure Recovery

```
Build failed → check logs
├── "Provisioning profile" error → eas credentials → fix iOS signing
├── "SDK version mismatch" → npx expo install --fix → rebuild
├── "Metro bundler" error → check JS syntax → npx expo start to reproduce
├── "Native module" error → npx expo prebuild --clean → verify config plugins
└── "EAS secret" missing → eas secret:create → rebuild
```

## Screen with Expo Router

```tsx
// app/user/[id].tsx
import { useLocalSearchParams } from 'expo-router';
import { View, Text } from 'react-native';

export default function UserScreen() {
  const { id } = useLocalSearchParams<{ id: string }>();
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>User {id}</Text>
    </View>
  );
}
```

## EAS Build Profile

```json
{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal"
    },
    "preview": {
      "distribution": "internal",
      "channel": "preview"
    },
    "production": {
      "channel": "production",
      "autoIncrement": true
    }
  }
}
```