React Native Rules
Cursor rules for React Native projects. Navigation, performance, platform handling, and testing conventions.
What it does
These Cursor rules teach Cursor the dozens of small mobile-specific conventions that keep React Native apps fast and production-ready. Drop .cursorrules at your project root and Cursor stops suggesting web-React habits inside your mobile code. FlatList over .map(). StyleSheet over inline styles. React Navigation with typed param lists. Platform.select for the parts of iOS and Android that genuinely diverge. SafeAreaView on every screen. TypeScript strict, everywhere.
What Cursor does once these rules are installed
When you ask Cursor to generate a new screen, it wraps the root in SafeAreaView, wires it into React Navigation with a typed route param list, and imports the theme tokens from your shared file. List components always use FlatList with keyExtractor, memoized renderItem, and getItemLayout when rows have predictable heights. Styling goes through StyleSheet.create() at the bottom of the file. Platform-specific shadows, padding, and behavior get isolated with Platform.select or .ios.tsx / .android.tsx splits. Animations reach for Reanimated or Moti. State management follows your choice — Zustand for simple global state, React Query for server state.
Who should use it
Teams building React Native apps on Expo or bare RN who want Cursor tab completions to match mobile conventions instead of fighting them. Developers switching between Next.js and React Native in the same week who want the editor to stop suggesting <div> and CSS modules inside mobile files. Tech leads who want a one-file answer to every 'how should we build this screen?' question new engineers ask.
What it solves
Cursor's defaults are biased toward web React. Without rules, it reaches for <div>, CSS files, unmemoized lists, and browser-only APIs. The resulting code compiles but tanks scroll performance on Android and looks wrong on iOS notches. These rules flip every default toward what actually works on a real device, so tab completions stop introducing subtle perf regressions that only show up in production.
How to install
Which tool are you using?
Not sure? Claude.ai is the website. Claude Code is the command-line tool you install separately. Cursor is a code editor that reads .cursorrules.
- 01
Open your React Native project in Cursor
Open Cursor and make sure your React Native / Expo project is open. You should see package.json, App.tsx or index.js, and ios/ or android/ folders.
Do not have Cursor? Download it free at cursor.com
- 02
Locate or create .cursorrules at the project root
In the left sidebar, navigate to the project root (same folder as package.json). Check for an existing .cursorrules file — if it is there, you can replace or extend it.
- 03
Create .cursorrules if missing
Right-click in the file explorer → 'New File' → type exactly: .cursorrules (with the leading dot) → press Enter.
Name the file exactly '.cursorrules' — no extension, dot at the start.
- 04
Copy the rules and paste them in
Click the Copy button in the rules file section below. Open .cursorrules in Cursor, select all with Cmd/Ctrl+A, and paste with Cmd/Ctrl+V.
- 05
Save and verify with a test prompt
Save with Cmd/Ctrl+S. Open Cursor Chat (Cmd/Ctrl+L) and ask: 'Create a new screen with a long list of items'. Cursor should use FlatList with keyExtractor, SafeAreaView on the root, and a StyleSheet.create object — confirming the rules are active.
Commit .cursorrules to git. Every teammate who clones the project gets the same Cursor behavior automatically.
The cursor rules file
Copy the full contents below, or download the file directly.
# React Native Cursor Rules You are an expert React Native developer shipping to iOS and Android from a singlecodebase. These rules apply to every suggestion you make in this project. ## Navigation- React Navigation v6+ is the default; Expo Router is an allowed alternative if already in use- Typed routes via RootStackParamList — every screen and every param strongly typed- Stack for screens, Tab for primary sections, Drawer only when necessary- One navigator file per stack, colocated with the screens it hosts- Linking config kept in a single place and tested per platform- Never call navigation.navigate with a free-form string — always a typed route key ## Styling- StyleSheet.create — never inline style object literals in the render tree- No arbitrary magic numbers; use a spacing / typography constants module- Colors referenced from a theme object, not hard-coded hex in components- Shadows via Platform.select with iOS shadow* and Android elevation- Avoid dynamic styles that change on every render — memoize or derive once ## Performance- FlatList for any list beyond ~10 items; never map a long array in a ScrollView- FlatList requires keyExtractor; add getItemLayout when item heights are uniform- React.memo list item components when parent re-renders are common- Avoid passing new arrow function props to memoized children — useCallback- Image caching via expo-image (preferred cross-platform) or FastImage- Avoid setState in a render; use useEffect for side effects- InteractionManager.runAfterInteractions for expensive work after navigation ## Platform- SafeAreaView wrapping every screen root — not just specific screens- KeyboardAvoidingView around every form; configure behavior per platform- Platform.select for divergent code, NEVER Platform.OS branching inside JSX- Handle iOS notch, Android status bar, and keyboard explicitly per platform- Permissions requested with expo-permissions or react-native-permissions; never assume granted- Test on both platforms before considering a feature complete ## TypeScript- strict mode on- Props typed with an interface or type alias named ComponentNameProps- No any — use unknown and narrow- Type native event handlers with the React Native event types- Type navigation route params via a shared RootStackParamList ## File Structure- src/- navigation/ (one file per navigator)- screens/ (one file per screen)- components/ (reusable UI)- features/[name]/ (feature-scoped code)- hooks/ (reusable hooks)- services/ (API clients, storage, analytics)- theme/ (colors, spacing, typography constants)- utils/ (pure helpers) ## State- React Query for server state (caching, retries, invalidation)- Zustand or Redux Toolkit for global client state- useState / useReducer for screen-local state; lift only when shared- AsyncStorage access via a typed wrapper, not directly in components ## Testing- Jest + React Native Testing Library for component tests- Detox for critical E2E flows (login, checkout, core create/edit)- Mock native modules at the jest setup level, not per testExample output
What Claude does before and after you install this cursor rules.
Cursor uses ScrollView for a 500-item list, inline styles, and skips SafeAreaView. Janky scroll on Android.
Cursor uses FlatList with keyExtractor and getItemLayout, StyleSheet objects, SafeAreaView root, and Platform.select for shadows. Smooth.
Customization tips
Swap Expo-first for bare RN if your project uses custom native modules. Update the State section if you use Redux Toolkit. For apps targeting only iOS or only Android, remove the cross-platform rules. If you rely on FlashList, raise the list-size threshold accordingly. For teams using Reanimated heavily, add a short section so Cursor reaches for useSharedValue and useAnimatedStyle by default.
Related resources
React Native Skill
Navigation patterns, performance optimizations, and platform-specific conventions for React Native projects.
Flutter + Dart Rules
Cursor rules for Flutter + Dart projects. Widget patterns, state management, naming, and error handling conventions.
Next.js + TypeScript Rules
Cursor rules for Next.js 14 App Router + strict TypeScript. Server Components, Server Actions, Zod, Tailwind, shadcn/ui.
Frequently asked questions
Does it work with Expo Router?
The default is React Navigation. To use Expo Router, edit the Navigation section of .cursorrules — swap the React Navigation rules for Expo Router patterns (file-based routing, typed Link, etc.).
Does it cover the New Architecture (Fabric / TurboModules)?
Not explicitly. The rules are architecture-agnostic. If you use Fabric-specific patterns, add a dedicated section to the rule file.
What if my app targets only iOS or only Android?
Remove the cross-platform Platform.select rules. Keep the Performance and State rules — those apply regardless of target platforms.
Does it handle animations?
Not in depth. If your project uses Reanimated or Moti, add a section covering useSharedValue, withSpring defaults, and performance guidelines.
Can I use these rules with Detox for E2E testing?
Yes. The testing section mentions Detox for critical flows. Extend it with your specific Detox conventions (test IDs, helpers, waiting strategies) if needed.
Want more like this?
Browse the full RohanKit library — free resources for Claude and Cursor.