Skip to content
STACK IT FAST
Share

Expo Router + React Native + NativeWind

Curated rule Mobile App Updated Oct 2026 Which file does my tool read?
expo-react-native-tailwind.md

Modern cross-platform mobile architecture for Expo SDK 57, Expo Router file-based routing, React Native, NativeWind v4, and TanStack Query.

Expo React Native NativeWind Tailwind CSS TypeScript iOS Android
Formats
4 files
AGENTS.md
46 lines
CLAUDE.md
16 lines
Languages
TypeScript
Updated
Oct 2026
Used by
4 projects
Install

Writes .claude/skills/expo-react-native-tailwind/SKILL.md

$ curl -s --create-dirs -o .claude/skills/expo-react-native-tailwind/SKILL.md https://stackitfast.com/rules/expo-react-native-tailwind/SKILL.md

Rule files

AGENTS.md· 46 lines · 3.4 KB
1# Project Architecture & Guidelines (Expo Router + React Native + NativeWind)
2
3## 1. System Architecture
4- **Platform**: Expo SDK 57 with React Native 0.87 (New Architecture only since SDK 55).
5- **Navigation**: Expo Router (versioned with the SDK; file-based navigation with native stack transitions).
6- **Styling**: NativeWind v4 (Tailwind CSS compile-time engine for React Native).
7- **Server State & Networking**: TanStack Query v5 with optimistic UI updates and AsyncStorage / SecureStore persistence.
8
9## 2. Directory & Route Organization
10- `app/`: File-based navigation hierarchy:
11 - `_layout.tsx`: Root layout with `SafeAreaProvider`, `QueryClientProvider`, and theme context.
12 - `(tabs)/_layout.tsx`: Bottom tab navigator.
13 - `(auth)/`: Authentication flows (login, register, forgot-password).
14 - `modal.tsx`: Native modal presentation screens (`presentation: "modal"`).
15- `components/`: UI components categorized into `primitives/` (buttons, inputs, cards) and `features/` (domain widgets).
16- `lib/`:
17 - `api.ts`: Typed fetch client with automatic token refreshing.
18 - `storage.ts`: Encrypted storage wrapper using `expo-secure-store`.
19- `hooks/`: Custom React hooks for hardware sensors, haptics, and permissions.
20
21## 3. Native Gestures & Safe Areas
22- Always wrap root screens with `SafeAreaView` from `react-native-safe-area-context` to prevent notch and home-bar collisions.
23- Utilize `react-native-gesture-handler` and `react-native-reanimated` for 60/120fps native-thread animations.
24- Apply subtle haptic feedback using `expo-haptics` on meaningful user interactions (toggles, deletions, confirmations).
25
26## 4. Cross-Platform Styling with NativeWind
27- Write utility class names with `className="..."` supported by NativeWind v4 Babel/Metro transformer.
28- Avoid inline styles for dynamic themes; consume CSS variables mapped in `global.css`.
29- Handle platform differences via `Platform.select()` or `Platform.OS === 'ios'` only when native API differences require divergence.
30
31## 5. Performance & Offline State
32- Use `FlashList` from Shopify instead of `FlatList` for high-throughput scrolling feeds.
33- Cache server queries with TanStack Query and persist cache to device storage for offline-first responsiveness.
34- Enforce strict TypeScript compilation with zero `any` types.
35
36## 6. Testing Conventions
37- Use Jest with `jest-expo` preset for unit tests; `@testing-library/react-native` for component behavior tests.
38- 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.
39- Snapshot-test NativeWind className output sparingly; prefer behavioral assertions (`getByRole`, `getByText`) over snapshot diffs that rot on every style tweak.
40- Test both iOS and Android via EAS Build preview channels before merging changes to native config (`app.json`, `expo-module.config.json`).
41
42## 7. Git Workflow & PR Conventions
43- Conventional Commits (`feat:`, `fix:`, `refactor:`) scoped to the screen or feature, e.g. `feat(profile): add avatar upload`.
44- Any PR touching native modules or `app.json` config must include an EAS preview build link for reviewer testing on-device.
45- Run `bun run lint` and `tsc --noEmit` before requesting review; New Architecture crashes are often silent type errors.
46- Tag releases with the Expo/EAS build number, not just the git SHA, so crash reports map back to the exact submitted binary.

Works with Cursor · Claude Code · Windsurf · AGY

Architecture notes

Architecture Overview

Standardized production guidelines for Expo Router, 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.

Frequently asked questions

Does this AGENTS.md work with Cursor, Claude Code, and Windsurf?

Yes — AGENTS.md is the open, cross-tool standard supported by Cursor, Claude Code, Windsurf, and 30+ other coding agents. A dedicated .mdc file is included for Cursor's native .cursor/rules format.

Why FlashList instead of React Native's built-in FlatList?

FlashList reuses cell components instead of destroying and recreating them on scroll, which keeps memory stable and frame rates smooth on lists with hundreds or thousands of rows. FlatList's virtualization strategy starts dropping frames well before FlashList does under the same data volume.

Why does NativeWind need a Babel/Metro transformer instead of just a CSS file?

React Native has no CSS engine — there's no browser to parse a stylesheet. NativeWind compiles Tailwind utility classes into React Native StyleSheet objects at build time, so the className syntax you write maps to real native style objects at runtime with zero interpretation cost.

Used in production

Explore all stacks

Orca

1
Agentic Development Environment for Parallel Coding Agents · 6-20 people

Agent CLIs stay the user's own. Orca adds the orchestration layer around them: isolated git worktrees, a PTY daemon that outlives the UI, and a relay for mobile steering. It can support new agents without bundling them.

CopilotKit

AI Copilot & Assistant SDK · 2-5 people

A shared AG-UI protocol plus a PlatformAdapter-based channel architecture let one agent implementation power web, mobile and chat-platform surfaces from a single Nx/pnpm monorepo instead of building a separate integration per surface.

Immich

Photo & Video Management Platform · 6-20 people

Machine-learning inference is split into its own FastAPI/Python service with pluggable CPU/GPU backends so heavy models stay off the request-serving NestJS process, while BullMQ and Redis move thumbnailing and job dispatch out of the request/response path.

Bluesky App

Mobile App · 20+ people

One Expo/React Native codebase keeps three platforms in lockstep from shared UI and state code, while link shortening, OG-card rendering and web serving are split into small standalone Go/Express services so the client is not coupled to backend concerns it does not own.
Where this stack fits

Stack It First recommends it at:

Mobile · MVP · CompanionMobile · MVP · ConsumerMobile · MVP · Tool
Walk the mobile roadmap
Every stack ships as files

More AI agent coding rules and skills

View all
expo-sqlite-local-first/AGENTS.mdExpo + SQLite + Drizzle (Local-First Mobile App)Expo · React Native · Expo Routerreact-native-new-architecture/AGENTS.mdReact Native New Architecture + Native Modules (Scale)React Native · Expo · TypeScriptswiftui-compose-native/AGENTS.mdNative iOS + Android (SwiftUI + Jetpack Compose, Shared Schema)Swift · SwiftUI · Kotlinastro-static-content/AGENTS.mdAstro Static Site + Content Collections + TailwindAstro · Tailwind CSS · TypeScript