React Native Skills
Comprehensive best practices for React Native and Expo applications. Contains
rules across multiple categories covering performance, animations, UI patterns,
and platform-specific optimizations.
Portability note: This skill reads sibling files (rules/*.md and the
compiled AGENTS.md) relative to this SKILL.md. If those files are not
shipped alongside it, apply the inline Quick Reference rules directly — the
rule names below are self-describing and need no VPS-specific path.
Single-voice craft (do NOT parallelize)
This is one coherent engineering-guidance voice, not a multi-angle audit. Do
not fan out into parallel sub-agents or split categories across workers —
RN guidance must stay internally consistent (one navigation stack choice, one
styling system, one list strategy) or it contradicts itself. Read the relevant
rule file(s), apply, move on.
Craft upgrades when applying these rules:
- Cite the rule name in every change. When you apply guidance, name it
(e.g. "
list-performance-virtualize → swapped FlatList for FlashList") so
the reviewer can trace each edit to a rule. No silent restyling of adjacent
code (R-KARPATHY: surgical changes).
- Resolve conflicts toward the higher-priority category. Priorities are
ordered 1 (List Performance, CRITICAL) → 8 (Config, LOW). If two rules pull
different directions, the lower-numbered category wins; state the tradeoff.
- Match the existing project, don't impose. Detect the app's current
stack (NativeWind vs StyleSheet, expo-image vs Image, native vs JS nav)
before recommending — apply the rule in the project's idiom rather than
rewriting its conventions.
Output contract
- Produces: RN/Expo code changes (or a review) where each change maps to a
named rule above, plus a short list of
rule-name → what changed.
- Verify: the app/component still type-checks and renders
(
tsc --noEmit or the project's lint/build); animations run on the UI thread
(transform/opacity only); lists use FlashList with stable keys. A change that
doesn't build is not done (L0).
- Evidence / no hallucination: only apply rules listed here or in
rules/.
Do not invent RN APIs — if a rule file is absent, fall back to the documented
Quick Reference name and verify the API against current Expo/RN docs before
using it. No regressions: never remove working behavior to satisfy a rule.
When to Apply
Reference these guidelines when:
- Building React Native or Expo apps
- Optimizing list and scroll performance
- Implementing animations with Reanimated
- Working with images and media
- Configuring native modules or fonts
- Structuring monorepo projects with native dependencies
Rule Categories by Priority
| Priority |
Category |
Impact |
Prefix |
| 1 |
List Performance |
CRITICAL |
list-performance- |
| 2 |
Animation |
HIGH |
animation- |
| 3 |
Navigation |
HIGH |
navigation- |
| 4 |
UI Patterns |
HIGH |
ui- |
| 5 |
State Management |
MEDIUM |
react-state- |
| 6 |
Rendering |
MEDIUM |
rendering- |
| 7 |
Monorepo |
MEDIUM |
monorepo- |
| 8 |
Configuration |
LOW |
fonts-, imports- |
Quick Reference
1. List Performance (CRITICAL)
list-performance-virtualize - Use FlashList for large lists
list-performance-item-memo - Memoize list item components
list-performance-callbacks - Stabilize callback references
list-performance-inline-objects - Avoid inline style objects
list-performance-function-references - Extract functions outside render
list-performance-images - Optimize images in lists
list-performance-item-expensive - Move expensive work outside items
list-performance-item-types - Use item types for heterogeneous lists
2. Animation (HIGH)
animation-gpu-properties - Animate only transform and opacity
animation-derived-value - Use useDerivedValue for computed animations
animation-gesture-detector-press - Use Gesture.Tap instead of Pressable
3. Navigation (HIGH)
navigation-native-navigators - Use native stack and native tabs over JS navigators
4. UI Patterns (HIGH)
ui-expo-image - Use expo-image for all images
ui-image-gallery - Use Galeria for image lightboxes
ui-pressable - Use Pressable over TouchableOpacity
ui-safe-area-scroll - Handle safe areas in ScrollViews
ui-scrollview-content-inset - Use contentInset for headers
ui-menus - Use native context menus
ui-native-modals - Use native modals when possible
ui-measure-views - Use onLayout, not measure()
ui-styling - Use StyleSheet.create or Nativewind
5. State Management (MEDIUM)
react-state-minimize - Minimize state subscriptions
react-state-dispatcher - Use dispatcher pattern for callbacks
react-state-fallback - Show fallback on first render
react-compiler-destructure-functions - Destructure for React Compiler
react-compiler-reanimated-shared-values - Handle shared values with compiler
6. Rendering (MEDIUM)
rendering-text-in-text-component - Wrap text in Text components
rendering-no-falsy-and - Avoid falsy && for conditional rendering
7. Monorepo (MEDIUM)
monorepo-native-deps-in-app - Keep native dependencies in app package
monorepo-single-dependency-versions - Use single versions across packages
8. Configuration (LOW)
fonts-config-plugin - Use config plugins for custom fonts
imports-design-system-folder - Organize design system imports
js-hoist-intl - Hoist Intl object creation
How to Use
Read individual rule files for detailed explanations and code examples:
rules/list-performance-virtualize.md
rules/animation-gpu-properties.md
Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
1---2name: vl-react-native-skills3description:4 React Native and Expo best-practices reference for building performant mobile5 apps — list performance (FlashList), Reanimated animations, native navigation,6 UI patterns, state management, monorepo and config rules. Use when building or7 reviewing React Native / Expo components, optimizing list/scroll performance,8 implementing gestures or animations, or wiring native modules. EN triggers:9 "react native", "expo", "flashlist", "reanimated", "mobile performance",10 "native module". FR triggers: "react native", "appli mobile expo",11 "performance liste mobile", "animation mobile", "module natif".12license: MIT13metadata:14 source: https://skillmd.com/skills/agentik-os/vl-react-native-skills15 author: vercel16 version: '1.0.0'17---1819# React Native Skills2021Comprehensive best practices for React Native and Expo applications. Contains22rules across multiple categories covering performance, animations, UI patterns,23and platform-specific optimizations.2425> **Portability note:** This skill reads sibling files (`rules/*.md` and the26> compiled `AGENTS.md`) relative to this SKILL.md. If those files are not27> shipped alongside it, apply the inline Quick Reference rules directly — the28> rule names below are self-describing and need no VPS-specific path.2930## Single-voice craft (do NOT parallelize)3132This is one coherent engineering-guidance voice, not a multi-angle audit. Do33**not** fan out into parallel sub-agents or split categories across workers —34RN guidance must stay internally consistent (one navigation stack choice, one35styling system, one list strategy) or it contradicts itself. Read the relevant36rule file(s), apply, move on.3738Craft upgrades when applying these rules:39401. **Cite the rule name in every change.** When you apply guidance, name it41 (e.g. "`list-performance-virtualize` → swapped FlatList for FlashList") so42 the reviewer can trace each edit to a rule. No silent restyling of adjacent43 code (R-KARPATHY: surgical changes).442. **Resolve conflicts toward the higher-priority category.** Priorities are45 ordered 1 (List Performance, CRITICAL) → 8 (Config, LOW). If two rules pull46 different directions, the lower-numbered category wins; state the tradeoff.473. **Match the existing project, don't impose.** Detect the app's current48 stack (NativeWind vs StyleSheet, expo-image vs Image, native vs JS nav)49 before recommending — apply the rule in the project's idiom rather than50 rewriting its conventions.5152## Output contract5354- **Produces:** RN/Expo code changes (or a review) where each change maps to a55 named rule above, plus a short list of `rule-name → what changed`.56- **Verify:** the app/component still type-checks and renders57 (`tsc --noEmit` or the project's lint/build); animations run on the UI thread58 (transform/opacity only); lists use FlashList with stable keys. A change that59 doesn't build is not done (L0).60- **Evidence / no hallucination:** only apply rules listed here or in `rules/`.61 Do not invent RN APIs — if a rule file is absent, fall back to the documented62 Quick Reference name and verify the API against current Expo/RN docs before63 using it. No regressions: never remove working behavior to satisfy a rule.6465## When to Apply6667Reference these guidelines when:6869- Building React Native or Expo apps70- Optimizing list and scroll performance71- Implementing animations with Reanimated72- Working with images and media73- Configuring native modules or fonts74- Structuring monorepo projects with native dependencies7576## Rule Categories by Priority7778| Priority | Category | Impact | Prefix |79| -------- | ---------------- | -------- | -------------------- |80| 1 | List Performance | CRITICAL | `list-performance-` |81| 2 | Animation | HIGH | `animation-` |82| 3 | Navigation | HIGH | `navigation-` |83| 4 | UI Patterns | HIGH | `ui-` |84| 5 | State Management | MEDIUM | `react-state-` |85| 6 | Rendering | MEDIUM | `rendering-` |86| 7 | Monorepo | MEDIUM | `monorepo-` |87| 8 | Configuration | LOW | `fonts-`, `imports-` |8889## Quick Reference9091### 1. List Performance (CRITICAL)9293- `list-performance-virtualize` - Use FlashList for large lists94- `list-performance-item-memo` - Memoize list item components95- `list-performance-callbacks` - Stabilize callback references96- `list-performance-inline-objects` - Avoid inline style objects97- `list-performance-function-references` - Extract functions outside render98- `list-performance-images` - Optimize images in lists99- `list-performance-item-expensive` - Move expensive work outside items100- `list-performance-item-types` - Use item types for heterogeneous lists101102### 2. Animation (HIGH)103104- `animation-gpu-properties` - Animate only transform and opacity105- `animation-derived-value` - Use useDerivedValue for computed animations106- `animation-gesture-detector-press` - Use Gesture.Tap instead of Pressable107108### 3. Navigation (HIGH)109110- `navigation-native-navigators` - Use native stack and native tabs over JS navigators111112### 4. UI Patterns (HIGH)113114- `ui-expo-image` - Use expo-image for all images115- `ui-image-gallery` - Use Galeria for image lightboxes116- `ui-pressable` - Use Pressable over TouchableOpacity117- `ui-safe-area-scroll` - Handle safe areas in ScrollViews118- `ui-scrollview-content-inset` - Use contentInset for headers119- `ui-menus` - Use native context menus120- `ui-native-modals` - Use native modals when possible121- `ui-measure-views` - Use onLayout, not measure()122- `ui-styling` - Use StyleSheet.create or Nativewind123124### 5. State Management (MEDIUM)125126- `react-state-minimize` - Minimize state subscriptions127- `react-state-dispatcher` - Use dispatcher pattern for callbacks128- `react-state-fallback` - Show fallback on first render129- `react-compiler-destructure-functions` - Destructure for React Compiler130- `react-compiler-reanimated-shared-values` - Handle shared values with compiler131132### 6. Rendering (MEDIUM)133134- `rendering-text-in-text-component` - Wrap text in Text components135- `rendering-no-falsy-and` - Avoid falsy && for conditional rendering136137### 7. Monorepo (MEDIUM)138139- `monorepo-native-deps-in-app` - Keep native dependencies in app package140- `monorepo-single-dependency-versions` - Use single versions across packages141142### 8. Configuration (LOW)143144- `fonts-config-plugin` - Use config plugins for custom fonts145- `imports-design-system-folder` - Organize design system imports146- `js-hoist-intl` - Hoist Intl object creation147148## How to Use149150Read individual rule files for detailed explanations and code examples:151152```153rules/list-performance-virtualize.md154rules/animation-gpu-properties.md155```156157Each rule file contains:158159- Brief explanation of why it matters160- Incorrect code example with explanation161- Correct code example with explanation162- Additional context and references163164## Full Compiled Document165166For the complete guide with all rules expanded: `AGENTS.md`