10 Cursor Rules for React Native (Copy-Paste) (2026)

# tested on: 2026-07-20 — run from Expo/RN project root
mkdir -p .cursor/rules

your-expo-app/
├── .cursor/
│   └── rules/
│       ├── 00-rn-stack.mdc
│       ├── 01-typescript-strict.mdc
│       ├── 02-expo-router.mdc
│       ├── 03-stylesheet-nativewind.mdc
│       ├── 04-data-fetching-hooks.mdc
│       ├── 05-testing-jest-rntl.mdc
│       ├── 06-metro-config.mdc
│       ├── 07-env-expo-constants.mdc
│       ├── 08-navigation-typing.mdc
│       ├── 09-flatlist-performance.mdc
│       └── 10-banned-patterns.mdc
├── app/                 # Expo Router
├── components/
├── package.json
└── tsconfig.json

---
description: React Native / Expo stack identity — never invent web DOM APIs
alwaysApply: true
---

# React Native / Expo stack

- This is an **Expo (or React Native)** app — not Next.js, not React DOM.
- UI primitives: `View`, `Text`, `Pressable`, `ScrollView`, `FlatList`, `TextInput`, `Image` from `react-native`.
- Never use `div`, `span`, `button`, `onClick`, `className` for DOM, `window`, `document`, or `localStorage` unless a documented polyfill exists and is already in the repo.
- Navigation: **Expo Router** file-based routes under `app/` (or `src/app/`). Do not add `react-navigation` stacks unless the project already uses them.
- Styling: follow the project’s StyleSheet or NativeWind convention (see styling rule). Do not invent CSS modules or styled-components unless already present.
- Prefer TypeScript. Do not introduce `any` without a one-line justification comment.
- When unsure about an API, check `package.json` dependencies before suggesting a new library.

---
description: TypeScript strict mode for React Native — no silent any, typed props
globs:
  - "**/*.{ts,tsx}"
alwaysApply: false
---

# TypeScript strict (React Native)

- Respect `tsconfig` strict settings. Prefer explicit prop types for every component.
- Use `type` for props objects; export props when the component is shared.
- Avoid `as any`. Prefer `unknown` + narrowing, or generated types from APIs.
- Platform files: `foo.ios.tsx` / `foo.android.tsx` / `foo.web.tsx` — keep shared types in `foo.tsx` or a `types.ts` next to them.
- Hooks: name custom hooks `useX`; return tuples or objects with stable shapes.
- Do not disable ESLint `@typescript-eslint/no-explicit-any` project-wide to “make the AI happy.”
- Path aliases: only use aliases already defined in `tsconfig` / `babel.config` (e.g. `@/`).

---
description: Expo Router file-based routing — layouts, links, typed routes
globs:
  - "app/**/*.{ts,tsx}"
  - "src/app/**/*.{ts,tsx}"
alwaysApply: false
---

# Expo Router

- Routes live under `app/` (or `src/app/`). Prefer `_layout.tsx` for shared chrome (headers, tabs, stacks).
- Use `Link` / `router.push` / `router.replace` from `expo-router` — not raw React Navigation unless already wired.
- Prefer **typed routes** when the project has them enabled (`experiments.typedRoutes` in app config). Import `Href` types instead of stringly-typed paths when available.
- Dynamic segments: `app/users/[id].tsx` — read params with `useLocalSearchParams` and validate (string vs string[]).
- Groups: `(auth)`, `(tabs)` for organization without URL segments — do not over-nest groups.
- Loading/error: use `loading.tsx` / `error` boundaries where the Expo Router version supports them; otherwise colocate clear fallback UI.
- Do not put business logic in `_layout.tsx` beyond providers and navigation chrome.
- Deep links: keep path names stable; document any intentional rename in the PR description.

---
description: React Native StyleSheet conventions — no inline style abuse
globs:
  - "**/*.{tsx,jsx}"
alwaysApply: false
---

# Styling — StyleSheet

- Prefer `StyleSheet.create` at the bottom of the file (or a colocated `styles.ts`).
- Avoid large inline `style={{ ... }}` objects in JSX except for truly one-off dynamic values (e.g. animated height).
- Compose with arrays: `style={[styles.card, disabled && styles.cardDisabled]}`.
- Do not invent NativeWind / Tailwind `className` unless `nativewind` is in `package.json`.
- Use platform-safe spacing; prefer tokens (constants) for colors and radii already used in the repo.
- Images: set explicit `width`/`height` or use known aspect-ratio patterns — avoid layout thrash.

---
description: NativeWind / Tailwind className conventions for React Native
globs:
  - "**/*.{tsx,jsx}"
alwaysApply: false
---

# Styling — NativeWind

- Prefer `className` with NativeWind utilities already used in the codebase.
- Do not add raw `StyleSheet.create` for static layout unless needed for animated styles or third-party components that require `style`.
- Keep dynamic styles as small `style` overrides, not duplicated utility strings.
- Do not use web-only Tailwind plugins or CSS `@apply` files unless the project already has them.
- Verify `global.css` / Babel preset remains intact when suggesting config changes.

---
description: Data fetching belongs in hooks or query libs — not raw fetch in JSX
globs:
  - "app/**/*.{ts,tsx}"
  - "src/**/*.{ts,tsx}"
  - "components/**/*.{ts,tsx}"
alwaysApply: false
---

# Data fetching

- Do **not** call `fetch` / `axios` directly inside the component function body or JSX.
- Prefer: existing data library in the repo (TanStack Query, SWR, Relay, custom hooks) — match what `package.json` already has.
- If no query lib exists, create `useXQuery` / `useXMutation` hooks under `hooks/` and keep screens thin.
- Handle loading, error, and empty states explicitly for mobile (offline-friendly messaging).
- Cancel or ignore stale responses on unmount; do not setState after unmount.
- Never hardcode production API URLs or tokens in components — use env via expo-constants / existing config helpers.
- For mutations, disable double-submit (button `disabled` while pending).

---
description: Jest + React Native Testing Library patterns
globs:
  - "**/__tests__/**/*.{ts,tsx}"
  - "**/*.{test,spec}.{ts,tsx}"
alwaysApply: false
---

# Testing — Jest / RNTL

- Use **@testing-library/react-native** (RNTL) queries — prefer `getByRole` / `getByText` / `getByLabelText` over testID-only when accessible roles exist.
- Prefer `userEvent` (or project-standard fireEvent helpers) over implementation-detail probing.
- Mock `expo-router` / navigation modules the way existing tests do — do not invent a new mock style per file.
- Keep tests deterministic: no real network; mock timers when testing debounced search.
- Co-locate tests as `Component.test.tsx` or under `__tests__/` — match the repo’s existing pattern.
- Do not snapshot huge trees unless the project already relies on snapshots for that file.
- When adding a component, include a minimal happy-path test if the folder already has tests.

---
description: Metro bundler config changes — monorepo, SVG, and cache safety
globs:
  - "metro.config.*"
  - "babel.config.*"
alwaysApply: false
---

# Metro config

- Prefer minimal diffs to `metro.config.js` / `metro.config.ts`. Explain why a resolver or `watchFolders` change is required.
- Monorepos: follow Expo’s monorepo Metro guidance already linked in the repo README when present.
- Do not disable cache permanently (`RESET_CACHE` hacks) as a “fix” — document one-time `npx expo start -c` instead.
- Asset extensions / SVG transformers: only add if the dependency is already installed or the task explicitly requires it.
- Keep `babel.config.js` presets aligned with Expo (`babel-preset-expo`) unless bare RN requires otherwise.
- Never commit machine-specific absolute paths in Metro config.

---
description: Environment variables via Expo config and expo-constants — no leaked secrets
globs:
  - "app.config.*"
  - "app.json"
  - "eas.json"
  - "**/constants/**/*.{ts,tsx}"
  - "**/config/**/*.{ts,tsx}"
alwaysApply: false
---

# Env — expo-constants

- Public client env belongs in `app.config.ts` / `app.config.js` `extra` (or Expo public env patterns the project already uses).
- Read values with `expo-constants` (`Constants.expoConfig?.extra`) or the project’s existing wrapper — do not invent three competing helpers.
- Never commit `.env` secrets. Document required keys in `.env.example` only.
- Distinguish **public** vs **secret** values: anything in the client bundle is public — API secrets belong on a backend.
- EAS: use EAS Secrets / profiles in `eas.json` for build-time values; do not hardcode staging URLs in multiple files.
- When adding a new env key, update types for `extra` if the project types them.

---
description: Typed navigation and route params for Expo Router / React Navigation
globs:
  - "app/**/*.{ts,tsx}"
  - "src/app/**/*.{ts,tsx}"
  - "**/navigation/**/*.{ts,tsx}"
alwaysApply: false
---

# Navigation typing

- Prefer Expo Router typed routes when enabled; avoid `as any` on `router.push`.
- Validate `useLocalSearchParams` — treat params as `string | string[] | undefined` until narrowed.
- For React Navigation (if present): keep a central param list type; do not redefine stack params per screen.
- Deep link params: coerce IDs to the right type before API calls (number vs string).
- Do not navigate during render. Navigation side effects belong in event handlers or effects with clear guards.
- After auth state changes, prefer a single redirect strategy (layout guard) over scattered `router.replace` calls.

---
description: FlatList performance and banned React Native patterns
globs:
  - "**/*.{tsx,jsx}"
alwaysApply: false
---

# FlatList performance

- Prefer `FlatList` / `SectionList` for long lists — not `ScrollView` mapping huge arrays.
- Provide stable `keyExtractor`. Avoid index-only keys when items have IDs.
- Use `renderItem` callbacks that do not close over changing inline objects unnecessarily; extract `ListItem` components.
- Consider `getItemLayout` for fixed-height rows; set reasonable `windowSize` / `maxToRenderPerBatch` only when profiling shows need.
- Avoid anonymous heavy inline styles inside `renderItem`.
- Images in rows: cache-friendly sizing; do not decode full-resolution assets for thumbnails.

# Banned patterns

- Do not default-export messy god components with 500+ lines — prefer named exports for components/hooks when the codebase does.
- Do not abuse inline styles for entire screens (see styling rule).
- Do not add `console.log` noise in hot paths (list render, animations).
- Do not introduce class components unless maintaining legacy code.
- Do not use `TouchableOpacity` / `TouchableHighlight` for new UI if the project standardized on `Pressable`.
- Do not fetch inside `renderItem`.

---
description: Banned React Native / Expo patterns Cursor must not introduce
globs:
  - "**/*.{tsx,jsx}"
  - "**/*.{ts,js}"
alwaysApply: false
---

# Banned patterns

- No DOM / web-only APIs in native screens (`div`, `document`, `localStorage` without a polyfill already in use).
- No default-export soup: avoid `export default function` dumping helpers, types, and UI in one anonymous blob when named exports are the team norm.
- No inline-style abuse for full layouts.
- No secrets in source.
- No new state libraries if one already exists (Redux vs Zustand vs Context — match the repo).
- No `fetch` in JSX / render paths (see data-fetching rule).