How to Write .cursorrules for React Native (2026)

Write a .cursorrules file that stops Cursor from breaking your React Native app. The exact rules, the structure, and why each one matters. Built on 9 years of mobile engineering.

To write React Native AI rules for Cursor, put a .cursorrules file at the repo root that states your architecture, the native gotchas, and the design system in plain rules. Keep it short and structural. Cursor, Claude Code, and Antigravity read it on every prompt, so a one-page file stops the model from hallucinating navigation, storage, and styling. Built on 9 years of mobile engineering and AI tooling experience.

A .cursorrules file is the cheapest, highest-leverage thing you can add to a React Native repo. It is a plain text file. It takes twenty minutes. And it changes Cursor's output more than any prompt-engineering trick, because it is loaded before you even type. This is the exact file I write, rule by rule, with the reasoning behind each one.

What is a .cursorrules file and why does React Native need one?

A .cursorrules file is a plain text file Cursor reads at the start of every prompt and treats as standing instructions. React Native needs one more than most stacks because so many of its important patterns are invisible in a blank project: which image component to use, how navigation is typed, where state lives, where a feature's files belong. Cursor cannot see those, so without rules it guesses.

The guesses are the problem. They are averaged over the whole internet, not over your repo, so they pull in old patterns, web idioms, and APIs that do not exist on Hermes. The code compiles. Then it breaks navigation or leaks memory. A rules file removes the ambiguity that drives the guessing in the first place.

What should go in a React Native .cursorrules file?

A good React Native .cursorrules file covers four things: the architecture, the native gotchas, the design system, and the hard prohibitions. Everything else is noise. The model does not need your philosophy; it needs the rules it will otherwise break. Here is the full file I start every project with.

# .cursorrules for React Native

## Architecture
- Feature-first. Each feature lives in src/features/<name>/.
- Shared UI in src/components. Screens compose components.
- State: Redux Toolkit + RTK Query. No useState for server data.
- Navigation types live in src/navigation/types.ts. Use them.

## React Native gotchas (do not break these)
- Images: use expo-image. Never Image from react-native.
- Storage: MMKV. Never synchronous reads in the render path.
- No web-only APIs. No window, no document, no localStorage.
- Lists: use FlashList for anything over ~20 rows.

## Design system
- Reuse components from src/components. Do not inline styles.
- Spacing and color come from the Restyle theme tokens only.

## Hard rules
- Strict TypeScript. Never add 'any' to make an error go away.
- Do not add a dependency without asking.
- When unsure of a pattern, read a sibling feature first.

That is the whole thing. Notice it is structural, not prose. Each line is a rule the model can either follow or visibly violate, which makes review fast. Vague instructions like “write clean code” do nothing; “never add any” is enforceable.

Why do the React Native specific rules matter most?

The native gotchas matter most because they are where Cursor's general training actively misleads it. Cursor's default instinct is web-flavored. Ask it for an image and it reaches for the Image from react-native or, worse, a web pattern, when expo-image is the right call for caching and performance. The rule that says “use expo-image” pays for the whole file by itself.

Image component. Without the rule, Cursor mixes Image sources inconsistently and you get cache misses and flicker.
Synchronous storage. A storage read in the render path blocks the JS thread. The rule keeps it out.
Web-only APIs. localStorage and window do not exist on a device. The model adds them anyway unless told not to.
List rendering. A plain map over 500 rows janks. FlashList is the rule, not the suggestion.

I learned each of these rules by cleaning up the regression it prevents. This file is the residue of 9 years of mobile engineering and AI tooling experience, distilled into the dozen lines Cursor most reliably gets wrong.

How do I write and load the file step by step?

Writing the file is four steps, and the last one is the one people forget. Cursor caches context per session, so a rules file you add mid-session does nothing until you reload. Here is the order.

Declare the architecture. Write the folder structure, state, and navigation rules first. This is what tells Cursor where new code goes.
Encode the native gotchas. Add the React Native specific prohibitions. These prevent the most expensive regressions.
Point at the design system. Tell the model to reuse your components and theme tokens. This keeps the app visually coherent as it grows.
Save at the root and restart. Put .cursorrules at the repo root, then restart the Cursor session so the rules load on the next prompt.

After the restart, test it. Ask Cursor to add a small screen and watch whether it reuses your components and the right image API. If it does, the file is working. If it does not, the relevant rule is either missing or too vague to enforce. The same logic applies to a CLAUDE.md for Claude Code; the format differs, the discipline does not.

What are the most common .cursorrules mistakes?

The most common mistake is writing a rules file that is long and vague instead of short and enforceable. A two-page essay about your values gives Cursor nothing to act on; it skims it and keeps guessing. Three failure patterns show up again and again.

Prose over rules. “We value maintainable code” is unenforceable. “No any” is a rule the model can follow or break.
No native section. Generic rules that would fit any TypeScript project miss the React Native gotchas, which is exactly where Cursor fails.
Forgetting to reload. Edits to the file do nothing until you restart the session. Half the “rules don't work” reports are this.

If you keep the file structural, cover the native cases, and reload after edits, Cursor's output on your repo gets measurably tighter. For the architectural reasoning behind these rules, see why Cursor breaks your React Native app.

Where AI Mobile Launcher fits

AI Mobile Launcher ships this whole rules layer pre-written. The .cursorrules and CLAUDE.md are already tuned to a feature-first architecture and a 60+ component design system, so Cursor generates against real conventions from the first prompt. If you are a developer who wants to stop fixing AI regressions, or a founder who wants the AI to do the heavy lifting without you authoring rules by hand, start from the vibe coding boilerplate and pick a tier.