1# React Native Guidelines
2 
3A structured repository for creating and maintaining React Native Best Practices
4optimized for agents and LLMs.
5 
6## Structure
7 
8- `rules/` - Individual rule files (one per rule)
9  - `_sections.md` - Section metadata (titles, impacts, descriptions)
10  - `_template.md` - Template for creating new rules
11  - `area-description.md` - Individual rule files
12- `metadata.json` - Document metadata (version, organization, abstract)
13- **`AGENTS.md`** - Compiled output (generated)
14 
15## Rules
16 
17### Core Rendering (CRITICAL)
18 
19- `rendering-text-in-text-component.md` - Wrap strings in Text components
20- `rendering-no-falsy-and.md` - Avoid falsy && operator in JSX
21 
22### List Performance (HIGH)
23 
24- `list-performance-virtualize.md` - Use virtualized lists (LegendList,
25  FlashList)
26- `list-performance-function-references.md` - Keep stable object references
27- `list-performance-callbacks.md` - Hoist callbacks to list root
28- `list-performance-inline-objects.md` - Avoid inline objects in renderItem
29- `list-performance-item-memo.md` - Pass primitives for memoization
30- `list-performance-item-expensive.md` - Keep list items lightweight
31- `list-performance-images.md` - Use compressed images in lists
32- `list-performance-item-types.md` - Use item types for heterogeneous lists
33 
34### Animation (HIGH)
35 
36- `animation-gpu-properties.md` - Animate transform/opacity instead of layout
37- `animation-gesture-detector-press.md` - Use GestureDetector for press
38  animations
39- `animation-derived-value.md` - Prefer useDerivedValue over useAnimatedReaction
40 
41### Scroll Performance (HIGH)
42 
43- `scroll-position-no-state.md` - Never track scroll in useState
44 
45### Navigation (HIGH)
46 
47- `navigation-native-navigators.md` - Use native stack and native tabs
48 
49### React State (MEDIUM)
50 
51- `react-state-dispatcher.md` - Use functional setState updates
52- `react-state-fallback.md` - State should represent user intent only
53- `react-state-minimize.md` - Minimize state variables, derive values
54 
55### State Architecture (MEDIUM)
56 
57- `state-ground-truth.md` - State must represent ground truth
58 
59### React Compiler (MEDIUM)
60 
61- `react-compiler-destructure-functions.md` - Destructure functions early
62- `react-compiler-reanimated-shared-values.md` - Use .get()/.set() for shared
63  values
64 
65### User Interface (MEDIUM)
66 
67- `ui-expo-image.md` - Use expo-image for optimized images
68- `ui-image-gallery.md` - Use Galeria for lightbox/galleries
69- `ui-menus.md` - Native dropdown and context menus with Zeego
70- `ui-native-modals.md` - Use native Modal with formSheet
71- `ui-pressable.md` - Use Pressable instead of TouchableOpacity
72- `ui-measure-views.md` - Measuring view dimensions
73- `ui-safe-area-scroll.md` - Use contentInsetAdjustmentBehavior
74- `ui-scrollview-content-inset.md` - Use contentInset for dynamic spacing
75- `ui-styling.md` - Modern styling patterns (gap, boxShadow, gradients)
76 
77### Design System (MEDIUM)
78 
79- `design-system-compound-components.md` - Use compound components
80 
81### Monorepo (LOW)
82 
83- `monorepo-native-deps-in-app.md` - Install native deps in app directory
84- `monorepo-single-dependency-versions.md` - Single dependency versions
85 
86### Third-Party Dependencies (LOW)
87 
88- `imports-design-system-folder.md` - Import from design system folder
89 
90### JavaScript (LOW)
91 
92- `js-hoist-intl.md` - Hoist Intl formatter creation
93 
94### Fonts (LOW)
95 
96- `fonts-config-plugin.md` - Load fonts natively at build time
97 
98## Creating a New Rule
99 
1001. Copy `rules/_template.md` to `rules/area-description.md`
1012. Choose the appropriate area prefix:
102   - `rendering-` for Core Rendering
103   - `list-performance-` for List Performance
104   - `animation-` for Animation
105   - `scroll-` for Scroll Performance
106   - `navigation-` for Navigation
107   - `react-state-` for React State
108   - `state-` for State Architecture
109   - `react-compiler-` for React Compiler
110   - `ui-` for User Interface
111   - `design-system-` for Design System
112   - `monorepo-` for Monorepo
113   - `imports-` for Third-Party Dependencies
114   - `js-` for JavaScript
115   - `fonts-` for Fonts
1163. Fill in the frontmatter and content
1174. Ensure you have clear examples with explanations
118 
119## Rule File Structure
120 
121Each rule file should follow this structure:
122 
123````markdown
124---
125title: Rule Title Here
126impact: MEDIUM
127impactDescription: Optional description
128tags: tag1, tag2, tag3
129---
130 
131## Rule Title Here
132 
133Brief explanation of the rule and why it matters.
134 
135**Incorrect (description of what's wrong):**
136 
137```tsx
138// Bad code example
139```
140````
141 
142**Correct (description of what's right):**
143 
144```tsx
145// Good code example
146```
147 
148Reference: [Link](https://example.com)
149 
150```
151 
152## File Naming Convention
153 
154- Files starting with `_` are special (excluded from build)
155- Rule files: `area-description.md` (e.g., `animation-gpu-properties.md`)
156- Section is automatically inferred from filename prefix
157- Rules are sorted alphabetically by title within each section
158 
159## Impact Levels
160 
161- `CRITICAL` - Highest priority, causes crashes or broken UI
162- `HIGH` - Significant performance improvements
163- `MEDIUM` - Moderate performance improvements
164- `LOW` - Incremental improvements
165```
166