Expo + TanStack + Zustand rules for AI coding agents

# AGENTS.md - this project

Instructions for AI coding agents working in this repository.

## Project

A Expo (React Native) + TanStack Query + Zustand + Jest project.

Stack: Expo (React Native), TanStack Query, Zustand, Jest.

## Commands

- Start dev server: `npx expo start`
- Add a native-compatible package: `npx expo install <package>`
- Check project health: `npx expo-doctor`
- Type-check: `npx tsc --noEmit`
- Unit tests: `npx jest`

## Project structure

- Screens are files in `app/` (Expo Router). Layouts are `_layout.tsx`.
- Reusable components in `components/`, hooks in `hooks/`.

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## Expo (React Native)

- Install packages with `npx expo install` so versions match the Expo SDK.
- Use Expo Router for navigation (`<Link>`, `router.push`). Do not add React Navigation manually unless it is already in use.
- Use React Native primitives (`View`, `Text`, `Pressable`) only. No DOM elements.
- Use `FlatList` / `FlashList` for long lists, never `.map()` inside a `ScrollView`.
- Wrap screens in safe-area handling (`react-native-safe-area-context`).
- Env vars must start with `EXPO_PUBLIC_` to reach the app, so they are public. Keep secrets on a server.
- Store tokens with `expo-secure-store`, not AsyncStorage.
- Do not edit `ios/` or `android/` by hand when using Continuous Native Generation; use config plugins in `app.json` / `app.config.ts`.

## TanStack Query

- All server data goes through `useQuery` / `useMutation`; do not copy query results into `useState`.
- Use array query keys built by a small key factory (e.g. `todoKeys.detail(id)`).
- Invalidate or update affected queries in `onSuccess` of every mutation.
- Wrap queries in custom hooks (`useTodos()`) instead of calling `useQuery` inline everywhere.

## Zustand

- Keep stores small and split by domain.
- Select only what a component needs (`useStore((s) => s.count)`) to avoid unnecessary re-renders.
- Use Zustand for client/UI state only. Server data belongs in the data-fetching layer.

## Jest

- Co-locate tests as `*.test.ts(x)` or in `__tests__/`, matching the existing convention.
- Use React Native Testing Library or Testing Library queries by role/text, not implementation details.
- Reset mocks between tests; no shared mutable state across tests.

## Reference docs

- [Expo docs](https://docs.expo.dev)
- [TanStack Query docs](https://tanstack.com/query/latest)
- [Zustand docs](https://zustand.docs.pmnd.rs)
- [Jest docs](https://jestjs.io/docs/getting-started)

# CLAUDE.md - this project

Project instructions for Claude Code.

## Project

A Expo (React Native) + TanStack Query + Zustand + Jest project.

Stack: Expo (React Native), TanStack Query, Zustand, Jest.

## Commands

- Start dev server: `npx expo start`
- Add a native-compatible package: `npx expo install <package>`
- Check project health: `npx expo-doctor`
- Type-check: `npx tsc --noEmit`
- Unit tests: `npx jest`

## Project structure

- Screens are files in `app/` (Expo Router). Layouts are `_layout.tsx`.
- Reusable components in `components/`, hooks in `hooks/`.

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## Expo (React Native)

- Install packages with `npx expo install` so versions match the Expo SDK.
- Use Expo Router for navigation (`<Link>`, `router.push`). Do not add React Navigation manually unless it is already in use.
- Use React Native primitives (`View`, `Text`, `Pressable`) only. No DOM elements.
- Use `FlatList` / `FlashList` for long lists, never `.map()` inside a `ScrollView`.
- Wrap screens in safe-area handling (`react-native-safe-area-context`).
- Env vars must start with `EXPO_PUBLIC_` to reach the app, so they are public. Keep secrets on a server.
- Store tokens with `expo-secure-store`, not AsyncStorage.
- Do not edit `ios/` or `android/` by hand when using Continuous Native Generation; use config plugins in `app.json` / `app.config.ts`.

## TanStack Query

- All server data goes through `useQuery` / `useMutation`; do not copy query results into `useState`.
- Use array query keys built by a small key factory (e.g. `todoKeys.detail(id)`).
- Invalidate or update affected queries in `onSuccess` of every mutation.
- Wrap queries in custom hooks (`useTodos()`) instead of calling `useQuery` inline everywhere.

## Zustand

- Keep stores small and split by domain.
- Select only what a component needs (`useStore((s) => s.count)`) to avoid unnecessary re-renders.
- Use Zustand for client/UI state only. Server data belongs in the data-fetching layer.

## Jest

- Co-locate tests as `*.test.ts(x)` or in `__tests__/`, matching the existing convention.
- Use React Native Testing Library or Testing Library queries by role/text, not implementation details.
- Reset mocks between tests; no shared mutable state across tests.

## Reference docs

- [Expo docs](https://docs.expo.dev)
- [TanStack Query docs](https://tanstack.com/query/latest)
- [Zustand docs](https://zustand.docs.pmnd.rs)
- [Jest docs](https://jestjs.io/docs/getting-started)

---
description: "Core rules for this project"
alwaysApply: true
---

# this project

A Expo (React Native) + TanStack Query + Zustand + Jest project.

Stack: Expo (React Native), TanStack Query, Zustand, Jest.

## Commands

- Start dev server: `npx expo start`
- Add a native-compatible package: `npx expo install <package>`
- Check project health: `npx expo-doctor`
- Type-check: `npx tsc --noEmit`
- Unit tests: `npx jest`

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

---
description: "Expo (React Native) conventions: Expo + React Native app with Expo Router and TypeScript."
globs: app/**/*.tsx, src/**/*.tsx, src/**/*.ts, components/**/*.tsx
alwaysApply: false
---

# Expo (React Native)

- Install packages with `npx expo install` so versions match the Expo SDK.
- Use Expo Router for navigation (`<Link>`, `router.push`). Do not add React Navigation manually unless it is already in use.
- Use React Native primitives (`View`, `Text`, `Pressable`) only. No DOM elements.
- Use `FlatList` / `FlashList` for long lists, never `.map()` inside a `ScrollView`.
- Wrap screens in safe-area handling (`react-native-safe-area-context`).
- Env vars must start with `EXPO_PUBLIC_` to reach the app, so they are public. Keep secrets on a server.
- Store tokens with `expo-secure-store`, not AsyncStorage.
- Do not edit `ios/` or `android/` by hand when using Continuous Native Generation; use config plugins in `app.json` / `app.config.ts`.

Docs: https://docs.expo.dev

---
description: "TanStack Query conventions: Server-state caching with TanStack Query."
globs: **/*.tsx, **/hooks/**/*.ts
alwaysApply: false
---

# TanStack Query

- All server data goes through `useQuery` / `useMutation`; do not copy query results into `useState`.
- Use array query keys built by a small key factory (e.g. `todoKeys.detail(id)`).
- Invalidate or update affected queries in `onSuccess` of every mutation.
- Wrap queries in custom hooks (`useTodos()`) instead of calling `useQuery` inline everywhere.

Docs: https://tanstack.com/query/latest

---
description: "Zustand conventions: Lightweight client state with Zustand."
globs: **/store/**/*.ts, **/stores/**/*.ts
alwaysApply: false
---

# Zustand

- Keep stores small and split by domain.
- Select only what a component needs (`useStore((s) => s.count)`) to avoid unnecessary re-renders.
- Use Zustand for client/UI state only. Server data belongs in the data-fetching layer.

Docs: https://zustand.docs.pmnd.rs

---
description: "Jest conventions: Unit tests with Jest."
globs: **/*.test.ts, **/*.test.tsx, **/__tests__/**
alwaysApply: false
---

# Jest

- Co-locate tests as `*.test.ts(x)` or in `__tests__/`, matching the existing convention.
- Use React Native Testing Library or Testing Library queries by role/text, not implementation details.
- Reset mocks between tests; no shared mutable state across tests.

Docs: https://jestjs.io/docs/getting-started

# Cursor rules - this project

You are an expert Expo (React Native), TanStack Query, Zustand, Jest engineer working on this codebase. Follow these rules.

## Project

A Expo (React Native) + TanStack Query + Zustand + Jest project.

Stack: Expo (React Native), TanStack Query, Zustand, Jest.

## Commands

- Start dev server: `npx expo start`
- Add a native-compatible package: `npx expo install <package>`
- Check project health: `npx expo-doctor`
- Type-check: `npx tsc --noEmit`
- Unit tests: `npx jest`

## Project structure

- Screens are files in `app/` (Expo Router). Layouts are `_layout.tsx`.
- Reusable components in `components/`, hooks in `hooks/`.

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## Expo (React Native)

- Install packages with `npx expo install` so versions match the Expo SDK.
- Use Expo Router for navigation (`<Link>`, `router.push`). Do not add React Navigation manually unless it is already in use.
- Use React Native primitives (`View`, `Text`, `Pressable`) only. No DOM elements.
- Use `FlatList` / `FlashList` for long lists, never `.map()` inside a `ScrollView`.
- Wrap screens in safe-area handling (`react-native-safe-area-context`).
- Env vars must start with `EXPO_PUBLIC_` to reach the app, so they are public. Keep secrets on a server.
- Store tokens with `expo-secure-store`, not AsyncStorage.
- Do not edit `ios/` or `android/` by hand when using Continuous Native Generation; use config plugins in `app.json` / `app.config.ts`.

## TanStack Query

- All server data goes through `useQuery` / `useMutation`; do not copy query results into `useState`.
- Use array query keys built by a small key factory (e.g. `todoKeys.detail(id)`).
- Invalidate or update affected queries in `onSuccess` of every mutation.
- Wrap queries in custom hooks (`useTodos()`) instead of calling `useQuery` inline everywhere.

## Zustand

- Keep stores small and split by domain.
- Select only what a component needs (`useStore((s) => s.count)`) to avoid unnecessary re-renders.
- Use Zustand for client/UI state only. Server data belongs in the data-fetching layer.

## Jest

- Co-locate tests as `*.test.ts(x)` or in `__tests__/`, matching the existing convention.
- Use React Native Testing Library or Testing Library queries by role/text, not implementation details.
- Reset mocks between tests; no shared mutable state across tests.

## Reference docs

- [Expo docs](https://docs.expo.dev)
- [TanStack Query docs](https://tanstack.com/query/latest)
- [Zustand docs](https://zustand.docs.pmnd.rs)
- [Jest docs](https://jestjs.io/docs/getting-started)

# Copilot instructions - this project

A Expo (React Native) + TanStack Query + Zustand + Jest project.

Stack: Expo (React Native), TanStack Query, Zustand, Jest.

## Commands

- Start dev server: `npx expo start`
- Add a native-compatible package: `npx expo install <package>`
- Check project health: `npx expo-doctor`
- Type-check: `npx tsc --noEmit`
- Unit tests: `npx jest`

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

---
applyTo: "app/**/*.tsx,src/**/*.tsx,src/**/*.ts,components/**/*.tsx"
---

# Expo (React Native)

- Install packages with `npx expo install` so versions match the Expo SDK.
- Use Expo Router for navigation (`<Link>`, `router.push`). Do not add React Navigation manually unless it is already in use.
- Use React Native primitives (`View`, `Text`, `Pressable`) only. No DOM elements.
- Use `FlatList` / `FlashList` for long lists, never `.map()` inside a `ScrollView`.
- Wrap screens in safe-area handling (`react-native-safe-area-context`).
- Env vars must start with `EXPO_PUBLIC_` to reach the app, so they are public. Keep secrets on a server.
- Store tokens with `expo-secure-store`, not AsyncStorage.
- Do not edit `ios/` or `android/` by hand when using Continuous Native Generation; use config plugins in `app.json` / `app.config.ts`.

---
applyTo: "**/*.tsx,**/hooks/**/*.ts"
---

# TanStack Query

- All server data goes through `useQuery` / `useMutation`; do not copy query results into `useState`.
- Use array query keys built by a small key factory (e.g. `todoKeys.detail(id)`).
- Invalidate or update affected queries in `onSuccess` of every mutation.
- Wrap queries in custom hooks (`useTodos()`) instead of calling `useQuery` inline everywhere.

---
applyTo: "**/store/**/*.ts,**/stores/**/*.ts"
---

# Zustand

- Keep stores small and split by domain.
- Select only what a component needs (`useStore((s) => s.count)`) to avoid unnecessary re-renders.
- Use Zustand for client/UI state only. Server data belongs in the data-fetching layer.

---
applyTo: "**/*.test.ts,**/*.test.tsx,**/__tests__/**"
---

# Jest

- Co-locate tests as `*.test.ts(x)` or in `__tests__/`, matching the existing convention.
- Use React Native Testing Library or Testing Library queries by role/text, not implementation details.
- Reset mocks between tests; no shared mutable state across tests.

---
trigger: always_on
---

# this project

A Expo (React Native) + TanStack Query + Zustand + Jest project.

Stack: Expo (React Native), TanStack Query, Zustand, Jest.

## Commands

- Start dev server: `npx expo start`
- Add a native-compatible package: `npx expo install <package>`
- Check project health: `npx expo-doctor`
- Type-check: `npx tsc --noEmit`
- Unit tests: `npx jest`

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

---
trigger: glob
globs: app/**/*.tsx, src/**/*.tsx, src/**/*.ts, components/**/*.tsx
---

# Expo (React Native)

- Install packages with `npx expo install` so versions match the Expo SDK.
- Use Expo Router for navigation (`<Link>`, `router.push`). Do not add React Navigation manually unless it is already in use.
- Use React Native primitives (`View`, `Text`, `Pressable`) only. No DOM elements.
- Use `FlatList` / `FlashList` for long lists, never `.map()` inside a `ScrollView`.
- Wrap screens in safe-area handling (`react-native-safe-area-context`).
- Env vars must start with `EXPO_PUBLIC_` to reach the app, so they are public. Keep secrets on a server.
- Store tokens with `expo-secure-store`, not AsyncStorage.
- Do not edit `ios/` or `android/` by hand when using Continuous Native Generation; use config plugins in `app.json` / `app.config.ts`.

---
trigger: glob
globs: **/*.tsx, **/hooks/**/*.ts
---

# TanStack Query

- All server data goes through `useQuery` / `useMutation`; do not copy query results into `useState`.
- Use array query keys built by a small key factory (e.g. `todoKeys.detail(id)`).
- Invalidate or update affected queries in `onSuccess` of every mutation.
- Wrap queries in custom hooks (`useTodos()`) instead of calling `useQuery` inline everywhere.

---
trigger: glob
globs: **/store/**/*.ts, **/stores/**/*.ts
---

# Zustand

- Keep stores small and split by domain.
- Select only what a component needs (`useStore((s) => s.count)`) to avoid unnecessary re-renders.
- Use Zustand for client/UI state only. Server data belongs in the data-fetching layer.

---
trigger: glob
globs: **/*.test.ts, **/*.test.tsx, **/__tests__/**
---

# Jest

- Co-locate tests as `*.test.ts(x)` or in `__tests__/`, matching the existing convention.
- Use React Native Testing Library or Testing Library queries by role/text, not implementation details.
- Reset mocks between tests; no shared mutable state across tests.

# GEMINI.md - this project

Project context for Gemini CLI.

## Project

A Expo (React Native) + TanStack Query + Zustand + Jest project.

Stack: Expo (React Native), TanStack Query, Zustand, Jest.

## Commands

- Start dev server: `npx expo start`
- Add a native-compatible package: `npx expo install <package>`
- Check project health: `npx expo-doctor`
- Type-check: `npx tsc --noEmit`
- Unit tests: `npx jest`

## Project structure

- Screens are files in `app/` (Expo Router). Layouts are `_layout.tsx`.
- Reusable components in `components/`, hooks in `hooks/`.

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## Expo (React Native)

- Install packages with `npx expo install` so versions match the Expo SDK.
- Use Expo Router for navigation (`<Link>`, `router.push`). Do not add React Navigation manually unless it is already in use.
- Use React Native primitives (`View`, `Text`, `Pressable`) only. No DOM elements.
- Use `FlatList` / `FlashList` for long lists, never `.map()` inside a `ScrollView`.
- Wrap screens in safe-area handling (`react-native-safe-area-context`).
- Env vars must start with `EXPO_PUBLIC_` to reach the app, so they are public. Keep secrets on a server.
- Store tokens with `expo-secure-store`, not AsyncStorage.
- Do not edit `ios/` or `android/` by hand when using Continuous Native Generation; use config plugins in `app.json` / `app.config.ts`.

## TanStack Query

- All server data goes through `useQuery` / `useMutation`; do not copy query results into `useState`.
- Use array query keys built by a small key factory (e.g. `todoKeys.detail(id)`).
- Invalidate or update affected queries in `onSuccess` of every mutation.
- Wrap queries in custom hooks (`useTodos()`) instead of calling `useQuery` inline everywhere.

## Zustand

- Keep stores small and split by domain.
- Select only what a component needs (`useStore((s) => s.count)`) to avoid unnecessary re-renders.
- Use Zustand for client/UI state only. Server data belongs in the data-fetching layer.

## Jest

- Co-locate tests as `*.test.ts(x)` or in `__tests__/`, matching the existing convention.
- Use React Native Testing Library or Testing Library queries by role/text, not implementation details.
- Reset mocks between tests; no shared mutable state across tests.

## Reference docs

- [Expo docs](https://docs.expo.dev)
- [TanStack Query docs](https://tanstack.com/query/latest)
- [Zustand docs](https://zustand.docs.pmnd.rs)
- [Jest docs](https://jestjs.io/docs/getting-started)