---
name: expo-react-native-tailwind
description: "Use when building, refactoring, or reviewing a Expo Router + React Native + NativeWind project (Expo, React Native, NativeWind, Tailwind CSS, TypeScript, iOS, Android). Modern cross-platform mobile architecture for Expo SDK 57, Expo Router file-based routing, React Native, NativeWind v4, and TanStack Query."
license: MIT
metadata:
  source: https://stackitfast.com/rules/expo-react-native-tailwind
  version: "2026-10-04"
---

# Expo Router + React Native + NativeWind — Agent Skill

## When to use this skill
- Any task that scaffolds, modifies, refactors, or reviews code in a Expo Router + React Native + NativeWind codebase.
- Whenever the project depends on Expo, React Native, NativeWind, Tailwind CSS, TypeScript, iOS, Android.
- Apply these guidelines before proposing architecture, database, or deployment changes.

## Guidelines
# Project Architecture & Guidelines (Expo Router + React Native + NativeWind)

## 1. System Architecture
- **Platform**: Expo SDK 57 with React Native 0.87 (New Architecture only since SDK 55).
- **Navigation**: Expo Router (versioned with the SDK; 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.

## Source
Maintained at https://stackitfast.com/rules/expo-react-native-tailwind — also available as AGENTS.md, CLAUDE.md, and Cursor .mdc.