React Native Guidelines

A structured repository for creating and maintaining React Native Best Practices optimized for agents and LLMs.

Structure

• rules/ - Individual rule files (one per rule)
  • _sections.md - Section metadata (titles, impacts, descriptions)
  • _template.md - Template for creating new rules
  • area-description.md - Individual rule files
• metadata.json - Document metadata (version, organization, abstract)
• AGENTS.md - Compiled output (generated)

Rules

Core Rendering (CRITICAL)

• rendering-text-in-text-component.md - Wrap strings in Text components
• rendering-no-falsy-and.md - Avoid falsy && operator in JSX

List Performance (HIGH)

• list-performance-virtualize.md - Use virtualized lists (LegendList, FlashList)
• list-performance-function-references.md - Keep stable object references
• list-performance-callbacks.md - Hoist callbacks to list root
• list-performance-inline-objects.md - Avoid inline objects in renderItem
• list-performance-item-memo.md - Pass primitives for memoization
• list-performance-item-expensive.md - Keep list items lightweight
• list-performance-images.md - Use compressed images in lists
• list-performance-item-types.md - Use item types for heterogeneous lists

Animation (HIGH)

• animation-gpu-properties.md - Animate transform/opacity instead of layout
• animation-gesture-detector-press.md - Use GestureDetector for press animations
• animation-derived-value.md - Prefer useDerivedValue over useAnimatedReaction

Scroll Performance (HIGH)

• scroll-position-no-state.md - Never track scroll in useState

Navigation (HIGH)

• navigation-native-navigators.md - Use native stack and native tabs

React State (MEDIUM)

• react-state-dispatcher.md - Use functional setState updates
• react-state-fallback.md - State should represent user intent only
• react-state-minimize.md - Minimize state variables, derive values

State Architecture (MEDIUM)

• state-ground-truth.md - State must represent ground truth

React Compiler (MEDIUM)

• react-compiler-destructure-functions.md - Destructure functions early
• react-compiler-reanimated-shared-values.md - Use .get()/.set() for shared values

User Interface (MEDIUM)

• ui-expo-image.md - Use expo-image for optimized images
• ui-image-gallery.md - Use Galeria for lightbox/galleries
• ui-menus.md - Native dropdown and context menus with Zeego
• ui-native-modals.md - Use native Modal with formSheet
• ui-pressable.md - Use Pressable instead of TouchableOpacity
• ui-measure-views.md - Measuring view dimensions
• ui-safe-area-scroll.md - Use contentInsetAdjustmentBehavior
• ui-scrollview-content-inset.md - Use contentInset for dynamic spacing
• ui-styling.md - Modern styling patterns (gap, boxShadow, gradients)

Design System (MEDIUM)

• design-system-compound-components.md - Use compound components

Monorepo (LOW)

• monorepo-native-deps-in-app.md - Install native deps in app directory
• monorepo-single-dependency-versions.md - Single dependency versions

Third-Party Dependencies (LOW)

• imports-design-system-folder.md - Import from design system folder

JavaScript (LOW)

• js-hoist-intl.md - Hoist Intl formatter creation

Fonts (LOW)

• fonts-config-plugin.md - Load fonts natively at build time

Creating a New Rule

1. Copy rules/_template.md to rules/area-description.md
2. Choose the appropriate area prefix:
   • rendering- for Core Rendering
   • list-performance- for List Performance
   • animation- for Animation
   • scroll- for Scroll Performance
   • navigation- for Navigation
   • react-state- for React State
   • state- for State Architecture
   • react-compiler- for React Compiler
   • ui- for User Interface
   • design-system- for Design System
   • monorepo- for Monorepo
   • imports- for Third-Party Dependencies
   • js- for JavaScript
   • fonts- for Fonts
3. Fill in the frontmatter and content
4. Ensure you have clear examples with explanations

Rule File Structure

Each rule file should follow this structure:

---
title: Rule Title Here
impact: MEDIUM
impactDescription: Optional description
tags: tag1, tag2, tag3
---

## Rule Title Here

Brief explanation of the rule and why it matters.

**Incorrect (description of what's wrong):**

```tsx
// Bad code example
```

Correct (description of what's right):

// Good code example

Reference: Link

## File Naming Convention

- Files starting with `_` are special (excluded from build)
- Rule files: `area-description.md` (e.g., `animation-gpu-properties.md`)
- Section is automatically inferred from filename prefix
- Rules are sorted alphabetically by title within each section

## Impact Levels

- `CRITICAL` - Highest priority, causes crashes or broken UI
- `HIGH` - Significant performance improvements
- `MEDIUM` - Moderate performance improvements
- `LOW` - Incremental improvements