rn-fundamentals

---
name: rn-fundamentals
description: 'Use at the start of any React Native or Expo task to lock in foundational choices: Expo managed workflow as default, latest Expo SDK with New Architecture ON, TypeScript, npm. Triggers on: "starting a new RN/Expo project", "what is the right architecture for an Expo app", "managed vs bare workflow", questions about Fabric/Hermes/JSI/New Architecture, "differences between RN and React web". Also triggers as a precondition when any other rn-* skill is selected and project setup is unclear. Not for: styling (rn-styling), navigation (rn-expo-router), data (rn-data-fetching).'
---

# rn-fundamentals — foundational rules for React Native + Expo

This skill is the prerequisite read for any RN/Expo work. It sets the four non-negotiables and points you to deeper concept material when needed.

## The 4 non-negotiables

1. **Expo managed workflow** is the default. Bare workflow / `react-native init` only if there is a documented native dependency Expo cannot wrap.
2. **Latest stable Expo SDK** — `58.0.14` on 2026-10-17 (`npm view expo dist-tags`; SDK 58 stable since 2026-10-15); `[VERIFY]` at bootstrap time, quarterly cadence. **New Architecture is on and not optional** from SDK 55 onward — do *not* set `newArchEnabled`: it is ignored, and **confirmed absent from `@expo/config-types@58.0.3`'s `ExpoConfig` schema** (2026-10-17) (zero occurrences), so it is not merely discouraged — there is no key to set. Hermes is the engine.
3. **TypeScript** is mandatory. `tsconfig.json` extends **`expo/tsconfig.base`** — confirmed shipping at the root of `expo@58.0.14` (2026-10-17), and it sets `moduleResolution: "bundler"` (which is why relative imports here need no `.js` extension).
   ⚠️ **`blank-typescript` is our choice, not the CLI's default.** From `create-expo-app@4.0.0`'s own help: *"NPM template to use: default, blank, blank-typescript, tabs, bare-minimum. **Default: default**"* — and `default` is the one it labels *"recommended for most app developers"*. Pass `-t blank-typescript` explicitly or you get something else.
4. **npm** is the package manager. ⚠️ This is a **house rule**, not the CLI's preference: `create-expo-app@4.0.0` *resolves* the package manager from your environment — the `--use-npm` / `--use-yarn` / `--use-pnpm` flags are **gone** (zero occurrences in the package). Invoking it with `npx` gets you npm because npx *is* npm, not because the CLI prefers it. No Yarn, no pnpm in this set.
5. ⚠️ **`create-expo-app@4` writes agent files by default** — `AGENTS.md`, `CLAUDE.md` and `.claude/settings.json`, opt out with `--no-agents-md`. On a dev-flow project decide deliberately: a scaffolded `CLAUDE.md` sitting next to `.workflow/` is a second set of instructions nobody reconciled.

## Source of truth (Expo)

This skill set (rn-fundamentals + its 6 siblings: rn-data-fetching, rn-expo-router, rn-backend, rn-push-notifications, rn-publishing-payments, rn-animations-gestures) encodes the **workflow and opinionated stack choices** — Expo managed, New Architecture on, TanStack Query, Reanimated 4, and so on. It is NOT a frozen copy of the Expo/RN API, and it goes stale every time a new SDK ships.

For anything sensitive to the current Expo SDK — exact API shapes, CLI commands and flags, config-plugin options, deprecations, EAS behavior — do not trust this skill's wording blindly. In priority order, the authoritative source is:

1. **Live Expo docs** — https://docs.expo.dev/ (always current for the installed SDK).
2. **Expo MCP server** — `https://mcp.expo.dev/mcp` — live docs/CLI/EAS reference exposed as MCP tools. **If it is connected in this session, prefer it** over anything written across this skill set for current-version details.
3. **Official `expo/skills`** — installable as a Claude Code plugin, or via `npx skills add expo/skills` — maintained by Expo directly against the SDK release cadence.

Last swept **2026-08-26** against `expo@57.0.16`, `create-expo-app@4.0.0`, `@expo/config-types@57.0.2` and `zustand@5.0.15`; the SDK, `tsconfig.base` and `newArchEnabled` claims above re-checked **2026-10-17** against `expo@58.0.14` and `@expo/config-types@58.0.3`. Any version number, CLI command, or config key in this skill set marked `[VERIFY]` above is a candidate to have drifted since — check it against the sources above before relying on it, the same way `eve-agent` defers to `node_modules/eve/docs` instead of guessing the eve API.

## Quick decision tree

- "Should I use Expo or bare RN?" → `references/decision-tree.md`
- "What versions am I targeting?" → `references/stack-defaults.md`
- "Why does X behave differently than React on the web?" → `references/concepts.md`
- "Is this an OK pattern at the foundational level?" → `references/patterns.md`
- "Where does this piece of state live?" → `references/zustand-rn.md` (Zustand as the client-state store: selectors + `useShallow`, slices, `persist` with AsyncStorage, ⚠️ the async-hydration race — and the table for what does **not** belong in it: server data → TanStack Query, form fields → the form lib, ephemeral UI → `useState`)

## Common anti-patterns (NEVER do)

- ❌ `npx react-native init` when Expo managed would have worked — Expo is the default.
- ❌ Leaving New Architecture OFF on a new project — opt out only with a written reason.
- ❌ Mixing `yarn` and `npm install` in the same project.
- ❌ Pinning Expo SDK to a version older than the current stable without justification.

## Sources

- Course: codewithbeto.dev/rnCourse — lessons 1, 2, 3, 5, 6, 12 + "Introduction" module (free).
- Official: https://reactnative.dev/architecture/landing-page
- Official: https://docs.expo.dev/get-started/introduction/

• SKILL.md 6 KB
• references/.gitkeep 1 KB
• references/concepts.md 3 KB
• references/decision-tree.md 3 KB
• references/patterns.md 2 KB
• references/stack-defaults.md 6 KB
• references/zustand-rn.md 9 KB