Write production-quality React Native and Expo screens day to day — Expo Router routes and Stack.Protected guards, StyleSheet or NativeWind with theme tokens, safe areas and keyboard handling, FlashList v2 lists, Pressable and touch targets, forms with React Hook Form + Zod, Expo SDK modules and permissions, and gestures and animations with Reanimated 4.
When agents use itUse this whenever the user asks to build, implement, refactor or fix a React Native or Expo screen, component, hook or feature; asks "how do I do X in React Native"; pastes RN code with a bug; or asks about FlatList vs FlashList, KeyboardAvoidingView, useSafeAreaInsets, Pressable, Platform.select, expo-image, expo-router, useLocalSearchParams, permissions, scheduleOnRN or deep links. Also use it when generating any new React Native code, even a small snippet. For tests use react-native-testing; for web React use react-development.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill react-native-development -a github-copilot
# or with the org installer (adds .github/skills/react-native-development):
npx -y github:AGCO-Global/org-skills add skill react-native-development
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the frontend-react-native-skills plugin, which bundles all Frontend / React Native skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install frontend-react-native-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill react-native-development -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill react-native-development -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill react-native-development -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill react-native-development -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the react-native-development folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
Web React habits mostly transfer; the places they do not — no CSS cascade, touch instead of click, two threads, native permissions, store review — are where the bugs live. Read expo in package.json before writing code: this guidance assumes SDK 54 or newer (New Architecture only, React Compiler on by default, edge-to-edge mandatory on Android). On SDK 52 or older, say so and name the API that differs.
1. Decide first
Question
Default
Change when
Where does the screen live?
features/<f>/screens/; the app/ route file only imports and renders it
Never — a route file with logic is untestable and ties you to the router
List component
FlashList v2 (@shopify/flash-list) for any data list
Fewer than ~20 static rows that fit one screen → View + map inside a ScrollView
Tappable element
Pressable with accessibilityRole and a ≥44 pt target
Need the platform's native ripple only → still Pressable with android_ripple
Animation
Reanimated 4 CSS style props (animationName, transitionProperty) for simple state changes
Gesture-driven or interpolated → useSharedValue + useAnimatedStyle in a hook
Callback from a worklet
scheduleOnRN from react-native-worklets
Never runOnJS — it was renamed in Reanimated 4
Auth gating
<Stack.Protected guard={!!session}> in the root layout (SDK 53+)
SDK 52 or older → <Redirect>; either way it is client-side only, so the API must authorise too
Storage
MMKV for settings and cache flags
Tokens and secrets → expo-secure-store, always
Forms
React Hook Form + Zod with Controller (RN inputs are controlled)
A one-field sheet → local useState
Native capability
The Expo SDK module (expo-camera, expo-location, …)
No module and no config plugin → local Expo Module (npx create-expo-module --local)
2. Screen shape
A screen reads its typed params (useLocalSearchParams<{ id: string }>(), validated before use), calls one query hook, and returns early for isPending and isError before the happy path — each early return renders designed UI, never null.
StyleSheet.create at the bottom of the file, styles named by role (root, content), every value from shared/theme tokens — no magic numbers. flex: 1 on the root, gap between children instead of margin hacks.
Safe areas as padding from useSafeAreaInsets(). SafeAreaView inside a navigator double-pads, and the core SafeAreaView is deprecated since SDK 54.
Data-dependent headers go in <Stack.Screen options={{ title }} /> inside the screen, not the layout.
Every screen answers four questions: what renders while loading, when empty, on error (with retry), and with no network.
Full screen, list and form templates with imports: references/screen-patterns.md.
3. Components and touch
Pressable for everything tappable: android_ripple, style={({ pressed }) => …}, hitSlop to reach 44×44 pt (Apple HIG) / 48×48 dp (Material) — target the larger of the two, accessibilityRole="button", accessibilityLabel, accessibilityState={{ disabled }}.
Every string lives inside <Text> — a bare string in a View crashes. Set maxFontSizeMultiplier on constrained labels and check the screen at 200 % dynamic type.
Never nest same-direction scroll views. A list inside a screen is a FlashList with ListHeaderComponent, not a ScrollView plus map.
Platform differences: Platform.select({ ios, android }) for small values; Component.ios.tsx / .android.tsx for genuinely different implementations.
Shadows are shadow* on iOS and elevation on Android — wrap in one shadow(level) helper. overflow: 'hidden' is required for borderRadius to clip children on Android.
Android 16 / SDK 54 is edge-to-edge: never assume an opaque status or navigation bar; pad with insets.
4. Lists (FlashList v2)
FlashList from @shopify/flash-list with data, keyExtractor, renderItem, ItemSeparatorComponent, ListEmptyComponent, getItemType when rows differ in layout, onEndReached + onEndReachedThreshold={0.5} for infinite scroll and refreshing/onRefresh for pull-to-refresh. Working screen: references/screen-patterns.md.
v2 measures automatically: estimatedItemSize, estimatedListSize and disableAutoLayout are no longer used and passing them does nothing. Masonry is the masonry prop, not a separate MasonryFlashList. Rows are small components that receive primitives and an id, never an inline closure capturing the row object; formatting happens in the data layer, not in renderItem.
5. Navigation (Expo Router)
router.push drills down, router.replace swaps after login or completion, router.navigate returns to an existing screen, router.dismiss() closes a modal.
Guards are evaluated on the client only — they hide UI, they do not protect data.
<Link href="/orders/[id]" asChild><Pressable>…</Pressable></Link> for tappable navigation; turn on experiments.typedRoutes (still beta) so params are checked.
Modals as a (modals) route group with presentation: 'modal' — deep-linkable and back-button aware, unlike component state.
Every screen is reachable by URL; validate params and render a designed not-found state for a missing entity. Intercept the Android back button only for unsaved changes (useFocusEffect + BackHandler).
6. Keyboard and forms
react-native-keyboard-controller for reliable cross-platform behaviour, or KeyboardAvoidingView with behavior={Platform.OS === 'ios' ? 'padding' : undefined} at screen level.
keyboardShouldPersistTaps="handled" so a button tap works while the keyboard is up; keyboardDismissMode="on-drag".
Inputs: returnKeyType, onSubmitEditing focusing the next ref, autoComplete/textContentType for autofill, keyboardType, autoCapitalize="none" for email.
React Hook Form + Zod through Controller; errors under the field with accessibilityLiveRegion="polite"; submit disabled while pending. Sample: references/screen-patterns.md.
7. Animations and gestures (Reanimated 4)
Simple state transitions: CSS style props — style={{ transitionProperty: 'opacity', transitionDuration: '200ms' }} or animationName keyframes on an Animated.View. No worklets, no hooks.
Gesture-driven: useSharedValue + useAnimatedStyle + Gesture.Pan() inside a GestureDetector, all kept in a hook (useSwipeToDismiss) so the screen stays declarative. Wrap the app root in GestureHandlerRootView.
Crossing back into React from a worklet is scheduleOnRN(fn, ...args) from react-native-worklets — runOnJS was renamed in Reanimated 4, and the babel plugin is now react-native-worklets/plugin (listed last).
List and layout changes: LinearTransition plus FadeIn/FadeOut entering and exiting animations (Layout was the removed 2.x name). Never the core Animated API or PanResponder in new code; @gorhom/bottom-sheet instead of a hand-rolled sheet.
8. Device APIs and permissions
Reach for the Expo SDK module first; they ship config plugins and work on the New Architecture. expo-file-system is class-based now (new File(Paths.cache, 'x.txt')); the old function API lives at expo-file-system/legacy and the deprecated methods throw.
Permissions: check status → show your own explanation → request → handle denied with Linking.openSettings(). Usage strings and Android permissions go in app.json through the config plugin, never by editing ios/ or android/.
Guard for capability (isAvailableAsync()), wrap calls in try/catch, and respect AccessibilityInfo.isReduceMotionEnabled() before animating anything decorative.
Route file is thin; the screen lives in a feature folder
Loading, empty, error-with-retry and offline states all render
Safe-area padding from insets; keyboard handled; checked edge-to-edge on Android
Lists use FlashList v2 with no estimatedItemSize; rows memo-friendly and keyed by id
Every string in <Text>; targets ≥44 pt; roles, labels and states set
Params typed and validated; screen deep-linkable; not-found state designed
Reanimated 4 APIs (scheduleOnRN, LinearTransition); no Animated core, no PanResponder
Tokens only — no hard-coded colours or sizes; dark mode checked
Tokens/secrets in expo-secure-store; permissions requested at the moment of use
Native config through app.json plugins, not edited ios//android/ folders
Anti-patterns
estimatedItemSize on FlashList → delete it; v2 measures automatically.
runOnJS in a worklet → scheduleOnRN from react-native-worklets.
Layout layout animation → LinearTransition.
<Redirect> auth gating on SDK 53+ → <Stack.Protected guard={…}>.
ScrollView + .map() over a data list, or nested same-direction scroll views → one FlashList with header/footer components.
TouchableOpacity or <View onTouchEnd> → Pressable with a role and label.
Dimensions.get('window') at module scope → useWindowDimensions(); the module value never updates on rotation or fold.
Requesting every permission at launch → request at the moment of use, after explaining why.
Business logic in app/ route files or _layout.tsx → move it to features/<f>/model/.
The shared React anti-pattern list (derived state, effect-fetch, index keys) lives in the react-development skill as react-anti-patterns.md.
Go deeper
references/screen-patterns.md — full screen with offline and empty states, FlashList screen with pull-to-refresh and infinite scroll, RHF + Zod form, swipe-to-dismiss hook with Reanimated 4, permission flow.
---
name: react-native-development
description: >
Write production-quality React Native and Expo screens day to day — Expo Router routes and Stack.Protected
guards, StyleSheet or NativeWind with theme tokens, safe areas and keyboard handling, FlashList v2 lists,
Pressable and touch targets, forms with React Hook Form + Zod, Expo SDK modules and permissions, and
gestures and animations with Reanimated 4. Use this whenever the user asks to build, implement, refactor
or fix a React Native or Expo screen, component, hook or feature; asks "how do I do X in React Native";
pastes RN code with a bug; or asks about FlatList vs FlashList, KeyboardAvoidingView, useSafeAreaInsets,
Pressable, Platform.select, expo-image, expo-router, useLocalSearchParams, permissions, scheduleOnRN or
deep links. Also use it when generating any new React Native code, even a small snippet. For tests use
react-native-testing; for web React use react-development.
metadata:
technology: React Native
type: development
---
# React Native Development
> **Targets:** Expo SDK 54+ (57 current) · React Native 0.87 · React 19.2 · Expo Router v7 · Reanimated 4 · FlashList v2 · **Verified:** 2026-09 against https://docs.expo.dev, https://reactnative.dev, https://docs.swmansion.com, https://shopify.github.io/flash-list
Web React habits mostly transfer; the places they do not — no CSS cascade, touch instead of click, two threads, native permissions, store review — are where the bugs live. Read `expo` in `package.json` before writing code: this guidance assumes SDK 54 or newer (New Architecture only, React Compiler on by default, edge-to-edge mandatory on Android). On SDK 52 or older, say so and name the API that differs.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Where does the screen live? | `features/<f>/screens/`; the `app/` route file only imports and renders it | Never — a route file with logic is untestable and ties you to the router |
| List component | **FlashList v2** (`@shopify/flash-list`) for any data list | Fewer than ~20 static rows that fit one screen → `View` + `map` inside a `ScrollView` |
| Tappable element | `Pressable` with `accessibilityRole` and a ≥44 pt target | Need the platform's native ripple only → still `Pressable` with `android_ripple` |
| Animation | Reanimated 4 CSS style props (`animationName`, `transitionProperty`) for simple state changes | Gesture-driven or interpolated → `useSharedValue` + `useAnimatedStyle` in a hook |
| Callback from a worklet | `scheduleOnRN` from `react-native-worklets` | Never `runOnJS` — it was renamed in Reanimated 4 |
| Auth gating | `<Stack.Protected guard={!!session}>` in the root layout (SDK 53+) | SDK 52 or older → `<Redirect>`; either way it is client-side only, so the API must authorise too |
| Storage | MMKV for settings and cache flags | Tokens and secrets → `expo-secure-store`, always |
| Forms | React Hook Form + Zod with `Controller` (RN inputs are controlled) | A one-field sheet → local `useState` |
| Native capability | The Expo SDK module (`expo-camera`, `expo-location`, …) | No module and no config plugin → local Expo Module (`npx create-expo-module --local`) |
## 2. Screen shape
A screen reads its typed params (`useLocalSearchParams<{ id: string }>()`, validated before use), calls one query hook, and returns early for `isPending` and `isError` before the happy path — each early return renders designed UI, never `null`.
- `StyleSheet.create` at the bottom of the file, styles named by role (`root`, `content`), every value from `shared/theme` tokens — no magic numbers. `flex: 1` on the root, `gap` between children instead of margin hacks.
- Safe areas as **padding from `useSafeAreaInsets()`**. `SafeAreaView` inside a navigator double-pads, and the core `SafeAreaView` is deprecated since SDK 54.
- Data-dependent headers go in `<Stack.Screen options={{ title }} />` inside the screen, not the layout.
- Every screen answers four questions: what renders while loading, when empty, on error (with retry), and with no network.
Full screen, list and form templates with imports: `references/screen-patterns.md`.
## 3. Components and touch
- **`Pressable`** for everything tappable: `android_ripple`, `style={({ pressed }) => …}`, `hitSlop` to reach **44×44 pt (Apple HIG) / 48×48 dp (Material)** — target the larger of the two, `accessibilityRole="button"`, `accessibilityLabel`, `accessibilityState={{ disabled }}`.
- **Every string lives inside `<Text>`** — a bare string in a `View` crashes. Set `maxFontSizeMultiplier` on constrained labels and check the screen at 200 % dynamic type.
- **Never nest same-direction scroll views.** A list inside a screen is a `FlashList` with `ListHeaderComponent`, not a `ScrollView` plus `map`.
- Platform differences: `Platform.select({ ios, android })` for small values; `Component.ios.tsx` / `.android.tsx` for genuinely different implementations.
- Shadows are `shadow*` on iOS and `elevation` on Android — wrap in one `shadow(level)` helper. `overflow: 'hidden'` is required for `borderRadius` to clip children on Android.
- Android 16 / SDK 54 is edge-to-edge: never assume an opaque status or navigation bar; pad with insets.
## 4. Lists (FlashList v2)
`FlashList` from `@shopify/flash-list` with `data`, `keyExtractor`, `renderItem`, `ItemSeparatorComponent`, `ListEmptyComponent`, `getItemType` when rows differ in layout, `onEndReached` + `onEndReachedThreshold={0.5}` for infinite scroll and `refreshing`/`onRefresh` for pull-to-refresh. Working screen: `references/screen-patterns.md`.
v2 measures automatically: `estimatedItemSize`, `estimatedListSize` and `disableAutoLayout` are **no longer used** and passing them does nothing. Masonry is the `masonry` prop, not a separate `MasonryFlashList`. Rows are small components that receive primitives and an `id`, never an inline closure capturing the row object; formatting happens in the data layer, not in `renderItem`.
## 5. Navigation (Expo Router)
- `router.push` drills down, `router.replace` swaps after login or completion, `router.navigate` returns to an existing screen, `router.dismiss()` closes a modal.
- Gate auth with guards in the root layout:
```tsx
<Stack>
<Stack.Protected guard={!!session}><Stack.Screen name="(app)" /></Stack.Protected>
<Stack.Protected guard={!session}><Stack.Screen name="sign-in" /></Stack.Protected>
</Stack>
```
Guards are evaluated on the client only — they hide UI, they do not protect data.
- `<Link href="/orders/[id]" asChild><Pressable>…</Pressable></Link>` for tappable navigation; turn on `experiments.typedRoutes` (still beta) so params are checked.
- Modals as a `(modals)` route group with `presentation: 'modal'` — deep-linkable and back-button aware, unlike component state.
- Every screen is reachable by URL; validate params and render a designed not-found state for a missing entity. Intercept the Android back button only for unsaved changes (`useFocusEffect` + `BackHandler`).
## 6. Keyboard and forms
- `react-native-keyboard-controller` for reliable cross-platform behaviour, or `KeyboardAvoidingView` with `behavior={Platform.OS === 'ios' ? 'padding' : undefined}` at screen level.
- `keyboardShouldPersistTaps="handled"` so a button tap works while the keyboard is up; `keyboardDismissMode="on-drag"`.
- Inputs: `returnKeyType`, `onSubmitEditing` focusing the next `ref`, `autoComplete`/`textContentType` for autofill, `keyboardType`, `autoCapitalize="none"` for email.
- React Hook Form + Zod through `Controller`; errors under the field with `accessibilityLiveRegion="polite"`; submit disabled while pending. Sample: `references/screen-patterns.md`.
## 7. Animations and gestures (Reanimated 4)
- Simple state transitions: CSS style props — `style={{ transitionProperty: 'opacity', transitionDuration: '200ms' }}` or `animationName` keyframes on an `Animated.View`. No worklets, no hooks.
- Gesture-driven: `useSharedValue` + `useAnimatedStyle` + `Gesture.Pan()` inside a `GestureDetector`, all kept in a hook (`useSwipeToDismiss`) so the screen stays declarative. Wrap the app root in `GestureHandlerRootView`.
- Crossing back into React from a worklet is `scheduleOnRN(fn, ...args)` from `react-native-worklets` — `runOnJS` was renamed in Reanimated 4, and the babel plugin is now `react-native-worklets/plugin` (listed last).
- List and layout changes: `LinearTransition` plus `FadeIn`/`FadeOut` entering and exiting animations (`Layout` was the removed 2.x name). Never the core `Animated` API or `PanResponder` in new code; `@gorhom/bottom-sheet` instead of a hand-rolled sheet.
## 8. Device APIs and permissions
- Reach for the Expo SDK module first; they ship config plugins and work on the New Architecture. `expo-file-system` is class-based now (`new File(Paths.cache, 'x.txt')`); the old function API lives at `expo-file-system/legacy` and the deprecated methods throw.
- Permissions: check status → show your own explanation → request → handle denied with `Linking.openSettings()`. Usage strings and Android permissions go in `app.json` through the config plugin, never by editing `ios/` or `android/`.
- Guard for capability (`isAvailableAsync()`), wrap calls in `try/catch`, and respect `AccessibilityInfo.isReduceMotionEnabled()` before animating anything decorative.
## 9. Deliverable format
```
## Screen/component: <name>
- Route: app/<path> → features/<f>/screens/<Name> · params: <typed shape>
- Code (imports included, TypeScript strict)
- States: loading / empty / error+retry / offline
- Platform notes: <iOS vs Android behaviour, insets, keyboard>
- SDK assumptions: Expo <version>, Reanimated 4, FlashList v2
- Tests: behaviours to cover (write them with react-native-testing)
```
## Checklist
- [ ] Route file is thin; the screen lives in a feature folder
- [ ] Loading, empty, error-with-retry and offline states all render
- [ ] Safe-area padding from insets; keyboard handled; checked edge-to-edge on Android
- [ ] Lists use FlashList v2 with no `estimatedItemSize`; rows memo-friendly and keyed by id
- [ ] Every string in `<Text>`; targets ≥44 pt; roles, labels and states set
- [ ] Params typed and validated; screen deep-linkable; not-found state designed
- [ ] Reanimated 4 APIs (`scheduleOnRN`, `LinearTransition`); no `Animated` core, no `PanResponder`
- [ ] Tokens only — no hard-coded colours or sizes; dark mode checked
- [ ] Tokens/secrets in `expo-secure-store`; permissions requested at the moment of use
- [ ] Native config through `app.json` plugins, not edited `ios/`/`android/` folders
## Anti-patterns
- **`estimatedItemSize` on FlashList** → delete it; v2 measures automatically.
- **`runOnJS` in a worklet** → `scheduleOnRN` from `react-native-worklets`.
- **`Layout` layout animation** → `LinearTransition`.
- **`<Redirect>` auth gating on SDK 53+** → `<Stack.Protected guard={…}>`.
- **`ScrollView` + `.map()` over a data list, or nested same-direction scroll views** → one `FlashList` with header/footer components.
- **`TouchableOpacity` or `<View onTouchEnd>`** → `Pressable` with a role and label.
- **`Dimensions.get('window')` at module scope** → `useWindowDimensions()`; the module value never updates on rotation or fold.
- **Requesting every permission at launch** → request at the moment of use, after explaining why.
- **Business logic in `app/` route files or `_layout.tsx`** → move it to `features/<f>/model/`.
- The shared React anti-pattern list (derived state, effect-fetch, index keys) lives in the `react-development` skill as `react-anti-patterns.md`.
## Go deeper
- `references/screen-patterns.md` — full screen with offline and empty states, FlashList screen with pull-to-refresh and infinite scroll, RHF + Zod form, swipe-to-dismiss hook with Reanimated 4, permission flow.
- Sibling skills: `react-native-architecture` (structure, offline strategy, native modules, releases), `react-native-performance` (jank, startup, profiling), `react-native-testing` (tests), `frontend-code-review`, `react-development` (web).