Expo React Native Coder Best Practices

Comprehensive feature development guide for Expo React Native applications. Contains 50 rules across 10 categories, covering everything from project setup to testing. Includes production-ready code templates for common features.

When to Apply

Reference these guidelines when:

• Setting up a new Expo project with TypeScript
• Building navigation with Expo Router (tabs, stacks, drawers, modals)
• Creating screens (list, detail, form, settings)
• Implementing authentication flows with protected routes
• Configuring deep linking and universal links

Rule Categories by Priority

Quick Reference

1. Project Setup & Configuration (CRITICAL)

• setup-typescript-config – Configure TypeScript with strict mode
• setup-app-config-typescript – Use typed app.config.ts
• setup-environment-variables – EXPO_PUBLIC_ prefix for client vars
• setup-eas-build-profiles – EAS build profiles per environment
• setup-development-build – Development builds vs Expo Go

2. Routing & Navigation (CRITICAL)

• route-file-based-routing – File-based routing with Expo Router
• route-tab-navigator – Tab navigator with route groups
• route-dynamic-segments – Dynamic route segments [param]
• route-stack-within-tabs – Nested stack in tabs
• route-modal-presentation – Modal screen presentation
• route-typed-routes – Enable typed routes
• route-drawer-navigator – Drawer navigator setup

3. Screen Patterns & Layouts (HIGH)

• screen-list-flashlist – FlashList for large lists
• screen-detail-params – Pass minimal data via params
• screen-loading-state – Loading and error states
• screen-pull-to-refresh – Pull-to-refresh pattern
• screen-header-options – Configure screen headers
• screen-settings-list – Settings screen with SectionList

4. Data Fetching & State (HIGH)

• data-api-routes – Server-side API routes
• data-secure-store – SecureStore for sensitive data
• data-sqlite-local – SQLite for complex local data
• data-fetch-on-focus – Refetch on screen focus
• data-async-storage-simple – AsyncStorage for preferences
• data-abort-controller – Cancel fetch on unmount

5. Authentication & Security (HIGH)

• auth-protected-routes – Stack.Protected guards
• auth-context-provider – Auth context with session
• auth-oauth-flow – OAuth with AuthSession
• auth-login-form – Login form with validation
• auth-splash-loading – Splash screen during auth check

6. Deep Linking & Universal Links (HIGH)

• link-deep-linking-scheme – Custom URL scheme
• link-universal-links-ios – iOS Universal Links
• link-android-app-links – Android App Links
• link-handle-incoming – Handle incoming URLs

7. Native UX Patterns (MEDIUM-HIGH)

• ux-safe-area-insets – SafeAreaView for notches
• ux-status-bar – Status bar styling
• ux-haptic-feedback – Haptic feedback on actions
• ux-gesture-handler – Gesture handler for swipes
• ux-keyboard-avoiding – KeyboardAvoidingView

8. Forms & User Input (MEDIUM)

• form-text-input-config – TextInput keyboard types
• form-controlled-inputs – Controlled inputs with useState
• form-submit-button-state – Disable button during submit
• form-dismiss-keyboard – Dismiss keyboard on tap outside

9. Assets & Theming (MEDIUM)

• asset-image-optimization – expo-image for caching
• asset-font-loading – Load fonts with useFonts
• asset-vector-icons – @expo/vector-icons
• asset-splash-screen – Splash screen configuration

10. Error Handling & Testing (MEDIUM)

• test-jest-setup – Jest with jest-expo preset
• test-component-testing – Testing Library for components
• test-error-boundary – Error boundaries
• test-e2e-maestro – Maestro E2E testing

Code Templates

Production-ready templates are available in assets/templates/:

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions – Category structure and impact levels
• Rule template – Template for adding new rules

Full Compiled Document

For a single comprehensive document with all rules, see AGENTS.md.

Reference Files