playbooks

home / skills / vercel-labs / agent-skills / react-native-skills

react-native-skills skill

/skills/react-native-skills

This skill helps optimize React Native apps by applying best practices for list performance, animations, and native integrations across Expo and RN.

npx playbooks add skill vercel-labs/agent-skills --skill react-native-skills

Review the files below or copy the command above to add this skill to your agents.

Files (42)
SKILL.md
4.3 KB
---
name: vercel-react-native-skills
description:
  React Native and Expo best practices for building performant mobile apps. Use
  when building React Native components, optimizing list performance,
  implementing animations, or working with native modules. Triggers on tasks
  involving React Native, Expo, mobile performance, or native platform APIs.
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.

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

Overview

This skill provides concise, actionable best practices for building performant React Native and Expo mobile apps. It focuses on list performance, animations, navigation, UI patterns, state, rendering, monorepo layout, and configuration. Use it to enforce high-impact rules and common patterns that reduce jank, memory use, and native integration issues.

How this skill works

The skill inspects tasks or code involving React Native, Expo, mobile performance, and native APIs, then recommends specific rules and fixes from prioritized categories. It highlights critical list optimizations, recommended animation patterns, native navigation choices, and UI/component-level guidance. Each rule points to concrete code patterns to avoid and preferred implementations for better runtime behavior.

When to use it

  • When building or reviewing React Native or Expo apps
  • When optimizing scrolling, lists, and large data sets
  • When implementing animations with Reanimated or gestures
  • When integrating native modules, fonts, or media handling
  • When structuring monorepos that include native dependencies

Best practices

  • For large lists, virtualize with FlashList and memoize item components; stabilize callbacks and avoid inline style objects
  • Animate only GPU-friendly properties (transform, opacity) and compute animations with derived values to keep work off the JS thread
  • Prefer native stack/tabs for navigation performance and use native modal/menu primitives where possible
  • Use expo-image for efficient image handling and optimize images inside lists to reduce memory and layout cost
  • Minimize state subscriptions, use dispatcher patterns for callbacks, and show fallbacks on first render to avoid layout thrash

Example use cases

  • Convert a FlatList with jank into a FlashList with memoized items and stable callbacks
  • Replace JS-heavy animated gestures with Reanimated derived values and GPU-only transforms
  • Switch a JS navigator to native stack/tabs to fix slow transitions on low-end devices
  • Organize a monorepo so native dependencies live in the app package and ensure single-version dependencies
  • Add expo-image and lazy image loading to an image gallery to reduce memory spikes

FAQ

Does this skill apply to both managed and bare Expo projects?

Yes. The rules focus on runtime patterns and native integration that apply to managed and bare workflows; some configuration rules (fonts, plugins) vary by project type.

Which list library should I use for large datasets?

Use FlashList for large lists by default; it provides better virtualization and throughput than basic FlatList for heterogeneous or high-volume lists.