Expo

expoMobile42 lines

Managed React Native tooling: config plugins, EAS builds and over-the-air updates.

Current — as published in v1.3.2. Written by hand for Expo, not generated.

The rule

Installing packages

  • npx expo install <package> for anything Expo-related — it resolves the version matching the installed SDK. Plain npm install produces version mismatches whose error messages point somewhere else entirely.
  • After adding a package with native code, the dev client must be rebuilt.

Native configuration

  • All native config goes in app.json — permissions, bundle identifiers, icons, plugins. Never edit ios/ or android/ directly: expo prebuild regenerates them and discards the change.
  • A library needing native setup ships a config plugin. Add it to plugins rather than patching the generated project.

Environment variables

  • Only EXPO_PUBLIC_* variables reach the app, and they are embedded in the bundle. Treat every one as public.
  • Secrets go in EAS secrets or on a server. Never in EXPO_PUBLIC_*.

Updates

  • eas update ships JavaScript only.
  • Any change touching native code — a new native dependency, a permission, an icon — requires a new build. Shipping an OTA update that expects a missing native module crashes the app on launch for everyone who receives it.
  • Update channels must match build channels.

Builds

  • Keep development, preview and production profiles separate in eas.json, each with its own environment variables and credentials.
  • Increment ios.buildNumber and android.versionCode for every store upload.

Never

  • Never commit a keystore, certificate, or .env.
  • Never point a non-production profile at production credentials.
  • Never hand-edit generated native folders.

As each tool receives it

The same guidance, in the shape each editor reads. Cursor and Claude Code are written separately by hand; the rest are derived from the Cursor rule.

→ .cursor/rules/expo.mdchand-written for this tool
.cursor/rules/expo.mdc
---
description: Expo conventions
globs: ["**/*.tsx", "**/*.ts", "app.json", "eas.json"]
alwaysApply: false
---

# Expo

## Installing packages

- `npx expo install <package>` for anything Expo-related — it resolves the
  version matching the installed SDK. Plain `npm install` produces version
  mismatches whose error messages point somewhere else entirely.
- After adding a package with native code, the dev client must be rebuilt.

## Native configuration

- All native config goes in `app.json` — permissions, bundle identifiers, icons,
  plugins. Never edit `ios/` or `android/` directly: `expo prebuild` regenerates
  them and discards the change.
- A library needing native setup ships a config plugin. Add it to `plugins`
  rather than patching the generated project.

## Environment variables

- Only `EXPO_PUBLIC_*` variables reach the app, and they are **embedded in the
  bundle**. Treat every one as public.
- Secrets go in EAS secrets or on a server. Never in `EXPO_PUBLIC_*`.

## Updates

- `eas update` ships JavaScript only.
- Any change touching native code — a new native dependency, a permission, an
  icon — requires a new build. Shipping an OTA update that expects a missing
  native module crashes the app on launch for everyone who receives it.
- Update channels must match build channels.

## Builds

- Keep `development`, `preview` and `production` profiles separate in
  `eas.json`, each with its own environment variables and credentials.
- Increment `ios.buildNumber` and `android.versionCode` for every store upload.

## Never

- Never commit a keystore, certificate, or `.env`.
- Never point a non-production profile at production credentials.
- Never hand-edit generated native folders.

What else this module writes

Selecting Expo contributes more than a rule file — all of it merged with every other module you pick, with conflicts resolved rather than duplicated.

Environment
EXPO_PUBLIC_API_URLrequiredBase URL the app calls. One per environment.
EXPO_PUBLIC_ENVoptionalEnvironment label used for feature gating and diagnostics.
EXPO_TOKENoptionalEAS access token. CI only — never in a local `.env` that could be committed.
Dependencies
expo^57.0.0expo-dev-client^57.0.0expo-constants^57.0.0expo-updates^57.0.0eas-cli^21.5.0dev
Folders
src/config/assets/icons/assets/splash/
Checklists
checklists/expo-release.md

Related

needsReact Native
Put this in your repo

Adds Expo to a project this tool generated, without starting over. Files you have hand-edited are left alone.