Cursor rules for Expo and React Native (SDK 58, Expo Router)
A free Cursor rule (.mdc) for Expo apps: npx expo install for native packages, Expo Router files and layouts, EXPO_PUBLIC_ variables are public, SecureStore for tokens, no hand edits to generated ios/ and android/, and when Expo Go isn't enough.
- Install
.cursor/rules/expo.mdc- Last tested
- Cursor / Expo SDK 58 docs · 2026-11-12
The usual AI mistakes in an Expo app are expensive to find later: npm install pulling a version that doesn't match the SDK, a secret key in an EXPO_PUBLIC_ variable, hand edits to ios/ or android/ that vanish on the next prebuild, a NavigationContainer added on top of Expo Router, and telling you to test a new native library in Expo Go. This rule tells Cursor's agent how to avoid each one. It attaches when app.json, app.config, eas.json, files in the app directory or platform-specific files are in play.
It follows Expo's docs, checked on November 12, 2026, when SDK 58 (React Native 0.88) was the latest release: npx expo install picks versions that match your SDK and --check validates them; EXPO_PUBLIC_ variables are inlined into the bundle in plain text and only dot-notation references are replaced; SDK 55 and later run only on the New Architecture; Continuous Native Generation regenerates ios/ and android/, so native changes belong in app config or config plugins; and Expo Router treats every file in the app directory as a route, with the root _layout replacing App.tsx. New SDK 55+ templates put routes in src/app; change the paths if yours are in app/.
One timing note: Expo's SDK 58 announcement says Expo Go for SDK 58 reaches the app stores a few weeks after release, and the Expo Router quick start currently says create-expo-app without a template still creates an SDK 57 project, so pick SDK 57 if you test in Expo Go on a phone and a development build if you're on 58. Expo also publishes official Expo Skills for agents; this rule is a short, project-level complement to them. Add an AGENTS.md at the repo root if you use other coding agents, and our free Supabase rule if Supabase is your backend.
expo.mdc---
description: Expo + React Native conventions: npx expo install for native packages, Expo Router file-based routes and layouts, EXPO_PUBLIC_ env vars are public, SecureStore for tokens, Continuous Native Generation (no hand edits to ios/ and android/), Expo Go vs development builds. Use when editing an Expo or React Native app.
globs: app.json, app.config.*, eas.json, src/app/**, app/**, **/*.native.tsx, **/*.ios.tsx, **/*.android.tsx
alwaysApply: false
---
# Expo + React Native
Stack: Expo SDK [58] with React Native [0.88], Expo Router, TypeScript. Package manager: [npm | pnpm | yarn | bun]. If something here disagrees with the installed SDK or docs.expo.dev, the docs win (append `.md` to any docs URL for a Markdown version). Never invent an Expo package, prop or config key; check the SDK reference for this SDK version first.
## Commands
- Start: `npx expo start`. Lint: `npx expo lint`. Types: `[npx tsc --noEmit]`. Tests: `[jest-expo command | none]`.
- Health check after dependency changes: `npx expo install --check` and `npx expo-doctor`. Report what you ran and the result. Never say a change works on a device unless it ran on one.
## Dependencies
- Add any package that touches native code (all `expo-*` packages, `react-native-*`, `react`, `react-native`) with `npx expo install <name>`, never `npm install`. It picks the version that matches this SDK. Pass dev flags through: `npx expo install typescript -- -D`.
- Don't bump `expo`, `react` or `react-native` versions by hand. SDK upgrades are their own task: ask first.
- Before adding a library, check it supports the New Architecture. SDK 55 and later run only on the New Architecture; there is no switch to turn it off.
## Native code and config
- This project uses Continuous Native Generation: `ios/` and `android/` are generated by `npx expo prebuild` [and are git-ignored]. Don't edit them by hand; changes are lost on the next `npx expo prebuild --clean`. Change native settings in `app.json` / `app.config.ts`, or with a config plugin.
- Expo Go only runs JavaScript plus the native modules built into it. If a change adds a library with custom native code or a config plugin, say that it needs a development build (`expo-dev-client`, then `npx expo run:ios|android` or an EAS build), and don't tell the user to test it in Expo Go.
## Routing (Expo Router)
- Routes are files in `[src/app]`. Each file default-exports a screen; the URL matches the path. `index.tsx` is `/`, `[id].tsx` is a dynamic segment, a `(group)` folder isn't part of the URL, `+not-found.tsx` catches unmatched routes.
- `_layout.tsx` files define the navigator for their folder (`Stack`, `Tabs`, `NativeTabs`). The root `src/app/_layout.tsx` replaces `App.tsx`: fonts, providers and splash screen go there.
- Navigate with `<Link href="/profile">` or `useRouter()` / `router.push()`. Read params with `useLocalSearchParams()`. Don't add React Navigation's `NavigationContainer`; Expo Router already provides it.
- Keep components, hooks and utilities outside the app directory, or every file in it becomes a route.
## Environment variables and secrets
- Only `EXPO_PUBLIC_` variables reach app code, and they're inlined into the bundle in plain text. Never put a private key, secret API key or service-role key in one. Calls that need a secret go through your server (or an Expo Router API route deployed as a server).
- Reference them as `process.env.EXPO_PUBLIC_API_URL`. Destructuring or `process.env['EXPO_PUBLIC_API_URL']` isn't inlined.
- Store tokens and other sensitive values on device with `expo-secure-store` (`setItemAsync` / `getItemAsync`), never AsyncStorage. It's not available on web; handle that platform separately. Values may be rejected if very large.
## UI and platforms
- Wrap screen content in safe-area handling (`react-native-safe-area-context`). Test both iOS and Android when layout changes; mention anything you couldn't check.
- Use `expo-image` for remote images. Give lists of unknown length a virtualized list (`FlatList` or the project's list library), not `ScrollView` + `map`.
- Use platform files (`*.ios.tsx`, `*.android.tsx`, `*.web.tsx`) or `Platform.select` for real differences; don't fork whole screens for a style tweak.
## Never
- Commit `.env` files with real values, signing keys, keystores or EAS credentials.
- Run `npx expo prebuild --clean`, delete `ios/` or `android/`, or change bundle identifiers or package names without asking.