Skip to content

lukedj78/dev-flow / rn-fundamentals

rn-fundamentals

Verified

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).

FileKindSize
SKILL.mdskill md5.6 KB
references/.gitkeepother0 B
references/concepts.mdmarkdown2.5 KB
references/decision-tree.mdmarkdown3.0 KB
references/patterns.mdmarkdown2.2 KB
references/stack-defaults.mdmarkdown6.0 KB
references/zustand-rn.mdmarkdown9.4 KB

references/zustand-rn.md

View on GitHub
# Zustand — client state in Expo + RN

The **how**, not just "use Zustand". Doc-grounded against `zustand.docs.pmnd.rs` (create, useShallow, slices pattern, persist / `createJSONStorage`) plus the Expo SecureStore reference. Verified `zustand` **5.0.15** (2026-08-26 — `stack-defaults.md` was refreshed to `^5.0.15` the same day). `createWithEqualityFn` **confirmed** in `zustand/traditional` (`traditional.d.ts`, and nowhere else). `[VERIFY]` identifiers against the installed version; the v4 → v5 surface changed and that move is one of the changes.

## Decide first: does this belong in Zustand at all?

Zustand is for **client state that outlives a screen**. Most state does not.

| State | Where it goes | Why |
|---|---|---|
| Anything the server owns (lists, details, profiles) | **TanStack Query** (`rn-data-fetching`) | cache, dedup, retry, invalidation, offline — Zustand has none of it |
| Field values, dirty/valid, submit | **the form library** | duplicating fields into a store re-renders the tree on every keystroke |
| Open/closed, hovered, selected tab *inside one screen* | **`useState`** | ephemeral, unmounts with the screen |
| Theme, locale, auth session, cart, onboarding step, feature flags | **Zustand** | read from many unrelated screens, must survive navigation |

Rule of thumb: if exactly one screen reads it, it is not global state.

## Creating a store (TypeScript)

TS requires the **curried** form `create<T>()(...)` — the extra `()` — because the state generic is invariant and cannot be inferred.

```ts
// store/cart.ts
import { create } from "zustand";

type CartItem = { id: string; qty: number };

type CartState = {
  items: CartItem[];
  // actions live in the store (see below)
  add: (id: string) => void;
  remove: (id: string) => void;
  clear: () => void;
};

export const useCartStore = create<CartState>()((set, get) => ({
  items: [],
  add: (id) =>
    set((state) => ({
      items: state.items.some((i) => i.id === id)
        ? state.items.map((i) => (i.id === id ? { ...i, qty: i.qty + 1 } : i))
        : [...state.items, { id, qty: 1 }],
    })),
  remove: (id) => set((state) => ({ items: state.items.filter((i) => i.id !== id) })),
  clear: () => set({ items: [] }),
}));
```

**Actions-in-store convention**: every mutation is a named action on the store. `set` is never called from a component, and the store is never exported raw. Consumers get verbs, not a setter. `set` merges shallowly at the top level — nested objects must be spread by hand.

Outside React (event handlers, API layer, background tasks): `useCartStore.getState().clear()` and `useCartStore.setState(...)`.

## Selectors — the re-render contract

Subscribe to the **narrowest value you actually render**. Calling the hook with no selector subscribes to the whole store and re-renders on every unrelated change.

```tsx
const qty = useCartStore((s) => s.items.length);   // ✅ atomic
const add = useCartStore((s) => s.add);            // ✅ actions are stable identities
const everything = useCartStore();                 // ❌ re-renders on any change
```

A selector that **builds a new object or array** returns a new reference every time, so `Object.is` always says "changed". Wrap it in `useShallow`:

```tsx
import { useShallow } from "zustand/react/shallow";

const { items, clear } = useCartStore(useShallow((s) => ({ items: s.items, clear: s.clear })));
const names = useMealsStore(useShallow((s) => Object.keys(s)));
```

Without `useShallow` this is the documented cause of "Maximum update depth exceeded" when reading multiple values at once.

## Slices, once the store grows

Split by domain, type each slice with `StateCreator<FullState, [], [], Slice>`, and combine in **one** bound store.

```ts
// store/slices/cart.ts
import type { StateCreator } from "zustand";

export interface CartSlice { items: CartItem[]; add: (id: string) => void }
export interface SessionSlice { userId: string | null; signOut: () => void }

export const createCartSlice: StateCreator<CartSlice & SessionSlice, [], [], CartSlice> = (set) => ({
  items: [],
  add: (id) => set((s) => ({ items: [...s.items, { id, qty: 1 }] })),
});
```

```ts
// store/index.ts
export const useBoundStore = create<CartSlice & SessionSlice>()((...a) => ({
  ...createCartSlice(...a),
  ...createSessionSlice(...a),
}));
```

Slices can call each other through `get()` (`get().add(id)`). **Apply middleware only on the combined store** — wrapping individual slices leads to unexpected behavior. With middleware, the mutator tuple changes: `StateCreator<S, [["zustand/persist", unknown]], [], Slice>`.

**Confirmed against `zustand@5.0.15`** (`middleware/persist.d.ts`), and the asymmetry is the part that
trips people writing it by hand — `persist` is typed

```ts
(initializer: StateCreator<T, [...Mps, ['zustand/persist', unknown]], Mcs>, options)
  => StateCreator<T, Mps, [['zustand/persist', U], ...Mcs]>
```

so it is **`unknown` on the way in** (what your slice declares) and **`U` on the way out** (what the
composed store exposes). Writing the store's own type where the `unknown` goes is the usual mistake.

## Persisting with AsyncStorage

`persist`'s default storage is `localStorage`, which does not exist in RN. Pass AsyncStorage through `createJSONStorage`:

```bash
npx expo install @react-native-async-storage/async-storage -- --legacy-peer-deps
```

```ts
// store/session.ts
import AsyncStorage from "@react-native-async-storage/async-storage";
import { create } from "zustand";
import { persist, createJSONStorage } from "zustand/middleware";

type SessionState = {
  userId: string | null;
  locale: "en" | "it";
  hasOnboarded: boolean;
  _hasHydrated: boolean;
  setHasHydrated: (v: boolean) => void;
  signOut: () => void;
};

export const useSessionStore = create<SessionState>()(
  persist(
    (set) => ({
      userId: null,
      locale: "en",
      hasOnboarded: false,
      _hasHydrated: false,
      setHasHydrated: (v) => set({ _hasHydrated: v }),
      signOut: () => set({ userId: null }),
    }),
    {
      name: "session",                                  // storage key — required
      storage: createJSONStorage(() => AsyncStorage),
      partialize: (s) => ({ locale: s.locale, hasOnboarded: s.hasOnboarded }),
      version: 1,
      migrate: (persisted, from) => (from === 0 ? { ...(persisted as object), locale: "en" } : persisted),
      onRehydrateStorage: () => (state, error) => {
        if (error) console.warn("rehydrate failed", error);
        state?.setHasHydrated(true);
      },
    },
  ),
);
```

Other options: `merge` (custom merge, defaults to shallow), `skipHydration: true` + `useSessionStore.persist.rehydrate()` for manual control. Runtime helpers: `.hasHydrated()`, `.onHydrate()`, `.onFinishHydration()`, `.clearStorage()`, `.setOptions()`.

### `partialize` — secrets never reach AsyncStorage

`partialize` is an **allowlist**, and the only thing standing between your store and plaintext-on-disk. AsyncStorage is unencrypted; `createJSONStorage` does `JSON.stringify` with no validation on the way back in.

- ✅ persist: locale, theme, onboarding flags, non-identifying preferences.
- ❌ never persist: access/refresh tokens, API keys, passwords, PII, payment data.

Secrets go to **`expo-secure-store`** (Keychain / Android Keystore), read at startup and held in memory only:

```ts
import * as SecureStore from "expo-secure-store";

await SecureStore.setItemAsync("session_token", token);
const token = await SecureStore.getItemAsync("session_token");
await SecureStore.deleteItemAsync("session_token");   // on sign-out
```

SecureStore is iOS/Android/tvOS only (no web) and rejects large payloads — historically ~2048 bytes on iOS. Store the token, not the profile.

## ⚠️ AsyncStorage is async — the first render sees defaults, not persisted state

The store is created **synchronously** with its initial values; rehydration lands one or more ticks later. So on the very first frame `hasOnboarded` is `false` and `locale` is `"en"` **even for a returning user**. Any redirect, gate, or `<Redirect>` in `app/_layout.tsx` that reads persisted state will fire on the wrong values — users get bounced back to onboarding, then flicker to the real screen.

Gate on hydration before you branch:

```tsx
// app/_layout.tsx
const hasHydrated = useSessionStore((s) => s._hasHydrated);
const hasOnboarded = useSessionStore((s) => s.hasOnboarded);

if (!hasHydrated) return <SplashScreenPlaceholder />;   // keep the splash up, don't guess
return hasOnboarded ? <Stack /> : <Redirect href="/onboarding" />;
```

The `_hasHydrated` + `onRehydrateStorage` pair above is the documented approach; the alternative is a `useHydration()` hook built on `.onFinishHydration()` / `.hasHydrated()`. Either way: **never branch on persisted state before hydration completes.**

## Integration in dev-flow

- Installed at scaffold by `rn-bootstrap`; stores live in `store/` (see `references/patterns.md` project layout).
- `rn-add-screen` reaches for `useState` first, Zustand only when a second unrelated screen needs the same value.
- Server data stays in TanStack Query (`rn-data-fetching`) — a Zustand store that mirrors an API response is a bug, not a cache.
- `rn-module-add auth` owns the token: `expo-secure-store` for the credential, Zustand for the derived `userId` / role, and both cleared on sign-out alongside `queryClient.clear()`.
- `rn-write-tests`: reset stores between tests (`useCartStore.setState(initialState, true)`) — module-level stores leak across test files.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall