expo_boilerplate / rules

---
description: Advanced Best Practices covering Error Handling, Environment Variables, Performance, and Accessibility rules
globs: **/*.ts, **/*.tsx
---

# Advanced Best Practices

## 🔴 Error Handling & Observability

### 1. API Error Handling
- Never allow API failures to crash the app or fail silently.
- When calling RTK Query mutations, handle `.unwrap()` errors or `isRejectedWithValue` reliably.
- Use explicit `try/catch` and fire user-facing toasts (e.g., via `react-native-toast-message`) on failure.

### 2. Global Error Boundaries
- Since `react-native-error-boundary` is installed, ensure that any major rendering block is wrapped where appropriate.
- Log fatal crashes to the logging service before presenting the fallback UI.

## 🟢 Environment Variables & Secrets

- Never use `process.env` scattered across components.
- Validate environment variables at startup. Use `zod` to schemas in a central config file (e.g., `src/config/env.ts`) so missing or invalid keys throw an immediate exception.
- Never commit `.env` or credentials. Use `Expo Secure Store` for user session tokens or keys, never `MMKV` for sensitive data.

## 🚀 Performance & Reanimated

### 1. Animations with Reanimated 4
- Differentiate between the UI thread and the JS Thread. Use `runOnJS` when invoking state changes from a worklet.
- Avoid passing massive objects to worklets; pick out primitive dependencies.

### 2. Image Loading
- Prefer `Expo Image` over standard React Native `Image` for aggressive caching and memory performance, especially in `FlashList` components.

## ♿ Accessibility (A11y)

All UI elements must be accessible.
- Pass `accessibilityRole="button"` and `accessibilityLabel` to all custom touchables.
- Account for scaling text. Since we use Restyle, configure typography variants to respect dynamic font types cleanly without breaking layout.
- Use `accessibilityState` dynamically (e.g., `selected`, `disabled`) so screen readers announce correct context.