.cursorrules (deprecated)

1# React Native + Expo + TypeScript — Cursor Rules
2# Production mobile app patterns with React Native, Expo SDK, and TypeScript
3 
4# Project Context
5You are building a cross-platform mobile application using React Native with Expo (SDK 50+)
6and TypeScript. The app targets both iOS and Android from a single codebase. The project uses
7Expo Router for navigation, React Query for server state, and follows React Native best
8practices for performance and UX.
9 
10# Project Structure (Expo Router)
11```
12app/
13  _layout.tsx             # Root layout (providers, fonts, splash screen)
14  (tabs)/
15    _layout.tsx           # Tab navigator layout
16    index.tsx             # Home tab
17    explore.tsx           # Explore tab
18    profile.tsx           # Profile tab
19  (auth)/
20    _layout.tsx           # Auth stack layout
21    login.tsx
22    register.tsx
23  [id].tsx                # Dynamic route
24  +not-found.tsx          # 404 screen
25src/
26  components/
27    ui/                   # Reusable UI components
28    screens/              # Screen-specific components
29  hooks/                  # Custom hooks
30  services/               # API client and services
31  stores/                 # Zustand/Jotai stores
32  types/                  # TypeScript types
33  utils/                  # Utilities
34  constants/              # Colors, spacing, config
35    theme.ts
36    layout.ts
37```
38 
39# Expo Router Navigation
40- Use file-based routing in the `app/` directory (like Next.js for mobile).
41- Group routes with parentheses: `(tabs)`, `(auth)`, `(modal)`.
42- Use `_layout.tsx` files to define navigators (Stack, Tabs, Drawer).
43- Navigate with typed routes:
44```typescript
45  import { router } from 'expo-router';
46  router.push('/profile/123');
47  router.replace('/(auth)/login');
48  router.back();
49```
50- Use `<Link>` component for declarative navigation.
51- Handle deep links by defining route patterns in app.json.
52- Protect routes in layout files by checking auth state and redirecting.
53 
54# Component Patterns
55- Use `StyleSheet.create()` for all styles — never inline style objects:
56```typescript
57  const styles = StyleSheet.create({
58    container: {
59      flex: 1,
60      padding: 16,
61      backgroundColor: colors.background,
62    },
63  });
64```
65- Extract dimensions and colors into theme constants:
66```typescript
67  export const colors = { primary: '#007AFF', background: '#FFFFFF', text: '#000000' } as const;
68  export const spacing = { xs: 4, sm: 8, md: 16, lg: 24, xl: 32 } as const;
69```
70- Use `Platform.select()` for platform-specific values:
71```typescript
72  const shadow = Platform.select({
73    ios: { shadowColor: '#000', shadowOffset: { width: 0, height: 2 }, shadowOpacity: 0.1 },
74    android: { elevation: 3 },
75  });
76```
77- Use `<SafeAreaView>` or `useSafeAreaInsets()` for proper safe area handling.
78 
79# Performance (Critical for Mobile)
80- Use `FlatList` for long lists — never `ScrollView` with mapped items:
81```typescript
82  <FlatList
83    data={items}
84    keyExtractor={(item) => item.id}
85    renderItem={({ item }) => <ItemCard item={item} />}
86    getItemLayout={(_, index) => ({ length: ITEM_HEIGHT, offset: ITEM_HEIGHT * index, index })}
87    initialNumToRender={10}
88    maxToRenderPerBatch={5}
89    windowSize={5}
90  />
91```
92- Memoize list item components with `React.memo()`.
93- Use `useCallback` for event handlers passed to list items.
94- Use `Animated` API or `react-native-reanimated` for 60fps animations.
95```typescript
96  // Use reanimated for gesture-driven animations
97  const translateX = useSharedValue(0);
98  const animatedStyle = useAnimatedStyle(() => ({
99    transform: [{ translateX: translateX.value }],
100  }));
101```
102- Optimize images: use `expo-image` (not React Native's `<Image>`):
103```typescript
104  import { Image } from 'expo-image';
105  <Image source={uri} contentFit="cover" placeholder={blurhash} transition={200} />
106```
107- DON'T: Use `console.log` in production — it causes performance issues on Android.
108- DON'T: Create new style objects in render — use StyleSheet.create outside the component.
109- DON'T: Use `ScrollView` for long dynamic lists — use `FlatList` or `FlashList`.
110 
111# State Management
112- Use React Query (TanStack Query) for server/API state.
113- Use Zustand for client-side global state (lighter than Redux):
114```typescript
115  import { create } from 'zustand';
116  interface AuthStore {
117    user: User | null;
118    setUser: (user: User | null) => void;
119    logout: () => void;
120  }
121  export const useAuthStore = create<AuthStore>((set) => ({
122    user: null,
123    setUser: (user) => set({ user }),
124    logout: () => set({ user: null }),
125  }));
126```
127- Use `AsyncStorage` (via zustand `persist` middleware) for persisting state across app restarts.
128- DON'T: Store server data in Zustand — use React Query for anything from an API.
129 
130# API Integration
131- Create a typed API client with interceptors:
132```typescript
133  const api = axios.create({ baseURL: process.env.EXPO_PUBLIC_API_URL });
134  api.interceptors.request.use(async (config) => {
135    const token = await SecureStore.getItemAsync('accessToken');
136    if (token) config.headers.Authorization = `Bearer ${token}`;
137    return config;
138  });
139```
140- Use React Query for all data fetching:
141```typescript
142  export function useUser(id: string) {
143    return useQuery({
144      queryKey: ['user', id],
145      queryFn: () => api.get<User>(`/users/${id}`).then(r => r.data),
146      staleTime: 5 * 60 * 1000,
147    });
148  }
149```
150- Handle offline state: show cached data, queue mutations for retry.
151- Use `useMutation` with `onMutate` for optimistic updates.
152 
153# Authentication
154- Store tokens in `expo-secure-store` (encrypted native storage), NOT AsyncStorage.
155- Implement token refresh with axios interceptors.
156- Check auth state in root layout and redirect to login if unauthenticated.
157- Support biometric authentication with `expo-local-authentication`.
158 
159# Form Handling
160- Use `react-hook-form` with zod validation for forms:
161```typescript
162  const { control, handleSubmit } = useForm<LoginForm>({
163    resolver: zodResolver(loginSchema),
164  });
165```
166- Use `<Controller>` to wrap React Native `<TextInput>` components.
167- Handle keyboard properly: use `<KeyboardAvoidingView>` or `react-native-keyboard-aware-scroll-view`.
168- Dismiss keyboard on tap outside with `<TouchableWithoutFeedback>` + `Keyboard.dismiss()`.
169 
170# Push Notifications
171- Use `expo-notifications` for push notification setup.
172- Register for push tokens on app start, send to your backend.
173- Handle notification taps to navigate to relevant screens.
174- Request notification permissions at a contextually appropriate moment (not on first launch).
175 
176# Expo-Specific Patterns
177- Use `expo-constants` for app config values.
178- Use `expo-updates` for OTA (over-the-air) updates.
179- Use `expo-splash-screen` to control splash screen visibility during asset loading.
180- Configure app.json/app.config.ts properly for both platforms.
181- Use EAS Build for production builds and EAS Submit for store submissions.
182 
183# Testing
184- Use Jest + React Native Testing Library for component tests.
185- Test hooks with `renderHook` from testing library.
186- Mock navigation: `jest.mock('expo-router')`.
187- Mock native modules: `jest.mock('expo-secure-store')`.
188- Use Detox or Maestro for E2E tests on real devices/simulators.
189 
190# Common Mistakes to Avoid
191- DON'T: Use web-specific APIs (window, document) — they don't exist in React Native.
192- DON'T: Create styles inside render functions — extract to StyleSheet.create.
193- DON'T: Use `TouchableOpacity` from React Native — use `Pressable` (more flexible).
194- DON'T: Store sensitive data in AsyncStorage — use expo-secure-store.
195- DON'T: Ignore platform differences — test on both iOS and Android.
196- DON'T: Use pixel values for responsive layout — use flex, percentages, or Dimensions API.
197- DON'T: Block the JS thread with heavy computation — use `InteractionManager` or offload to native.
198