expo-react-native

name	expo-react-native
description	Guides correct Expo SDK 52 + Expo Router + React Native implementation. Use this when building mobile screens, navigation flows, native components, styling, or data fetching in apps/mobile. Read the relevant docs first, then apply the checklist before writing code.

Expo + React Native Patterns

Mandatory: Read the docs before implementing

Before writing any mobile feature, open and read the relevant page from the official docs. The docs are the single source of truth.

Quick-reference map — match your task to the doc:

Task	Doc to read first
File-based routing basics	Expo Router: Introduction
Creating a new screen/route	Expo Router: Core Concepts
Nested navigation layouts	Expo Router: Layouts
Tab navigation	Expo Router: Tabs
Stack navigation	Expo Router: Stack
Navigating between screens	Expo Router: Navigation
Deep links and URL params	Expo Router: Dynamic Routes
Authentication flows	Expo Router: Authentication
Styling components	RN: Style
Flexbox layout	RN: Layout with Flexbox
Core UI components	RN: Core Components
Handling touches	RN: Handling Touches
Lists (FlatList / SectionList)	RN: Using List Views
Images	RN: Images
Animations	RN: Animations
Accessibility	RN: Accessibility
Performance	RN: Performance
Platform-specific code	RN: Platform-Specific Code

---

Project context

This is apps/mobile in the carwash-saas monorepo.

• Runtime: Expo SDK 52, React Native 0.76, React 18.3
• Router: Expo Router 4 (file-based, app/ directory)
• Data fetching: TanStack Query v5 with useX custom hooks
• Auth: Supabase JS with AsyncStorage persistence
• Shared packages: @carwash/lib (pure utils), @carwash/types (Zod schemas + DB types)
• No shared UI: packages/ui is web-only — build all mobile UI in apps/mobile/components/

File structure conventions

app/
  _layout.tsx          # Root layout — Providers + AuthGuard
  (auth)/              # Route group: unauthenticated screens
    _layout.tsx
    login.tsx
  (tabs)/              # Route group: authenticated tab screens
    _layout.tsx
    customers.tsx
    ...
components/            # Shared mobile-only UI components
lib/
  supabase.ts          # Supabase singleton (AsyncStorage)

Path aliases

• @/* maps to apps/mobile/ root
• Use @/lib/supabase for the Supabase client
• Use @/components/ for shared mobile components
• Use @carwash/lib, @carwash/types for shared packages

---

Implementation checklist

1. Routing and navigation (Expo Router)

• New screens are created as files inside app/ — filename becomes the route
• Route groups (name)/ are used to share layouts without affecting the URL
• _layout.tsx exports a layout component using <Stack>, <Tabs>, or <Slot>
• Dynamic routes use [param].tsx naming; access with useLocalSearchParams()
• Navigation uses router.push(), router.replace(), or <Link href="..."> — never manually manages a navigation stack
• router.replace() is used for auth redirects so the user cannot go back to the login screen
• Deep links work automatically — never break URL structure without updating any href references

2. Styling

• All styles use StyleSheet.create() — defined at the bottom of the file, after the component
• No inline style objects in JSX (except for truly dynamic values like { width: someVar })
• Layout is done with Flexbox — flex, flexDirection, justifyContent, alignItems
• No CSS module syntax, no Tailwind, no styled-components — React Native StyleSheet only
• Colors and spacing use named constants — no magic hex values or raw pixel numbers inline
• Safe area insets handled with SafeAreaView from react-native-safe-area-context or Expo Router's built-in safe area support — never hardcode status bar height

3. Core components

• Use RN core components: View, Text, TextInput, TouchableOpacity / Pressable, ScrollView, FlatList, Image
• Never use <div>, <span>, <p>, <button> — these are web-only and will throw on native
• All text content is wrapped in a <Text> component — never rendered directly in a <View>
• Use FlatList or SectionList for long scrollable lists — never ScrollView with .map() for large datasets (causes performance issues)
• FlatList always has keyExtractor returning a stable string key from DB id

4. Data fetching (TanStack Query)

• All server data is fetched via TanStack Query useQuery / useMutation hooks
• Query hooks are defined with useX naming and co-located in the same file as the screen that uses them
• queryFn calls Supabase and throws on error: if (error) throw error;
• Mutations call queryClient.invalidateQueries() on success to keep data fresh
• Loading and error states are handled in the UI — never render data without checking isLoading / isError

5. Supabase client

• Always use the singleton from @/lib/supabase — never create a new client
• Always call supabase.auth.getUser(), never getSession() — getSession() can return stale JWT tokens
• Never write directly to wash_transactions or loyalty_cards — always call the log_wash Postgres RPC
• All queries are implicitly scoped by merchant_id through RLS — never manually filter by it in app code unless constructing a UI filter

6. Platform-specific code

• Use Platform.OS === 'ios' / 'android' for platform-specific logic, not file extensions, unless the difference is significant enough to warrant separate files
• File extensions .ios.tsx / .android.tsx reserved for components with fundamentally different implementations
• Expo modules used for native features (camera, notifications, etc.) — never raw RN native modules

7. Authentication

• Auth state is managed in the root _layout.tsx via supabase.auth.onAuthStateChange
• Protected routes check session in layout, not in individual screens
• Auth redirects always use router.replace() — never router.push()
• Subscription from onAuthStateChange is always cleaned up in the useEffect return

8. Performance

• FlatList is used for any list longer than ~20 items
• useCallback wraps event handlers passed as props to list items to prevent unnecessary re-renders
• Images use resizeMode appropriate to their container
• Avoid anonymous functions and object literals in JSX props for frequently re-rendered components

---

When to extract shared mobile components

Apply the rule of two: if the same UI pattern appears in 2 or more screens, extract it to apps/mobile/components/ before writing it a third time.

What is repeating	Extract to
UI component used in 2+ screens	apps/mobile/components/
TanStack Query hook with same shape	Co-located hooks/ or same screen file until used in 2+ places
Pure calculation or transformation	packages/lib/src/ (no I/O, no side effects)
Zod schema reused across 2+ forms	packages/types/src/models.ts

Do not extract on first use. Write inline, extract on second occurrence.

---

Common anti-patterns to reject

Anti-pattern	Correct approach
<div>, <span>, <p> in JSX	Use <View>, <View>, <Text>
Text rendered directly in <View>	Always wrap in <Text>
ScrollView with .map() for long lists	Use <FlatList> with keyExtractor
Inline style objects style={{ margin: 8 }} for static values	Move to StyleSheet.create()
Hardcoded status bar height	Use SafeAreaView or useSafeAreaInsets()
supabase.auth.getSession()	Always use supabase.auth.getUser()
Creating a new Supabase client in a component	Import the singleton from @/lib/supabase
Writing directly to wash_transactions	Use the log_wash RPC
router.push() for auth redirect	Use router.replace()
Importing from packages/ui in mobile	Build a dedicated component in apps/mobile/components/
Array index as FlatList key	Use stable DB id in keyExtractor
Missing isLoading / isError handling	Always handle all TanStack Query states