CLAUDE.md for React Native and Expo: a copyable template

What should a CLAUDE.md for React Native include?

A CLAUDE.md for a React Native app built with Expo should tell Claude Code how to add packages, run tests, make development builds and pick an EAS profile, where routes and shared code live, and your rules for native config, environment variables and platform files. Start it with @AGENTS.md, because create-expo-app now generates an AGENTS.md that Claude stops reading the moment a CLAUDE.md exists.

That AGENTS.md detail is what most React Native templates online miss, along with versions. Templates pinned to an old SDK teach Claude APIs that have since moved. The template below targets Expo SDK 58 with Expo Router, TypeScript and the default project layout. Commands and rules come from the Expo documentation and the AGENTS.md that Expo ships; state management, styling and testing choices are labeled as swappable. Memory behavior comes from Anthropic's CLAUDE.md documentation. For the file format in general, see what a CLAUDE.md file is.

One version note from the Expo Router docs: during the SDK 58 transition, create-expo-app@latest without a --template flag still creates an SDK 57 project, so check the expo version in package.json and adjust the stack line.

The React Native and Expo CLAUDE.md template

Copy this into CLAUDE.md at the project root, next to app.json. Replace the angle-bracket placeholders and delete lines that do not match your app. The core commands already live in the generated AGENTS.md, so the template adds what that file leaves out.

@AGENTS.md

# <App name>

<One sentence: what this app does and who uses it.>
Stack: Expo SDK 58, React Native, TypeScript strict, Expo Router, <npm>.
Platforms: iOS, Android<, web>. Versioned docs: https://docs.expo.dev/versions/v58.0.0/

## Commands (core ones are in AGENTS.md)
- Add a package: `npx expo install <package>`. Never `npm install <package>`
- Dev server: `npx expo start`. Clear the Metro cache: `npx expo start --clear`
- Check versions match the SDK: `npx expo install --check`
- Lint: `npx expo lint`. Typecheck: `npx tsc --noEmit`
- Unit tests, one run: `npx jest`. One file: `npx jest src/components/__tests__/card-test.tsx`
- Local native build: `npx expo run:ios` or `npx expo run:android`
- Regenerate native folders: `npx expo prebuild --clean`
- Development build on EAS: `npx eas-cli@latest build --profile development`
- Done means: lint, typecheck and tests for touched files pass, and `npx expo-doctor` is clean

## Project structure
- `src/app/`: routes only. Every file is a screen; `_layout.tsx` files define navigators
- `src/components/`, `src/hooks/`, `src/constants/`: shared code, never inside `src/app/`
- `assets/`: images and fonts
- `app.json`: app config (name, icons, permissions, config plugins)
- `eas.json`: build profiles: development, preview, production
- `ios/`, `android/`: generated by prebuild. Not committed. Never edit by hand
- Import with the `@/` alias, which maps to `src/`

## Native code and config
- Native changes go in app.json or a config plugin, then `npx expo prebuild --clean`
- Adding a library with native code needs a new development build; Expo Go will not have it
- Prefer Expo modules (expo-image, expo-router) over third-party packages when one exists
- Platform files: `name.ios.tsx`, `name.android.tsx`, `name.web.tsx`. Small differences use `Platform.OS`

## Env and secrets
- Only `EXPO_PUBLIC_` variables reach app code, and they ship in plain text in the bundle.
  Never put secrets there
- Read them as `process.env.EXPO_PUBLIC_NAME` with dot notation. Destructuring is not inlined
- Local overrides go in `.env.local` (git-ignored)

## Code style
- No `any`. Functional components and hooks only
- Styling: `StyleSheet.create` in the same file (swappable)
- State: <TanStack Query for server data, React context for app state> (swappable)

## Testing
- Jest with the `jest-expo` preset. Tests go in `__tests__/` folders as `*-test.tsx`
- `npm test` runs Jest in watch mode; agents use `npx jest <path>` instead
- Every bug fix comes with a test that failed before the fix

## Do not
- Do not run `eas build` without `--profile`; it defaults to production
- Do not run `eas submit` or `eas update` to a production channel without asking
- Do not upgrade the Expo SDK or React Native unless the task is an upgrade

## Gotchas
- A changed `EXPO_PUBLIC_` value needs a full reload of the app to show up
- Since SDK 58, only the standard .env files load (.env, .env.local, .env.development...).
  A `.env.staging` file is ignored
- <Your app's own surprises: test accounts, deep link scheme, feature flags>

How does this template work with the AGENTS.md Expo creates?

New Expo projects ship with an AGENTS.md. The create-expo-app reference says it points to the versioned Expo docs for your SDK, and that --no-agents-md skips it. The file tells agents not to trust their training data, to read the expo major version in package.json and fetch matching docs, lists the core commands (npx expo install, npx expo start, npx expo lint, npx tsc --noEmit, npx expo-doctor), and states rules for Expo Router, EAS and Continuous Native Generation. Unlike the Next.js block, it is a plain file written once, and Expo's docs suggest adding your own project instructions to it.

Claude Code's AGENTS.md rules decide what loads:

A CLAUDE.local.md also counts as a CLAUDE.md, so adding one for personal notes stops Claude from reading AGENTS.md unless your CLAUDE.md imports it. When Claude Code is installed, create-expo-app also writes .claude/settings.json with expo@claude-plugins-official under enabledPlugins. If Claude Code then says the plugin is enabled but not installed, run claude plugin install expo@claude-plugins-official, as the Expo Claude Code guide shows. The plugin adds Expo Skills and the Expo MCP Server; the Expo skill page covers the skills.

What does each part of the template do?

Commands. npx expo install resolves SDK-compatible versions, and the Expo CLI reference documents --check, which exits non-zero in CI when a package is out of line. npx jest <path> runs a single file once, per the Jest CLI docs. The prebuild --clean and run:ios lines come from the Continuous Native Generation guide. The EAS command uses npx eas-cli@latest, the form the generated AGENTS.md recommends.

Project structure. The SDK 58 default template keeps routes in src/app/ and shared code in src/components/, src/hooks/ and src/constants/, with an @/ path alias to src/ in tsconfig.json. The three profile names come from the eas.json reference, which also notes that EAS CLI uses the production profile when --profile is omitted. That is why the "Do not" section names it.

Native code and config. The CNG guide warns that manual edits to the generated android and ios folders risk being lost on the next npx expo prebuild --clean, and recommends config plugins instead. The Expo Go rule comes from the generated AGENTS.md: Expo Go only includes its bundled native modules, so a new native library needs a development build. Platform file extensions are a React Native feature described in the platform-specific code docs.

Env and secrets. The environment variables guide says EXPO_PUBLIC_ values are inlined into the bundle and visible in plain text, so they must not hold secrets. It also says only dot-notation references are inlined, that a full reload shows new values, and that SDK 58 and later load only the standard .env file names.

Testing. The Expo unit testing guide sets up Jest with the jest-expo preset, which also treats -test.tsx files as tests, and adds a jest --watchAll script. Watch mode never exits, so the template tells Claude to call Jest directly.

Which agent mistakes does the template prevent?

How do you adapt it to your project?

• Bare React Native without Expo: drop the import, prebuild and EAS lines, describe your committed ios/ and android/ folders, and list your own build and test scripts.
• Older SDK or no src/ folder: older templates keep routes in app/ at the root. Match the paths and the versioned docs link to your SDK.
• NativeWind, Zustand or Redux: replace the swappable style and state lines with one example of the pattern you use.
• Rules for one area: move them into .claude/rules/. A file with paths: ["src/app/**/*.tsx"] in its frontmatter loads only when Claude reads or edits a route file.
• Monorepo: put this file in the app's folder, for example apps/mobile/. The monorepo template shows how a root file and package files combine.

After saving, run /context in a Claude Code session and check that CLAUDE.md and AGENTS.md both appear under Memory files. Expo's own check works too: ask Claude which Expo SDK version package.json targets.

Should you write an AGENTS.md version instead?

If your team also uses Codex or Cursor, Expo's docs point you to AGENTS.md: put the template's sections below Expo's text there, and keep CLAUDE.md to the import plus Claude-only notes.

@AGENTS.md

## Claude Code only
- Use plan mode before an SDK upgrade or any change to app.json plugins
- Run `/doctor prompt-audit` after editing AGENTS.md or this file

The AGENTS.md guide covers which tools read the file, and the CLAUDE.md vs AGENTS.md comparison goes deeper on the trade-offs.

How do you keep the file useful over time?

Add a line when Claude repeats a mistake, prune lines it already follows, and update the stack line and docs link on every SDK upgrade. /doctor prompt-audit (Claude Code v2.1.283 or later) flags outdated or conflicting instructions and proposes edits. CLAUDE.md is context, not enforcement, so to block production EAS commands outright, use a hook.

If you start mobile apps often, keep the template where you can reuse it. Kipt stores prompts and Agent Skills as Markdown in a private GitHub repo you own, so you could save this as a prompt with blanks like {{sdk_version:58}} and fill them per app. The React Native skill is a useful companion. Templates for other stacks: Next.js, FastAPI, Django and Rails.