Home › React Native / Expo › React Native + Expo Windsurf rules

React Native + Expo Windsurf rules

Windsurf rules for React Native apps on Expo SDK (New Architecture): Expo Router, native modules, and EAS builds.

WindsurfReact Native / Expo

Copy react-native.md

How to use

Save this as .windsurf/rules/react-native.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

---
trigger: glob
globs: app/**,src/**,components/**
---

# React Native + Expo

- Use Expo Router file routes in `app/` (`_layout.tsx`, `(tabs)/`, `[id].tsx`); navigate with `<Link href>` / `router.push` and typed routes.
- Add native libraries with `npx expo install <pkg>` so versions match the SDK. Prefer Expo modules (`expo-image`, `expo-secure-store`, `expo-notifications`).
- The New Architecture is on; avoid libraries that don't support it.
- Lists: `FlatList`/`FlashList` with `keyExtractor` and memoized `renderItem`; never `ScrollView` + `map` for long lists.
- Styling with `StyleSheet.create` or the project's styling library; respect safe areas (`react-native-safe-area-context`).
- Images through `expo-image` with explicit sizes.
- Secrets/tokens in `expo-secure-store`, never `AsyncStorage`. Public config via `EXPO_PUBLIC_*` env only.
- Platform differences with `Platform.select` or `.ios.tsx`/`.android.tsx` files.
- Accessibility: `accessibilityLabel` and `accessibilityRole` on touchables; hit areas ≥ 44pt.
- Native config changes go in `app.config.ts` / config plugins, not edits to generated `ios/`/`android/` folders (CNG).

## Done when
`npx tsc --noEmit`, `npx expo lint`, and `npx jest` pass, and `npx expo-doctor` reports no issues.