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

Priority	Category	Impact	Prefix
1	Project Setup & Configuration	CRITICAL	setup-
2	Routing & Navigation	CRITICAL	route-
3	Screen Patterns & Layouts	HIGH	screen-
4	Data Fetching & State	HIGH	data-
5	Authentication & Security	HIGH	auth-
6	Deep Linking & Universal Links	HIGH	link-
7	Native UX Patterns	MEDIUM-HIGH	ux-
8	Forms & User Input	MEDIUM	form-
9	Assets & Theming	MEDIUM	asset-
10	Error Handling & Testing	MEDIUM	test-

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/:

Template	Description
layouts/tab-layout.tsx	Bottom tab navigator with icons
layouts/auth-layout.tsx	Root layout with protected routes
screens/list-screen.tsx	List with FlashList, refresh, states
screens/detail-screen.tsx	Detail screen with param handling
screens/form-screen.tsx	Form with validation, keyboard handling
hooks/use-auth.tsx	Auth context with SecureStore
components/error-boundary.tsx	Error boundary component

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

File	Description
AGENTS.md	Complete compiled guide with all rules
references/_sections.md	Category definitions and ordering
assets/templates/	Production-ready code templates
metadata.json	Version and reference information