react-native

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Native Complete Guide

React Native 完整优化指南

The ultimate React Native optimization guide combining:

Callstack - Profiling, measurement, and native optimization (27 references)
Vercel - Code patterns, UI, and best practices (36 rules)

这份终极React Native优化指南整合了以下两部分内容：

Callstack - 性能分析、测量与原生优化（含27份参考资料）
Vercel - 代码模式、UI设计与最佳实践（含36条规则）

When to Apply

适用场景

Reference these guidelines when:

Debugging slow/janky UI or animations
Optimizing list and scroll performance
Investigating memory leaks (JS or native)
Optimizing app startup time (TTI)
Reducing bundle or app size
Implementing animations with Reanimated
Building UI with native components
Working with React Compiler
Structuring monorepo projects

在以下场景中可参考本指南：

调试卡顿的UI或动画
优化列表与滚动性能
排查内存泄漏问题（JS或原生层面）
优化应用启动时间（TTI）
减小包体积或应用安装包大小
使用Reanimated实现动画
基于原生组件构建UI
开发React Compiler相关功能
搭建单体仓库（monorepo）项目结构

Priority-Ordered Guidelines

按优先级排序的指南

Priority	Category	Impact	Source
1	Core Rendering	CRITICAL	Vercel
2	List Performance	CRITICAL	Both
3	FPS & Re-renders	CRITICAL	Callstack
4	Bundle Size	CRITICAL	Callstack
5	Animation	HIGH	Both
6	Navigation	HIGH	Vercel
7	TTI Optimization	HIGH	Callstack
8	UI Patterns	HIGH	Vercel
9	Native Performance	HIGH	Callstack
10	State Management	MEDIUM	Vercel
11	React Compiler	MEDIUM	Both
12	Memory Management	MEDIUM	Callstack
13	Monorepo	MEDIUM	Vercel

优先级	分类	影响程度	来源
1	核心渲染	关键	Vercel
2	列表性能	关键	两者
3	FPS与重渲染	关键	Callstack
4	包体积	关键	Callstack
5	动画	高	两者
6	导航	高	Vercel
7	TTI优化	高	Callstack
8	UI模式	高	Vercel
9	原生性能	高	Callstack
10	状态管理	中	Vercel
11	React Compiler	中	两者
12	内存管理	中	Callstack
13	单体仓库	中	Vercel

Quick Reference: Code Patterns (Vercel)

快速参考：代码模式（Vercel）

Core Rendering (CRITICAL)

核心渲染（关键）

```
rendering-no-falsy-and
```
- Never use && with falsy values (crashes app)
```
rendering-text-in-text-component
```
- Wrap strings in Text components

```
rendering-no-falsy-and
```
- 切勿在布尔逻辑中使用假值与&&组合（会导致应用崩溃）
```
rendering-text-in-text-component
```
- 所有字符串需包裹在Text组件中

List Performance (CRITICAL)

列表性能（关键）

```
list-performance-virtualize
```
- Use FlashList/LegendList for any list
```
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
```
- Use compressed, appropriately-sized images
```
list-performance-item-expensive
```
- Move expensive work outside items
```
list-performance-item-types
```
- Use item types for heterogeneous lists

```
list-performance-virtualize
```
- 所有列表均使用FlashList/LegendList实现
```
list-performance-item-memo
```
- 对列表项组件进行记忆化处理
```
list-performance-callbacks
```
- 稳定回调函数引用
```
list-performance-inline-objects
```
- 避免在渲染内联样式对象
```
list-performance-function-references
```
- 将函数提取至渲染方法外部
```
list-performance-images
```
- 使用压缩后的、尺寸合适的图片
```
list-performance-item-expensive
```
- 将耗时操作移至列表项外部执行
```
list-performance-item-types
```
- 为异构列表设置列表项类型

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 for press animations

```
animation-gpu-properties
```
- 仅对transform与opacity属性执行动画
```
animation-derived-value
```
- 使用useDerivedValue实现计算式动画
```
animation-gesture-detector-press
```
- 使用Gesture.Tap实现按压动画

Navigation (HIGH)

导航（高）

```
navigation-native-navigators
```
- Use native stack/tabs over JS navigators

```
navigation-native-navigators
```
- 优先使用原生栈/标签导航器，而非JS导航器

UI Patterns (HIGH)

UI模式（高）

```
ui-expo-image
```
- Use expo-image for all images
```
ui-image-gallery
```
- Use Galeria for lightboxes
```
ui-pressable
```
- Use Pressable over TouchableOpacity
```
ui-safe-area-scroll
```
- Use contentInsetAdjustmentBehavior
```
ui-scrollview-content-inset
```
- Use contentInset for dynamic spacing
```
ui-menus
```
- Use native context menus (zeego)
```
ui-native-modals
```
- Use native modals over JS bottom sheets
```
ui-measure-views
```
- Use onLayout, not measure()
```
ui-styling
```
- Use StyleSheet.create, gap, borderCurve

```
ui-expo-image
```
- 所有图片均使用expo-image组件
```
ui-image-gallery
```
- 使用Galeria实现图片灯箱效果
```
ui-pressable
```
- 使用Pressable替代TouchableOpacity
```
ui-safe-area-scroll
```
- 使用contentInsetAdjustmentBehavior属性
```
ui-scrollview-content-inset
```
- 使用contentInset实现动态间距
```
ui-menus
```
- 使用原生上下文菜单（zeego）
```
ui-native-modals
```
- 优先使用原生模态框，而非JS底部弹窗
```
ui-measure-views
```
- 使用onLayout方法，而非measure()
```
ui-styling
```
- 使用StyleSheet.create、gap、borderCurve属性

State Management (MEDIUM)

状态管理（中）

```
react-state-minimize
```
- Derive values, minimize state
```
react-state-dispatcher
```
- Use dispatch updaters
```
react-state-fallback
```
- Use fallback pattern for reactive defaults
```
state-ground-truth
```
- State represents truth, derive visuals

```
react-state-minimize
```
- 推导数据，最小化状态数量
```
react-state-dispatcher
```
- 使用dispatch更新器
```
react-state-fallback
```
- 为响应式默认值使用回退模式
```
state-ground-truth
```
- 状态代表真实数据，视图由状态推导而来

React Compiler (MEDIUM)

React Compiler（中）

```
react-compiler-destructure-functions
```
- Destructure functions early
```
react-compiler-reanimated-shared-values
```
- Use .get()/.set() not .value

```
react-compiler-destructure-functions
```
- 提前解构函数
```
react-compiler-reanimated-shared-values
```
- 使用.get()/.set()而非.value属性

Monorepo (MEDIUM)

单体仓库（中）

```
monorepo-native-deps-in-app
```
- Install native deps in app package
```
monorepo-single-dependency-versions
```
- Single versions across packages

```
monorepo-native-deps-in-app
```
- 在应用包中安装原生依赖
```
monorepo-single-dependency-versions
```
- 所有包使用统一的依赖版本

Configuration (LOW)

配置（低）

```
fonts-config-plugin
```
- Load fonts at build time
```
imports-design-system-folder
```
- Re-export from design system
```
js-hoist-intl
```
- Hoist Intl formatter creation

```
fonts-config-plugin
```
- 在构建时加载字体
```
imports-design-system-folder
```
- 从设计系统目录重新导出
```
js-hoist-intl
```
- 提升Intl格式化器的创建逻辑

Quick Reference: Profiling & Measurement (Callstack)

快速参考：性能分析与测量（Callstack）

FPS & Re-renders (CRITICAL)

FPS与重渲染（关键）

bash

undefined

bash

undefined

Open React Native DevTools

打开React Native DevTools

Press 'j' in Metro, or shake device → "Open DevTools"

在Metro中按'j'键，或摇晃设备 → "Open DevTools"

- `js-profile-react.md` - React DevTools profiling
- `js-measure-fps.md` - FPS monitoring
- `js-react-compiler.md` - Automatic memoization
- `js-atomic-state.md` - Jotai/Zustand patterns
- `js-concurrent-react.md` - useDeferredValue, useTransition

- `js-profile-react.md` - React DevTools性能分析
- `js-measure-fps.md` - FPS监控
- `js-react-compiler.md` - 自动记忆化
- `js-atomic-state.md` - Jotai/Zustand使用模式
- `js-concurrent-react.md` - useDeferredValue、useTransition的使用

Bundle Size (CRITICAL)

包体积（关键）

bash

npx react-native bundle \
  --entry-file index.js \
  --bundle-output output.js \
  --platform ios \
  --sourcemap-output output.js.map \
  --dev false --minify true

npx source-map-explorer output.js --no-border-checks

```
bundle-barrel-exports.md
```
- Avoid barrel imports
```
bundle-analyze-js.md
```
- JS bundle visualization
```
bundle-tree-shaking.md
```
- Dead code elimination
```
bundle-r8-android.md
```
- Android code shrinking
```
bundle-hermes-mmap.md
```
- Disable bundle compression

bash

npx react-native bundle \
  --entry-file index.js \
  --bundle-output output.js \
  --platform ios \
  --sourcemap-output output.js.map \
  --dev false --minify true

npx source-map-explorer output.js --no-border-checks

```
bundle-barrel-exports.md
```
- 避免桶式导入
```
bundle-analyze-js.md
```
- JS包可视化分析
```
bundle-tree-shaking.md
```
- 无用代码消除
```
bundle-r8-android.md
```
- Android代码压缩
```
bundle-hermes-mmap.md
```
- 禁用包压缩

TTI Optimization (HIGH)

TTI优化（高）

```
native-measure-tti.md
```
- TTI measurement setup
```
bundle-hermes-mmap.md
```
- Enable Hermes mmap
Defer non-critical work with
```
InteractionManager
```

```
native-measure-tti.md
```
- TTI测量设置
```
bundle-hermes-mmap.md
```
- 启用Hermes mmap功能
使用
```
InteractionManager
```
延迟非关键任务

Native Performance (HIGH)

原生性能（高）

iOS: Xcode Instruments → Time Profiler
Android: Android Studio → CPU Profiler
```
native-turbo-modules.md
```
- Building fast native modules
```
native-threading-model.md
```
- Turbo Module threads
```
native-profiling.md
```
- Platform profiling guides

iOS: Xcode Instruments → Time Profiler
Android: Android Studio → CPU Profiler
```
native-turbo-modules.md
```
- 构建高性能原生模块
```
native-threading-model.md
```
- Turbo Module线程模型
```
native-profiling.md
```
- 平台性能分析指南

Memory Management (MEDIUM)

内存管理（中）

```
js-memory-leaks.md
```
- JS memory leak hunting
```
native-memory-leaks.md
```
- Native memory leaks
```
native-memory-patterns.md
```
- C++/Swift/Kotlin memory

```
js-memory-leaks.md
```
- JS内存泄漏排查
```
native-memory-leaks.md
```
- 原生内存泄漏排查
```
native-memory-patterns.md
```
- C++/Swift/Kotlin内存管理

Animations (MEDIUM)

动画（中）

```
js-animations-reanimated.md
```
- Reanimated worklets

```
js-animations-reanimated.md
```
- Reanimated worklets使用

Problem → Solution Mapping

问题→解决方案映射

Problem	Vercel Rules	Callstack References
App crashes	`rendering-no-falsy-and` , `rendering-text-in-text-component`	-
List scroll jank	`list-performance-*`	`js-lists-flatlist-flashlist.md`
Animation drops frames	`animation-gpu-properties`	`js-animations-reanimated.md`
Too many re-renders	`react-state-minimize`	`js-profile-react.md` , `js-react-compiler.md`
Slow startup (TTI)	-	`native-measure-tti.md` , `bundle-hermes-mmap.md`
Large app size	-	`bundle-analyze-app.md` , `bundle-r8-android.md`
Memory growing	-	`js-memory-leaks.md` , `native-memory-leaks.md`
TextInput lag	-	`js-uncontrolled-components.md`
Native module slow	-	`native-turbo-modules.md`

问题	Vercel规则	Callstack参考资料
应用崩溃	`rendering-no-falsy-and` , `rendering-text-in-text-component`	-
列表滚动卡顿	`list-performance-*`	`js-lists-flatlist-flashlist.md`
动画掉帧	`animation-gpu-properties`	`js-animations-reanimated.md`
重渲染次数过多	`react-state-minimize`	`js-profile-react.md` , `js-react-compiler.md`
启动缓慢（TTI）	-	`native-measure-tti.md` , `bundle-hermes-mmap.md`
应用体积过大	-	`bundle-analyze-app.md` , `bundle-r8-android.md`
内存持续增长	-	`js-memory-leaks.md` , `native-memory-leaks.md`
TextInput输入卡顿	-	`js-uncontrolled-components.md`
原生模块运行缓慢	-	`native-turbo-modules.md`

File Structure

文件结构

react-native/
├── SKILL.md          # This file
├── AGENTS.md         # Full 74KB compiled Vercel guide
├── rules/            # 36 individual Vercel rule files
│   ├── list-performance-*.md
│   ├── animation-*.md
│   ├── ui-*.md
│   └── ...
└── references/       # 27 Callstack reference files
    ├── js-*.md
    ├── native-*.md
    ├── bundle-*.md
    └── images/

react-native/
├── SKILL.md          # 本文件
├── AGENTS.md         # 完整的74KB编译版Vercel指南
├── rules/            # 36份独立的Vercel规则文件
│   ├── list-performance-*.md
│   ├── animation-*.md
│   ├── ui-*.md
│   └── ...
└── references/       # 27份Callstack参考资料文件
    ├── js-*.md
    ├── native-*.md
    ├── bundle-*.md
    └── images/

Attribution

来源说明

Combined from:

"The Ultimate Guide to React Native Optimization" by Callstack
React Native Skills by Vercel

本指南整合自：

Callstack出品的《The Ultimate Guide to React Native Optimization》
Vercel出品的React Native Skills