vl-react-native-skills

# 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. > **Portability note:** This skill reads sibling files (`rules/*.md` and the > compiled `AGENTS.md`) relative to this SKILL.md. If those files are not > shipped alongside it, apply the inline Quick Reference rules directly — the > rule names below are self-describing and need no VPS-specific path. ## Single-voice craft (do NOT parallelize) This is one coherent engineering-guidance voice, not a multi-angle audit. Do **not** fan out into parallel sub-agents or split categories across workers — RN guidance must stay internally consistent (one navigation stack choice, one styling system, one list strategy) or it contradicts itself. Read the relevant rule file(s), apply, move on. Craft upgrades when applying these rules: 1. **Cite the rule name in every change.** When you apply guidance, name it (e.g. "`list-performance-virtualize` → swapped FlatList for FlashList") so the reviewer can trace each edit to a rule. No silent restyling of adjacent code (R-KARPATHY: surgical changes). 2. **Resolve conflicts toward the higher-priority category.** Priorities are ordered 1 (List Performance, CRITICAL) → 8 (Config, LOW). If two rules pull different directions, the lower-numbered category wins; state the tradeoff. 3. **Match the existing project, don't impose.** Detect the app's current stack (NativeWind vs StyleSheet, expo-image vs Image, native vs JS nav) before recommending — apply the rule in the project's idiom rather than rewriting its conventions. ## Output contract - **Produces:** RN/Expo code changes (or a review) where each change maps to a named rule above, plus a short list of `rule-name → what changed`. - **Verify:** the app/component still type-checks and renders (`tsc --noEmit` or the project's lint/build); animations run on the UI thread (transform/opacity only); lists use FlashList with stable keys. A change that doesn't build is not done (L0). - **Evidence / no hallucination:** only apply rules listed here or in `rules/`. Do not invent RN APIs — if a rule file is absent, fall back to the documented Quick Reference name and verify the API against current Expo/RN docs before using it. No regressions: never remove working behavior to satisfy a rule. ## 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`