# Expo Router + React Native + NativeWind — AI Agent Guidelines & Architecture Rules

> Modern cross-platform mobile architecture for Expo SDK 52, Expo Router v4 file-based routing, React Native, NativeWind v4, and TanStack Query.
> Technologies: Expo, React Native, NativeWind, Tailwind CSS, TypeScript, iOS, Android

---

## AGENTS.md
```markdown
# Project Architecture & Guidelines (Expo Router + React Native + NativeWind)

## 1. System Architecture
- **Platform**: Expo SDK 52+ with React Native 0.76+ (New Architecture enabled).
- **Navigation**: Expo Router v4 (file-based navigation with native stack transitions).
- **Styling**: NativeWind v4 (Tailwind CSS compile-time engine for React Native).
- **Server State & Networking**: TanStack Query v5 with optimistic UI updates and AsyncStorage / SecureStore persistence.

## 2. Directory & Route Organization
- `app/`: File-based navigation hierarchy:
  - `_layout.tsx`: Root layout with `SafeAreaProvider`, `QueryClientProvider`, and theme context.
  - `(tabs)/_layout.tsx`: Bottom tab navigator.
  - `(auth)/`: Authentication flows (login, register, forgot-password).
  - `modal.tsx`: Native modal presentation screens (`presentation: "modal"`).
- `components/`: UI components categorized into `primitives/` (buttons, inputs, cards) and `features/` (domain widgets).
- `lib/`:
  - `api.ts`: Typed fetch client with automatic token refreshing.
  - `storage.ts`: Encrypted storage wrapper using `expo-secure-store`.
- `hooks/`: Custom React hooks for hardware sensors, haptics, and permissions.

## 3. Native Gestures & Safe Areas
- Always wrap root screens with `SafeAreaView` from `react-native-safe-area-context` to prevent notch and home-bar collisions.
- Utilize `react-native-gesture-handler` and `react-native-reanimated` for 60/120fps native-thread animations.
- Apply subtle haptic feedback using `expo-haptics` on meaningful user interactions (toggles, deletions, confirmations).

## 4. Cross-Platform Styling with NativeWind
- Write utility class names with `className="..."` supported by NativeWind v4 Babel/Metro transformer.
- Avoid inline styles for dynamic themes; consume CSS variables mapped in `global.css`.
- Handle platform differences via `Platform.select()` or `Platform.OS === 'ios'` only when native API differences require divergence.

## 5. Performance & Offline State
- Use `FlashList` from Shopify instead of `FlatList` for high-throughput scrolling feeds.
- Cache server queries with TanStack Query and persist cache to device storage for offline-first responsiveness.
- Enforce strict TypeScript compilation with zero `any` types.

## 6. Testing Conventions
- Use Jest with `jest-expo` preset for unit tests; `@testing-library/react-native` for component behavior tests.
- Use Maestro or Detox for end-to-end flows that cross native boundaries (camera, biometrics, push notifications) — Jest alone can't exercise real native modules.
- Snapshot-test NativeWind className output sparingly; prefer behavioral assertions (`getByRole`, `getByText`) over snapshot diffs that rot on every style tweak.
- Test both iOS and Android via EAS Build preview channels before merging changes to native config (`app.json`, `expo-module.config.json`).

## 7. Git Workflow & PR Conventions
- Conventional Commits (`feat:`, `fix:`, `refactor:`) scoped to the screen or feature, e.g. `feat(profile): add avatar upload`.
- Any PR touching native modules or `app.json` config must include an EAS preview build link for reviewer testing on-device.
- Run `bun run lint` and `tsc --noEmit` before requesting review; New Architecture crashes are often silent type errors.
- Tag releases with the Expo/EAS build number, not just the git SHA, so crash reports map back to the exact submitted binary.
```

---

## CLAUDE.md
```markdown
# CLAUDE.md — Expo Router + React Native Commands & Conventions

## Common Commands
- `bun run start` - Start Metro bundler with Expo CLI
- `bun run ios` - Run application in iOS Simulator
- `bun run android` - Run application in Android Emulator
- `bun run lint` - Run ESLint and TypeScript type checking
- `bunx expo prebuild` - Generate native iOS and Android projects for custom native modules

## Code Style Guidelines
- Use file-based routing conventions strictly (`app/` directory).
- Prefer functional components with hooks; avoid class components.
- Use NativeWind `className` for styling with design tokens.
- Always handle loading, error, and empty states in data-fetching screens.
```

---

## .cursor/rules/stack.mdc
```markdown
---
description: Expo Router + React Native + NativeWind mobile architecture rules
globs: ["**/*.tsx", "**/*.ts", "app/**/*"]
alwaysApply: true
---

# Expo Router + React Native + NativeWind

- Expo SDK 52+, React Native New Architecture enabled, Expo Router v4 file-based navigation.
- Root layout wraps `SafeAreaProvider` + `QueryClientProvider`; every screen respects safe areas via `react-native-safe-area-context`.
- Use `react-native-reanimated` + `react-native-gesture-handler` for native-thread animations — never JS-thread `Animated` for gesture-driven UI.
- NativeWind `className` for styling; dynamic theme values come from CSS variables in `global.css`, not inline styles.
- `Platform.select()` / `Platform.OS` checks only when a native API genuinely diverges — don't branch for cosmetic differences.
- `FlashList` over `FlatList` for any list that can grow large; `FlatList` frame-drops past a few hundred rows.
- TanStack Query for all server state, persisted to device storage for offline-first behavior.
- Strict TypeScript, zero `any`. Always render explicit loading/error/empty states.
```

---

## Architecture Overview & Best Practices
## Architecture Overview

Standardized production guidelines for **Expo Router v4**, **React Native**, and **NativeWind v4** targeting iOS, Android, and mobile web.

### Key Advantages

- **Universal File-Based Routing**: Deep linking, modal sheets, and stack transitions configured automatically via folder structure.
- **Native 120fps Performance**: NativeWind compiles Tailwind CSS directly into React Native StyleSheet objects at build time with zero runtime CSS-in-JS overhead.
- **Cross-Platform Parity**: Unified TypeScript codebase sharing business logic and UI tokens across iOS, Android, and web.