` | Always use RN primitives |
| ``, `` | `` | ALL text MUST be inside `` |
| `onClick` | `onPress` | Use `` (not TouchableOpacity) |
| CSS `gap` | `gap` (RN 0.71+) | Works in modern Expo |
| `overflow: scroll` | `` / `` | Use FlashList for >50 items |
| localStorage | SecureStore / AsyncStorage | SecureStore for tokens, AsyncStorage for prefs |
| CSS animations | `react-native-reanimated` | For performant 60fps animations |
---
## SECURE STORAGE PATTERN
```typescript
// lib/storage.ts
import * as SecureStore from 'expo-secure-store';
export const secureStorage = {
async get(key: string): Promise {
return await SecureStore.getItemAsync(key);
},
async set(key: string, value: string): Promise {
await SecureStore.setItemAsync(key, value);
},
async delete(key: string): Promise {
await SecureStore.deleteItemAsync(key);
},
};
// SECURITY: NEVER use AsyncStorage for tokens, API keys, or credentials
// AsyncStorage is NOT encrypted — use SecureStore for anything sensitive
```
---
## LIST PERFORMANCE — FlashList
```typescript
// components/features/UserList.tsx
import { FlashList } from '@shopify/flash-list';
export function UserList({ users }: { users: User[] }) {
return (
}
keyExtractor={(item) => item.id}
ItemSeparatorComponent={() => }
ListEmptyComponent={}
/>
);
}
// RULES:
// - FlashList for >50 items (FlatList is OK for <50)
// - ALWAYS set estimatedItemSize
// - NEVER use ScrollView for dynamic lists
```
---
## PERMISSIONS PATTERN
```typescript
// hooks/useCamera.ts
import * as ImagePicker from 'expo-image-picker';
import { Alert, Linking } from 'react-native';
export function useCamera() {
async function pickImage() {
const { status } = await ImagePicker.requestCameraPermissionsAsync();
if (status !== 'granted') {
Alert.alert(
'Permissão necessária',
'Precisamos de acesso à câmera para esta funcionalidade.',
[
{ text: 'Cancelar', style: 'cancel' },
{ text: 'Configurações', onPress: () => Linking.openSettings() },
]
);
return null;
}
return await ImagePicker.launchCameraAsync({
quality: 0.8,
allowsEditing: true,
aspect: [1, 1],
});
}
return { pickImage };
}
```
---
## ROUTING TABLE (trigger → action)
| Trigger | Action |
|---------|--------|
| New screen | `app/(group)/screen.tsx` → add to `_layout.tsx` if in tabs |
| Auth flow | Root `_layout.tsx` redirect based on `useAuthStore` state |
| API call | TanStack Query hook in `hooks/use{Resource}.ts` |
| Native feature | Check Expo SDK FIRST → Expo plugin for native modules |
| Performance | FlashList, `useMemo`, avoid inline functions in render item |
| Deep link | Configure `app.json` → `scheme` + `expo-linking` |
| Push notifications | `expo-notifications` + register token → send to API |
---
## TESTING PATTERNS
```typescript
// __tests__/LoginScreen.test.tsx
import { render, fireEvent, waitFor } from '@testing-library/react-native';
import LoginScreen from '../app/(auth)/login';
jest.mock('@/stores/auth.store', () => ({
useAuthStore: () => ({
login: jest.fn().mockResolvedValue(undefined),
isAuthenticated: false,
}),
}));
test('shows validation error for empty email', async () => {
const { getByText, getByPlaceholderText } = render();
fireEvent.press(getByText('Entrar'));
await waitFor(() => {
expect(getByText('Email inválido')).toBeTruthy();
});
});
```
---
## ENV VARS (app.json + eas.json)
```json
// app.json extra
{
"expo": {
"extra": {
"apiUrl": "https://api.myapp.com",
"eas": { "projectId": "..." }
}
}
}
```
## BUILD COMMANDS
```bash
npx expo start # Dev server
npx expo start --clear # Dev with cache clear
eas build --platform ios --profile preview # iOS preview
eas build --platform android --profile preview # Android preview
eas build --platform all --profile production # Production build
eas submit --platform all # Submit to stores
npx expo install --check # Check dependency compatibility
```
---
## QUALITY GATES
□ `npx tsc --noEmit` — 0 errors
□ `npm test` — all pass
□ No tokens in AsyncStorage (use SecureStore)
□ All lists >50 items use FlashList
□ Tested on iOS simulator AND Android emulator
□ Offline state handled gracefully
□ All permissions checked before use with graceful denial
□ App runs in Expo Go for rapid iteration
---
## FORBIDDEN
- NEVER store tokens in AsyncStorage (use SecureStore)
- NEVER use `` (use `` — more customizable)
- NEVER use `` for >50 items (use FlashList)
- NEVER put text outside `` component
- NEVER use CSS `vh`/`vw` units (use `Dimensions` or `useWindowDimensions`)
- NEVER hardcode API URL (use `Constants.expoConfig.extra`)
- NEVER skip permission checks before accessing camera/location/photos