Vl React Native Skills

---
name: vl-react-native-skills
description:
  React Native and Expo best-practices reference for building performant mobile
  apps — list performance (FlashList), Reanimated animations, native navigation,
  UI patterns, state management, monorepo and config rules. Use when building or
  reviewing React Native / Expo components, optimizing list/scroll performance,
  implementing gestures or animations, or wiring native modules. EN triggers:
  "react native", "expo", "flashlist", "reanimated", "mobile performance",
  "native module". FR triggers: "react native", "appli mobile expo",
  "performance liste mobile", "animation mobile", "module natif".
license: MIT
metadata:
  author: vercel
  version: '1.0.0'
---

# 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:

1. **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).
2. **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.
3. **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`