# React Native and Flutter UI Recipes

URL: https://developertoolkit.ai/en/cookbook/mobile-development/mobile-patterns/
Description: 12 copy-paste agent prompts for React Native and Flutter UI, pinned to current package majors, each with the device evidence that proves it works.

React Native and Flutter UI recipes are 12 copy-paste prompts for building cross-platform mobile screens with Claude Code, Codex, or Cursor, from adaptive navigation to store preparation. Each prompt pins the package majors current in September 2026 and asks for evidence from both platforms, so you check screenshots and tests instead of reading every line.

This page is for developers who build mobile UI with an agent, and for tech leads who review what it ships. You ask for a swipeable card and get `Gesture.Pan()`, which `react-native-gesture-handler` 3 deprecates. You ask for a fast feed and get FlashList's `estimatedItemSize`, a prop that FlashList 2 removed. The iOS simulator looks fine, and nobody opens the Android emulator. This page covers the screens; for the stack underneath them (Expo builds and OTA updates, React Native data layers, Riverpod and go_router architecture), start at the [mobile development overview](/en/cookbook/mobile-development/).

## Which package versions do these recipes assume?

The agent's training data spans several majors of every package below, and each major changed an API the agent likes to use. The table shows what npm and pub.dev served on 2026-09-26. Put the majors in `AGENTS.md` (or `CLAUDE.md`) so every session inherits them, and let `npx expo install` or `flutter pub add` choose exact versions.

| Package | Version | What the agent gets wrong |
| --- | --- | --- |
| `react-native` | 0.87.1 | Old-architecture bridge modules. Current libraries such as Reanimated 4 target the New Architecture. |
| `@react-navigation/native` | 7.4.1 | Mixing the v6 and v7 configuration styles in one navigator. |
| `@shopify/flash-list` | 2.3.2 | `estimatedItemSize`. Version 2 measures items itself, and the prop no longer exists. |
| `react-native-reanimated` | 4.7.0 | Missing `react-native-worklets` (peer dependency `0.13.x`). Reanimated 4.7 also requires React Native 0.86 to 0.88. |
| `react-native-gesture-handler` | 3.3.0 | `Gesture.Pan()`, which 3.x marks `@deprecated` in favour of `usePanGesture`. The 2.x line lives on npm under the `legacy` tag. |
| `expo-image` | 57.0.5 | Reaching for `react-native-fast-image` instead. This page uses `expo-image`. |
| `expo-notifications` | 57.0.21 | Reaching for `@notifee/react-native`, whose last npm release is 9.1.8 from 2024-12-20. |
| `flutter_riverpod` | 3.4.3 | `StateNotifierProvider` from Riverpod 2, which Riverpod 3 moved to `legacy.dart`. |
| `go_router` | 18.0.1 | Ignoring the SDK floor. Version 18 requires Flutter 3.44 and Dart 3.12. |

## Set up the agent once for mobile UI work

Two things make every recipe below cheaper to verify: a type check that runs on every edit, and an instruction file that defines "done". Install your stack's vendor skills first. The [mobile overview](/en/cookbook/mobile-development/) has the install commands for the Expo, Flutter, and Callstack React Native skills and for MobileBuildMCP.

Add this block to `AGENTS.md`, which Codex reads in trusted projects. Claude Code reads it when the repository has no `CLAUDE.md` (from v2.1.277, both release channels on 2026-10-12); otherwise copy the block into `CLAUDE.md`. For Cursor, paste the block into a project Rule.

```markdown
## Mobile UI: verify before done
- Pinned majors: React Native 0.87, React Navigation 7, FlashList 2, Reanimated 4,
  Gesture Handler 3, expo-image, expo-notifications. Flutter 3.44+, Riverpod 3, go_router 18.
- Before using a library API, read its types in node_modules or its pub.dev docs.
- Gates: `npx tsc --noEmit`, the linter, and the test runner (React Native);
  `flutter analyze` and `flutter test` (Flutter).
- Launch the app on one iOS simulator and one Android emulator. Save a screenshot of
  every changed screen to evidence/<task>/ios-*.png and evidence/<task>/android-*.png.
- Forbidden in app code: localStorage, window.*, document.*, dart:html,
  dart:io Platform in widgets.
- Never run a store submission, EAS build, or OTA publish.
```

The tools differ in how they enforce that block:

**Claude Code**

    A `PostToolUse` hook puts type errors in front of Claude on the edit that caused them. Save this as `.claude/hooks/mobile-typecheck.sh` and make it executable:

    ```bash
    #!/usr/bin/env bash
    # .claude/hooks/mobile-typecheck.sh (PostToolUse, matcher "Edit|Write")
    set -uo pipefail
    file=$(jq -r '.tool_input.file_path // empty')
    case "$file" in
      *.ts|*.tsx)
        out=$(cd "$CLAUDE_PROJECT_DIR" && npx tsc --noEmit 2>&1) \
          || { echo "tsc failed after editing $file:" >&2; head -n 40 <<<"$out" >&2; exit 2; } ;;
      *.dart)
        out=$(cd "$CLAUDE_PROJECT_DIR" && dart analyze "$file" 2>&1) \
          || { echo "dart analyze failed on $file:" >&2; head -n 40 <<<"$out" >&2; exit 2; } ;;
    esac
    exit 0
    ```

    Register it in `.claude/settings.json`:

    ```json
    {
      "hooks": {
        "PostToolUse": [
          { "matcher": "Edit|Write",
            "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/mobile-typecheck.sh", "args": [], "timeout": 120 }] }
        ]
      }
    }
    ```

    The matcher filters on the tool name, not on a file glob, so the script filters by extension. On a large project this runs the full type check on every edit, which can take tens of seconds; the `timeout` of 120 seconds stops a slow run from stalling the session, and adding `--incremental` to the `tsc` call lets later runs reuse the previous type information. See [Claude Code hooks](/en/claude-code/automate/hooks-automation/) for the full event list. Before you merge, run `/code-review` on the branch.

**Codex**

    Codex reads the `AGENTS.md` block in every session. For a repeatable, unattended run of one recipe, use `codex exec` with the `:workspace` permission profile (beta in Codex 0.157.1). That profile has no network access and writes only inside the project and the temp directory (it cannot write to `$HOME`): in our Codex 0.157.1 test on Linux, `curl` to the npm registry could not resolve the host and a write to `$HOME` hit a read-only file system. Package installs fail inside the run, and so does anything that needs simulator or emulator state outside the repository. We tested this offline-gate run only with the npm and TypeScript gates; Flutter is untested here, and `flutter analyze` or `flutter test` may need a writable SDK directory and `$HOME`, and so a different profile. Install dependencies first, give Codex only the offline gates, and fail the run unless every gate reports `PASS`:

    ```bash
    npm ci   # Flutter (untested here): flutter pub get. The :workspace profile has no network
    mkdir -p evidence/feed-list
    codex exec -c default_permissions=":workspace" -o evidence/feed-list/summary.md \
      "Apply the FlashList recipe in docs/prompts/feed-list.md. Do not install
       packages. Run the type check, linter and tests from 'Mobile UI: verify before
       done' in AGENTS.md; skip the simulator, emulator and frame-rate steps. Report
       each gate on its own line as PASS, FAIL or NOT RUN with the reason."
    s=evidence/feed-list/summary.md
    test -s "$s" && grep -q PASS "$s" && ! grep -Eq 'FAIL|NOT RUN' "$s" \
      || { echo "Codex run incomplete or failing: see $s" >&2; exit 1; }
    ```

    Save the FlashList prompt from this page as `docs/prompts/feed-list.md` first. The check fails closed: a missing or empty summary, a `FAIL`, or a `NOT RUN` stops the script. The device half of the evidence stays with you: launch the app on the iOS simulator and the Android emulator outside Codex, save the screenshots to `evidence/feed-list/`, and record the frame rates yourself. A green `summary.md` alone is not device evidence.

    Open the pull request and comment `@codex review` to get a second review of the diff against the same `AGENTS.md` rules. See [Codex code review](/en/codex/ship/code-review/).

**Cursor**

    Paste the block into a project Rule so Cursor applies it in every session. For recipes that touch many files (navigation, native modules), start in Plan Mode so you approve the file list before the agent writes code. On the pull request, [Bugbot](/en/cursor-ide/ship/bugbot/) reviews the diff. The [Cursor mobile development guide](/en/cursor-ide/build/mobile-dev/) covers the IDE-side loop with simulators.

## React Native UI recipes

Each recipe states the situation, gives the prompt, and names the evidence that proves the result. Paste a prompt as-is, and edit only the screen names.

### Build platform-adaptive navigation with React Navigation 7

Your product team wants a bottom tab bar on iOS and a navigation drawer on Android, both backed by the same screens and the same deep links.

**Copy-paste prompt: platform-adaptive navigation**

```text
Build platform-adaptive navigation with React Navigation 7 (read the installed
@react-navigation/* types before writing config).
- RootNavigator renders a bottom-tab navigator on iOS and a drawer navigator on
  Android. Both hold the same four stacks: Home, Search, Notifications, Profile.
- Type every route in RootStackParamList; no `any` in navigation code.
- Deep links: myapp://profile/:id and https://example.com/profile/:id open
  Profile with the id param, including from a cold start.
- Android back: pop the nested stack first; on a root screen, ask before exiting.
- Tests: resolve each deep link to its route and params with the linking config.
Finish with the evidence list from AGENTS.md, plus the output of
`npx uri-scheme open myapp://profile/42 --ios` and `--android`.
```

**Evidence:** the deep-link tests, and screenshots of Profile 42 opened by the link on both platforms.

### Build a responsive layout for phones, tablets, and foldables

Your app stretches a phone layout across a tablet, and the list-detail screens waste two thirds of the display.

**Copy-paste prompt: responsive layout system**

```text
Create a responsive layout system for this React Native app.
- useResponsive() built on useWindowDimensions (never Dimensions.get at module
  scope) returning { width, height, breakpoint, orientation }. Breakpoints:
  compact < 600, medium 600-839, expanded >= 840 (dp).
- MasterDetail: compact shows the list and pushes the detail screen; medium and
  expanded show list (1/3) and detail (2/3) side by side.
- ResponsiveGrid: 1, 2, or 3 columns by breakpoint, recomputed on rotation.
- Respect safe areas with react-native-safe-area-context.
- Tests: mock useWindowDimensions at 390, 700, and 1000 dp wide and assert
  which layout renders.
Screenshots: phone portrait, tablet portrait, tablet landscape.
```

**Evidence:** the three breakpoint tests, and a tablet screenshot in each orientation. Rotation is where hard-coded widths break.

### Fix a janky feed with FlashList 2 and expo-image

Your feed holds 1,000+ items with images and stutters when you scroll, and pull-to-refresh jumps the list.

**Copy-paste prompt: FlashList 2 feed**

```text
Rebuild FeedScreen on @shopify/flash-list 2. Do not add estimatedItemSize or
any other v1 estimate prop; v2 measures items itself.
- FeedItem in React.memo, compared on id and updatedAt only. Stable renderItem
  and keyExtractor (useCallback). If rows have different layouts, set
  getItemType.
- Images with expo-image: fixed dimensions, a blurhash placeholder, and
  cachePolicy "memory-disk".
- Pull-to-refresh prepends new items without moving the visible row; background
  refreshes show a "N new posts" pill instead of jumping.
- Infinite scroll with onEndReached, a footer spinner, and an end-of-feed state.
Measure before and after: record 10 seconds of fast scrolling on the Android
emulator with the performance monitor on, and report the JS and UI frame rates.
```

**Evidence:** before and after frame rates from the same device and scroll, not "should be faster". The [React Native recipe](/en/cookbook/mobile-development/react-native/) covers the data layer behind the feed.

### Show offline state without losing the user's work

Field technicians fill in forms without a signal, and today the app shows a spinner forever and drops the entry.

**Copy-paste prompt: offline-first UI states**

```text
Add offline UI states on top of the existing data layer (do not replace it).
- useNetworkStatus() with @react-native-community/netinfo returning
  { isOnline, pendingCount, lastSyncedAt, syncNow }.
- OfflineBanner: shows "Offline - N changes waiting" and a Retry button; hides
  within 2 seconds of reconnecting.
- Every list row with unsynced changes shows a "Pending" badge; a failed sync
  shows "Not saved - tap to retry" and never silently discards the entry.
- Forms save locally on submit and navigate back immediately.
- Tests: mock NetInfo offline, submit a form, go online, and assert the badge
  clears and the entry reaches the mocked API exactly once.
```

**Evidence:** the offline-to-online test, and a screenshot of the banner and badge taken in airplane mode. For the storage and sync engine itself (MMKV with TanStack Query, or WatermelonDB for relational sync), use the [React Native recipe](/en/cookbook/mobile-development/react-native/).

### Write a native module when no library covers the hardware

Your NFC hardware vendor uses a proprietary tag format that `react-native-nfc-manager` does not expose, so you need Swift and Kotlin code behind a typed TypeScript API.

**Copy-paste prompt: Turbo Module for NFC**

```text
Create a Turbo Module named NativeVendorNfc for the New Architecture.
- Codegen spec in src/specs/NativeVendorNfc.ts: isAvailable(), startScan(),
  stopScan(), and events onTag({ id, payload }) and onError({ code, message }).
- iOS (Swift): CoreNFC reader session, the NFCReaderUsageDescription key in
  Info.plist, and the NFC tag-reading entitlement. Return isAvailable false on
  devices without NFC instead of crashing.
- Android (Kotlin): NfcAdapter with foreground dispatch, released in onPause.
- useVendorNfc() hook: { isAvailable, isScanning, lastTag, error, start, stop }.
- Jest tests for the hook with the native module mocked.
After editing native code, do a full native rebuild for both platforms (no
Fast Refresh) and report both build logs' last 20 lines.
```

**Evidence:** two clean native builds and the hook tests. CoreNFC does not run on the iOS simulator, so a person scans a real tag on one iPhone and one Android phone before merge. In an Expo app, ask for an Expo module instead; see the [Expo recipe](/en/cookbook/mobile-development/expo/).

**Claude Code**

    Native edits need a rebuild, and a stale binary makes a correct change look broken. After any `.swift` or `.kt` edit, tell Claude to rebuild the native app: `npx expo run:ios` / `npx expo run:android` in an Expo development build, or `cd ios && pod install` followed by `npx react-native run-ios` / `npx react-native run-android` in bare React Native. `pod install` only syncs dependencies and compiles nothing. Keep `npx expo prebuild --clean` for a changed config plugin or `app.json` in a Continuous Native Generation project: it regenerates `ios/` and `android/` and deletes any direct edits there, so native code in an Expo app belongs in an Expo module. On macOS, [MobileBuildMCP](/en/ecosystem/mcp/framework-devtools-mcp/) lets Claude build, launch the simulator, and read the build log itself.

**Codex**

    Run the native work in its own worktree so Xcode and Gradle sync state never mixes with your JavaScript branch. Tell Codex to finish every native edit with the same rebuild: `npx expo run:ios` / `run:android` (Expo), or `pod install` then `npx react-native run-ios` / `run-android` (bare React Native). MobileBuildMCP registers with `codex mcp add`; see the [dev-server MCP servers](/en/ecosystem/mcp/framework-devtools-mcp/) page for the command.

**Cursor**

    Approve the file list in Plan Mode first: spec, Swift class, Kotlin class, manifest, entitlement, and hook. A missing entitlement file is the most common omission, and it fails only at run time on a device.

### Build a swipeable card stack with Reanimated 4 and Gesture Handler 3

Your matching screen needs a card stack that follows the finger at the display's frame rate and never stutters while JavaScript is busy.

**Copy-paste prompt: swipeable card stack**

```text
Build a swipeable card stack with react-native-reanimated 4 and
react-native-gesture-handler 3. Read both packages' installed types first:
Gesture.Pan() is deprecated in Gesture Handler 3, so use usePanGesture.
- SwipeableCard maps translationX to rotation (max 15 degrees) and to
  like/nope overlay opacity. Past 120 px on release it animates off-screen with
  withTiming; otherwise it springs back with withSpring.
- CardStack renders the top 3 cards with scale and translateY offsets; the next
  card animates up when the top card leaves.
- Undo brings the last card back. Haptic feedback (expo-haptics) at threshold.
- All animation values are shared values; no setState during a gesture.
- Tests with react-native-gesture-handler/jest-utils (fireGestureHandler or
  createGestureController): a past-threshold swipe calls onSwipe('right');
  a short swipe returns the card.
```

**Evidence:** the gesture tests, plus a screen recording from a physical Android phone, where dropped frames show that the simulator hides. Confirm `react-native-worklets` is in `package.json`.

### Ask for notification permission at the right moment

Your app requests notification permission on first launch, most users decline, and a tapped notification opens the home screen instead of the order it mentions.

**Copy-paste prompt: notification permission and deep links**

```text
Implement the notification UX with expo-notifications (it works in bare React
Native through Expo modules). Do not use @notifee/react-native.
- A pre-permission screen shown after the user's first completed order, not on
  launch; "Not now" hides it for 14 days.
- If permission is denied, Settings > Notifications shows a button that opens
  the system settings with Linking.openSettings().
- Android channels: orders (high), messages (default), promotions (low),
  created before the token request.
- A tapped notification with data.url opens that screen, including from a cold
  start (useLastNotificationResponse).
- Tests for the permission state machine and for data.url to route mapping.
```

**Evidence:** the state-machine tests, and a notification sent to a device and tapped from a killed app. The [Expo recipe](/en/cookbook/mobile-development/expo/) covers the token pipeline and server side.

## Flutter UI recipes

The Flutter recipes use the widget and state APIs of Flutter 3.44+ and Riverpod 3. For package setup, provider architecture, and the go_router auth redirect, follow the [Flutter recipe](/en/cookbook/mobile-development/flutter/) first.

### Build a branded widget library that adapts per platform

Every screen styles its own buttons, dark mode is half-finished, and the design team cannot see all variants in one place.

**Copy-paste prompt: Flutter widget library**

```text
Create a widget library in lib/widgets/ driven by ThemeData and a
ThemeExtension<AppTokens> (colors, radii, spacing) with light and dark
instances. No hard-coded colors or sizes inside widgets.
- AppButton: primary, secondary, outline, ghost, destructive; sm, md, lg;
  loading and disabled states; a minimum 48x48 dp tap target.
- AppTextField: label, helper, error, prefix/suffix, password visibility toggle.
- AppCard, AppAvatar (image, initials fallback, presence dot), AppBottomSheet
  (drag handle, half and full snap points).
- A Widgetbook catalogue listing every variant in light and dark.
- Widget tests per widget, and golden tests for AppButton in both themes.
Run flutter analyze and flutter test and report the results.
```

**Evidence:** passing golden tests in both themes. Goldens catch visual regressions that nobody spots in a diff. Generate them on the same OS as CI, because font rendering differs between macOS and Linux.

### Render loading, error, and empty states from Riverpod

Your screens show a blank page while data loads and a red error box when the API fails, and each screen handles it differently.

**Copy-paste prompt: async screen states with Riverpod 3**

```text
Standardise async screen states with Riverpod 3 code generation (@riverpod,
no imports from package:flutter_riverpod/legacy.dart).
- AsyncStateView<T> widget taking an AsyncValue<T> and builders for data,
  loading (skeleton, not a spinner), error (message plus Retry that calls
  ref.invalidate), and empty.
- Keep previous data visible during refresh (skipLoadingOnRefresh).
- Migrate OrdersScreen and ProfileScreen to it.
- Widget tests with ProviderScope overrides for each of the four states, and a
  test that Retry triggers exactly one new fetch.
```

**Evidence:** the four state tests per screen. The "exactly one fetch" test matters because Riverpod 3 also retries failing providers on its own.

### Make Flutter screens feel native on iOS and Android

Your Flutter app uses Material dialogs and switches on iOS, and iOS users notice.

**Copy-paste prompt: adaptive Flutter widgets**

```text
Create platform-adaptive widgets in lib/adaptive/ that branch on
Theme.of(context).platform (never dart:io Platform, so tests can override it).
- showAdaptiveAppDialog: AlertDialog on Android, CupertinoAlertDialog on iOS,
  one API.
- AdaptiveSwitch (Switch.adaptive), AdaptiveTextField, and an adaptive date
  picker (Material dialog on Android, CupertinoDatePicker in a bottom sheet on
  iOS).
- Page transitions from PageTransitionsTheme: Cupertino on iOS, the Material
  default on Android.
- Widget tests that render each widget with platform set to TargetPlatform.iOS
  and TargetPlatform.android and assert the expected widget type.
```

**Evidence:** the paired platform tests, and one screenshot per platform of the dialog and the date picker.

### Keep bottom navigation state with go_router shell routes

Switching tabs resets each tab's scroll position and navigation stack, and on a tablet the bottom bar looks out of place.

**Copy-paste prompt: adaptive shell navigation with go_router 18**

```text
Rebuild the main navigation with go_router 18 StatefulShellRoute.indexedStack:
four branches (Home, Search, Inbox, Profile), each keeping its own stack and
scroll position.
- The shell shows a NavigationBar below 600 dp width and a NavigationRail at
  600 dp and wider.
- Tapping the active tab pops that branch to its root.
- Typed routes with go_router_builder, including /products/:id inside Home.
- Keep the existing auth redirect unchanged.
- Widget tests: switch tabs and back and assert the pushed product page is
  still there; render at 400 and 800 dp and assert bar versus rail.
```

**Evidence:** the state-preservation test and the two width tests.

## Prepare a React Native or Flutter app for store submission

Your app is feature-complete, and the release checklist lives in one person's head. This recipe turns it into a script that CI can run on every release candidate.

**Copy-paste prompt: store submission preparation**

```text
Prepare this app for App Store and Google Play submission. Change config only;
do not submit, upload, or run a paid cloud build.
- iOS: every NS*UsageDescription the code actually needs (grep the APIs used;
  remove unused ones), the privacy manifest (PrivacyInfo.xcprivacy), version
  and build number.
- Android: applicationId, versionCode and versionName, targetSdk 36, release
  signing read from environment variables (never committed), R8 enabled.
- scripts/verify-release.sh: builds release for both platforms (iOS needs a
  macOS runner; fail, never skip, when Xcode is absent), fails if a
  release bundle contains console.log or debugPrint calls, debug-only packages,
  or a non-production API URL.
- RELEASE_CHECKLIST.md listing what a human checks on a real device.
Run verify-release.sh and report its output.
```

**Evidence:** a green `verify-release.sh` run and the checklist signed off by the release owner. Google Play requires new apps and app updates to target Android 16 (API level 36) from 2026-08-31, per the Android developers target-API page checked on 2026-09-26.

Whichever tool prepares the release, the rule is the same: run `verify-release.sh` in CI on every release branch (the iOS half on a macOS runner), let the script's exit code decide pass or fail, and have a person sign the checklist before anything reaches a store. The tools differ only in where you review the change. In Claude Code, run the prompt in plan mode (`/plan`) so the release owner approves the file list, then run `/code-review` on the branch before you open the pull request. In Codex, start the preparation as a cloud task that opens a pull request with the config changes and `RELEASE_CHECKLIST.md`, and the release owner approves the version bump and signing configuration there. In Cursor, review the `Info.plist`, `build.gradle`, and privacy-manifest changes in one diff before you accept them; a wrong `versionCode` or a leftover debug entitlement is visible there at a glance.

## How do you verify a mobile UI recipe without reading every line?

Every recipe above ends with evidence the agent produces and you check. Match the evidence to the kind of change:

| Change | Evidence that proves it | Who signs off |
| --- | --- | --- |
| Layout and adaptive UI | Screenshots on iOS and Android, phone and tablet, both orientations | The developer who opened the task |
| Lists and animations | Frame rates before and after, from the same device and scroll; a physical-device recording | The developer |
| State, navigation, deep links | Unit and widget tests for each state and each link, including cold start | Reviewer of the pull request |
| Native modules | Clean native builds on both platforms, plus a manual run on real hardware | The developer, on a device |
| Release config | A green `verify-release.sh` and a signed checklist | Release owner or tech lead |

In Claude Code the type-check hook catches wrong APIs on the edit that introduced them; in Codex and Cursor the `npx tsc --noEmit` / `flutter analyze` gate in `AGENTS.md` catches them when the agent runs it before finishing. The tests and screenshots prove behaviour. Put all of it in the pull request with the [evidence bundle](/en/workflows/ship/evidence-bundle/) format, and see [mobile app testing patterns](/en/workflows/test/mobile-testing/) for device matrices and flaky tests.

## What breaks when agents write React Native and Flutter UI?

- **APIs from an older major.** The agent writes `estimatedItemSize`, `Gesture.Pan()`, or `StateNotifierProvider`. Recovery: keep the version table in `AGENTS.md`, and tell the agent to read the installed types before it writes library code. In Claude Code the hook catches most of these as type errors; in Codex and Cursor the `AGENTS.md` type-check gate does, when the agent runs it.
- **Invented or abandoned packages.** The agent adds a package that does not exist, or one with no release in years. Recovery: check every new dependency on npm or pub.dev before merge; see [dependency verification](/en/workflows/test/dependency-verification/).
- **Web APIs in mobile code.** `localStorage`, `window.innerWidth`, or `dart:html` compile in some setups and crash on a device. Recovery: extend the "Forbidden in app code" line of the `AGENTS.md` block and reject any change without device screenshots.
- **Stale native binaries.** A native change looks broken because Fast Refresh does not rebuild Swift or Kotlin. Recovery: rebuild the binary with `npx expo run:ios` / `run:android` (Expo), or `pod install` then `npx react-native run-ios` / `run-android` (bare React Native). `npx expo prebuild --clean` compiles nothing and deletes direct edits to `ios/` and `android/`.
- **Simulator-only success.** NFC, push, and camera features work only on hardware or need entitlements that the simulator skips. Recovery: name the device test in the recipe's evidence, and keep one iPhone and one Android phone available for it.
- **Gradle and CocoaPods breaks.** The agent adds a library that needs a newer Android Gradle Plugin or iOS deployment target. Recovery: paste the full build error back, and ask the agent to state the library's minimum versions before it changes build files.

## Where to go next with mobile UI

- [Mobile development overview](/en/cookbook/mobile-development/): pick your stack and install its skills
- [Expo development patterns](/en/cookbook/mobile-development/expo/): routing, EAS builds, and staged OTA updates
- [React Native development patterns](/en/cookbook/mobile-development/react-native/): offline data, performance, and CI to the stores
- [Flutter development patterns](/en/cookbook/mobile-development/flutter/): Riverpod, go_router, Dio, and the check command
- [Native iOS and Android recipes](/en/cookbook/mobile-development/native-ios-android/): Swift/SwiftUI and Kotlin/Compose with an agent
- [Mobile app testing patterns](/en/workflows/test/mobile-testing/): device matrices, Maestro flows, and platform-specific tests
