Building React Native Apps

View saved version →

---
name: create-react-native-library
description: Scaffolds React Native libraries with create-react-native-library for standalone libraries or local native modules and views. Use when creating or working on React Native libraries or adding native functionality in an existing app.
license: MIT
---

# Create React Native Library

## Overview

Use this skill to scaffold a standalone React Native library or a local library inside an existing app, then continue with the correct implementation docs.

Examples:

- JS-only library that may use other React Native libraries
- Native modules that expose native functionality to JavaScript
- Native UI components that render native views in React Native

Choose one flow first:

- Use [scaffold-library.md][scaffold-library] when creating a new library that may be published to npm
- Use [local-library.md][local-library] when exposing native functionality in a React Native app

## When to Apply

Use this skill when:

- Creating or working on a React Native library with `create-react-native-library`
- Creating a native module or view in an existing app
- Wrapping native SDKs and exposing them to React Native

## Quick Reference

```bash
# Inspect current options before scaffolding
npx create-react-native-library@latest --help

# Scaffold a library with turbo modules and the Expo example app
npx create-react-native-library@latest awesome-library \
  --no-interactive \
  --yes \
  --description "A brief description of the library" \
  --type turbo-module \
  --languages kotlin-objc \
  --example expo

# Scaffold a local Turbo Module inside an existing app
cd MyApp
npx create-react-native-library@latest awesome-library \
  --local \
  --no-interactive \
  --yes \
  --description "A brief description of the library" \
  --type turbo-module \
  --languages kotlin-objc
```

## References

| File                                    | Description                                             |
| --------------------------------------- | ------------------------------------------------------- |
| [scaffold-library.md][scaffold-library] | Scaffold a new library and default to the Expo example  |
| [local-library.md][local-library]       | Add a local library to an existing app with autolinking |

## Problem -> Skill Mapping

| Problem                                      | Start With                           |
| -------------------------------------------- | ------------------------------------ |
| Need a new library scaffold                  | [scaffold-library][scaffold-library] |
| Need to add a local native library to an app | [local-library][local-library]       |

[scaffold-library]: references/scaffold-library.md
[local-library]: references/local-library.md

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: react-native-best-practices
description: Provides React Native performance optimization guidelines for FPS, TTI, bundle size, memory leaks, re-renders, and animations. Applies to tasks involving Hermes optimization, JS thread blocking, bridge overhead, FlashList, native modules, or debugging jank and frame drops.
license: MIT
---

# React Native Best Practices

## Overview

Performance optimization guide for React Native applications, covering JavaScript/React, Native (iOS/Android), and bundling optimizations. Based on Callstack's "Ultimate Guide to React Native Optimization".

## When to Apply

Reference these guidelines when:
- Debugging slow/janky UI or animations
- Investigating memory leaks (JS or native)
- Optimizing app startup time (TTI)
- Reducing bundle or app size
- Writing native modules (Turbo Modules)
- Profiling React Native performance
- Reviewing React Native code for performance

## Security Notes

- Treat shell commands in these references as local developer operations. Review them before running, prefer version-pinned tooling, and avoid piping remote scripts directly to a shell.
- Treat third-party libraries and plugins as dependencies that still require normal supply-chain controls: pin versions, verify provenance, and update through your standard review process.
- Treat remote chunk loading as first-party artifact delivery only. Prefer app-bundled chunks or signed CI release manifests; hosted chunks must come from trusted HTTPS origins you control and be pinned to the current app release.

## Priority-Ordered Guidelines

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | FPS & Re-renders | CRITICAL | `js-*` |
| 2 | Bundle Size | CRITICAL | `bundle-*` |
| 3 | TTI Optimization | HIGH | `native-*`, `bundle-*` |
| 4 | Native Performance | HIGH | `native-*` |
| 5 | Memory Management | MEDIUM-HIGH | `js-*`, `native-*` |
| 6 | Animations | MEDIUM | `js-*` |

Impact labels are triage hints: CRITICAL first, HIGH next, MEDIUM when evidence points there.

## Quick Reference

### Optimization Workflow

Follow this cycle for any performance issue: **Measure → Optimize → Re-measure → Validate**

1. **Measure**: Capture baseline metrics before changes. For runtime issues, prefer commit timeline, re-render counts, slow components, heaviest-commit breakdown, and startup/TTI when available. Component tree depth or count are optional context, not substitutes. Do not recommend memoization, atomic state, or compiler changes without a measured render or FPS problem.
2. **Optimize**: Apply the targeted fix from the relevant reference
3. **Re-measure**: Run the same measurement to get updated metrics
4. **Validate**: Confirm improvement (e.g., FPS 45→60, TTI 3.2s→1.8s, bundle 2.1MB→1.6MB)

If metrics did not improve, revert and try the next suggested fix.

### Review Guardrails

- Check library versions before suggesting API-specific fixes. Example: FlashList v2 deprecates `estimatedItemSize`, so do not flag it as missing there.
- Do not suggest `useMemo` or `useCallback` dependency changes unless behavior is demonstrably incorrect or profiling shows wasted work tied to that value.
- Do not report stale closures speculatively. Show the stale read path, a repro, or profiler evidence before calling it out.
- When profiling a flow, measure the target interaction itself. Do not treat component tree depth or component count as the main performance evidence.

### Critical: FPS & Re-renders

**Profile first:**
```bash
agent-device react-devtools status
agent-device react-devtools wait --connected
agent-device react-devtools profile start
agent-device react-devtools profile stop
agent-device react-devtools profile slow --limit 5
agent-device react-devtools profile rerenders --limit 5
agent-device react-devtools profile timeline --limit 20
```

Drive the target interaction with normal `agent-device` commands between `profile start` and `profile stop`.

Manual fallback when `agent-device` i

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 43 — file references are metadata, not package contents.

View saved version →

---
name: react-native-tv-best-practices
description: Reviews React Native TV apps for focus/D-pad navigation, 10-foot UI layout, TV playback/DRM integration, low-memory TV performance, and TV accessibility. Use when building, debugging, or reviewing react-native-tvos, Expo TV, Amazon Vega/Kepler, or React Native web TV targets where the issue depends on remote input, TV focus, TV packaging, TV hardware, or TV playback constraints.
license: MIT
---

# React Native TV Best Practices

## Overview

TV-specific review guidance for React Native-backed apps on Apple TV, Android TV, Fire TV, Amazon Vega/Kepler, and web-based TV targets such as Tizen or webOS.

Use this skill only for TV deltas: remote input, focus engines, 10-foot layout, platform packaging, playback/DRM, low-memory TV hardware, and TV accessibility. For ordinary React Native performance or architecture issues, use [react-native-best-practices](../react-native-best-practices/SKILL.md).

## Skill Format

Reference files are grouped by topic prefix:

- `focus-*`: focus engines, focus guides, focus event performance
- `nav-*`: D-pad navigation, Back/Menu behavior, keyboard/search input
- `design-*`: 10-foot typography, layout, color, focus visibility
- `perf-*`: startup, memory, lists, animation, and network constraints on TV hardware
- `video-*`: playback architecture, DRM/protocol selection, debugging
- `a11y-*`: TV accessibility implementation and audit checks
- `setup-*`: stack detection, setup, architecture, cross-platform behavior
- `test-*` and `release-*`: test coverage, E2E, and CI/release workflows

## When to Apply

Apply this skill when the app targets a TV platform and the work involves:

- Focus movement, visible focus, focus restoration, or remote/D-pad input
- TV layout readability, overscan/safe areas, or 10-foot UI density
- TV player controls, manifests, DRM, decoder support, or playback errors
- Performance on low-memory TV hardware, especially with video or large carousels
- TV accessibility with screen readers, captions, focus order, or remote-only interaction
- Platform setup for `react-native-tvos`, Expo TV, Amazon Vega/Kepler, Tizen, or webOS

## Before You Start — Identify the TV Stack

This skill covers several TV stacks. **Detect which one the app targets before flagging setup issues** — demanding `react-native-tvos`, a tvOS Podfile, or an Android TV manifest on a Vega/Kepler or web-based TV app produces false positives.

| Stack                                                 | How to detect                                                                                     | Setup expectations                                                                                                             |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **react-native-tvos** (Apple TV, Android TV, Fire TV) | `"react-native": "npm:react-native-tvos@…"` in package.json                                       | tvOS Podfile (`platform :tvos`); Android TV `leanback`/`LEANBACK_LAUNCHER` manifest entries; TV emulator/simulator             |
| **Expo + react-native-tvos**                          | above **plus** `@react-native-tvos/config-tv` in app.json                                         | `EXPO_TV=1` prebuild; `react-native-tvos` version must match the Expo SDK; not all Expo features/libraries are available on TV |
| **Amazon Vega / Kepler**                              | Vega/Kepler SDK & tooling (`@amazon-devices/*` deps, Kepler manifest); **no** `react-native-tvos` | Amazon's Vega/Kepler toolchain — `react-native-tvos`, tvOS Podfile, and Android TV manifest do **not** apply                   |
| **Web-based TV** (Tizen, webOS)                       | web bundler (Rsbuild/webpack) + platform packaging; spati

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 28 — file references are metadata, not package contents.

View saved version →

---
name: react-navigation
description: Provides React Navigation UI patterns for stacks, tabs, drawers etc. Use when building navigation UIs with React Navigation, configuring headers, bottom sheets or handling safe areas and insets.
license: MIT
---

# React Navigation

## Overview

Guide for building navigation UIs with React Navigation.

This skill only applies to React Navigation 7. The API and patterns may not work with different versions.

## API Selection

React Navigation offers two API - object-based `Static API` and component-based `Dynamic API`.

- **Existing Apps**: Check the current navigation setup and follow the same API style when using the references
- **New Apps**: If the app does not have an existing navigation setup yet, prefer `Static API`

## When to Apply

Reference this skill when:

- Building navigation UI patterns such as stacks, tabs, drawers, sheets etc.
- Configuring headers and other built-in navigator UI
- Handling safe areas and insets in navigation UI

## References

| File                                        | Description                    |
| ------------------------------------------- | ------------------------------ |
| [stacks.md][stacks]                         | Stack based navigation         |
| [form-sheet.md][form-sheet]                 | Bottom sheet and form sheets   |
| [bottom-tabs.md][bottom-tabs]               | Cross-platform bottom tabs     |
| [native-bottom-tabs.md][native-bottom-tabs] | Native bottom tabs             |
| [material-top-tabs.md][material-top-tabs]   | Swipeable Top tabs             |
| [drawers.md][drawers]                       | Drawer navigation and sidebars |
| [header.md][header]                         | Configuring headers            |
| [safe-areas.md][safe-areas]                 | Safe-area handling             |

## Problem -> Skill Mapping

| Problem                                                                   | Start With                                  |
| ------------------------------------------------------------------------- | ------------------------------------------- |
| Showing screens and modals in a stack                                     | [stacks.md][stacks]                         |
| Showing bottom sheets or form sheets                                      | [form-sheet.md][form-sheet]                 |
| Showing screens in bottom tabs or responsive sidebars with web support    | [bottom-tabs.md][bottom-tabs]               |
| Showing screens in native tabs on iOS & Android                           | [native-bottom-tabs.md][native-bottom-tabs] |
| Showing content in swipeable top tabs                                     | [material-top-tabs.md][material-top-tabs]   |
| Using a drawer or sidebar                                                 | [drawers.md][drawers]                       |
| Configuring the header in bottom tab or drawer navigator                  | [header.md][header]                         |
| Handling safe-area such as status bar, header insets, tab bar insets etc. | [safe-areas.md][safe-areas]                 |

[stacks]: references/stacks.md
[form-sheet]: references/form-sheet.md
[safe-areas]: references/safe-areas.md
[bottom-tabs]: references/bottom-tabs.md
[native-bottom-tabs]: references/native-bottom-tabs.md
[material-top-tabs]: references/material-top-tabs.md
[drawers]: references/drawers.md
[header]: references/header.md

Referenced files: 9 — file references are metadata, not package contents.

View saved version →

---
name: upgrading-react-native
description: Upgrades React Native apps to newer versions by applying rn-diff-purge template diffs, updating package.json dependencies, migrating native iOS and Android configuration, resolving CocoaPods and Gradle changes, and handling breaking API updates. Use when upgrading React Native, bumping RN version, updating from RN 0.x to 0.y, or migrating Expo SDK alongside a React Native upgrade.
license: MIT
---

# Upgrading React Native

## Overview

Covers the full React Native upgrade workflow: template diffs via Upgrade Helper, dependency updates, Expo SDK steps, and common pitfalls.

## Typical Upgrade Sequence

1. **Route**: Choose the right upgrade path via [upgrading-react-native.md][upgrading-react-native]
2. **Diff**: Fetch the canonical template diff using Upgrade Helper via [upgrade-helper-core.md][upgrade-helper-core]
3. **Dependencies**: Assess and update third-party packages via [upgrading-dependencies.md][upgrading-dependencies]
4. **React**: Align React version if upgraded via [react.md][react]
5. **Expo** (if applicable): Apply Expo SDK layer via [expo-sdk-upgrade.md][expo-sdk-upgrade]
6. **Verify**: Run post-upgrade checks via [upgrade-verification.md][upgrade-verification]

```bash
# Quick start: detect current version and fetch diff
npm pkg get dependencies.react-native --prefix "$APP_DIR"
npm view react-native dist-tags.latest

# Example: upgrading from 0.76.9 to 0.78.2
# 1. Fetch the template diff
curl -L -f -o /tmp/rn-diff.diff \
  "https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/0.76.9..0.78.2.diff" \
  && echo "Diff downloaded OK" || echo "ERROR: diff not found, check versions"
# 2. Review changed files
grep -n "^diff --git" /tmp/rn-diff.diff
# 3. Update package.json, apply native changes, then install + rebuild
npm install --prefix "$APP_DIR"
cd "$APP_DIR/ios" && pod install
# 4. Validate: both platforms must build successfully
npx react-native build-android --mode debug --no-packager
xcodebuild -workspace "$APP_DIR/ios/App.xcworkspace" -scheme App -sdk iphonesimulator build
```

## When to Apply

Reference these guidelines when:
- Moving a React Native app to a newer version
- Reconciling native config changes from Upgrade Helper
- Validating release notes for breaking changes

## Quick Reference

| File | Description |
|------|-------------|
| [upgrading-react-native.md][upgrading-react-native] | Router: choose the right upgrade path |
| [upgrade-helper-core.md][upgrade-helper-core] | Core Upgrade Helper workflow and reliability gates |
| [upgrading-dependencies.md][upgrading-dependencies] | Dependency compatibility checks and migration planning |
| [react.md][react] | React and React 19 upgrade alignment rules |
| [expo-sdk-upgrade.md][expo-sdk-upgrade] | Expo SDK-specific upgrade layer (conditional) |
| [upgrade-verification.md][upgrade-verification] | Post-upgrade verification checklist, including agent-device-assisted checks |
| [monorepo-singlerepo-targeting.md][monorepo-singlerepo-targeting] | Monorepo and single-repo app targeting and command scoping |

## Problem → Skill Mapping

| Problem | Start With |
|---------|------------|
| Need to upgrade React Native | [upgrade-helper-core.md][upgrade-helper-core] |
| Need dependency risk triage and migration options | [upgrading-dependencies.md][upgrading-dependencies] |
| Need React/React 19 package alignment | [react.md][react] |
| Need workflow routing first | [upgrading-react-native.md][upgrading-react-native] |
| Need Expo SDK-specific steps | [expo-sdk-upgrade.md][expo-sdk-upgrade] |
| Need manual or agent-assisted regression validation | [upgrade-verification.md][upgrade-verification] |
| Need repo/app command scoping | [monorepo-singlerepo-targeting.md][monorepo-singlerepo-targeting] |

[upgrading-react-native]: references/upgrading-react-native.md
[upgrade-helper-core]: references/upgrade-helper-core.md
[upgrading-dependencies]: references/upgrading-dependencies.md
[react]:

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 8 — file references are metadata, not package contents.