|
| 1 | +--- |
| 2 | +description: |
| 3 | +globs: |
| 4 | +alwaysApply: true |
| 5 | +--- |
| 6 | +# React Native Expo Project - Coding Guidelines |
| 7 | + |
| 8 | +## Project Overview |
| 9 | + |
| 10 | +React Native Expo SDK 53 project with TypeScript, Expo Router v5, Redux Toolkit, and modern development practices. |
| 11 | + |
| 12 | +## Built-in Features to Always Use |
| 13 | + |
| 14 | +### Configuration Management |
| 15 | + |
| 16 | +- **Use `utils/config.ts`** for all environment variables and app configuration |
| 17 | +- **Use `utils/deviceInfo.ts`** for platform detection and device dimensions |
| 18 | +- Never hardcode environment values, always go through config |
| 19 | + |
| 20 | +### Theme System |
| 21 | + |
| 22 | +- **Always import from `@/theme`** for colors, fonts, and images |
| 23 | +- **Use `@/theme/colors`** instead of hardcoded color values |
| 24 | +- **Use theme system** for consistent dark/light mode support |
| 25 | +- **Load assets through `@/theme/images` and `@/theme/fonts`** |
| 26 | + |
| 27 | +### Custom Hooks |
| 28 | + |
| 29 | +- **Use `useColorScheme` from `@/hooks`** for theme detection |
| 30 | +- **Use `useDataPersist` from `@/hooks`** for local storage operations |
| 31 | +- **Use `useKeyboard` from `@/hooks`** for keyboard state management |
| 32 | +- **Use `useAppSlice` from `@/slices`** for global state management |
| 33 | + |
| 34 | +### State Management |
| 35 | + |
| 36 | +- **Use Redux Toolkit slices** in `@/slices` for global state |
| 37 | +- **Import from `@/slices`** for all state operations |
| 38 | +- Keep local state minimal, prefer global state for shared data |
| 39 | + |
| 40 | +### Services Layer |
| 41 | + |
| 42 | +- **Use `@/services`** for all API calls and external integrations |
| 43 | +- Never make direct API calls from components |
| 44 | +- Use the services layer for data transformation |
| 45 | + |
| 46 | +### Type Safety |
| 47 | + |
| 48 | +- **Use types from `@/types`** for all interfaces |
| 49 | +- **Define component props interfaces** for all components |
| 50 | +- **Use TypeScript strict mode** - project is configured for it |
| 51 | + |
| 52 | +## Directory Structure Rules |
| 53 | + |
| 54 | +### Component Organization |
| 55 | + |
| 56 | +- **`components/elements`** - Reusable UI components (Button, Image, etc.) |
| 57 | +- **`components/layouts`** - Layout-specific components (headers, navigation) |
| 58 | +- **`scenes`** - Screen components (renamed from pages) |
| 59 | +- **`app`** - Expo Router routes only, delegate to scenes |
| 60 | + |
| 61 | +### File Naming |
| 62 | + |
| 63 | +- **Components**: PascalCase (`Button.tsx`, `NavigationHeader.tsx`) |
| 64 | +- **Hooks**: camelCase with "use" prefix (`useColorScheme.ts`) |
| 65 | +- **Utils**: camelCase (`deviceInfo.ts`, `config.ts`) |
| 66 | +- **Types**: PascalCase (`User.ts`, `ApiResponse.ts`) |
| 67 | + |
| 68 | +## Code Standards |
| 69 | + |
| 70 | +### Import Organization |
| 71 | + |
| 72 | +1. React and React Native imports first |
| 73 | +2. Third-party library imports |
| 74 | +3. Internal imports using `@/` paths |
| 75 | +4. Relative imports last |
| 76 | + |
| 77 | +### Component Structure |
| 78 | + |
| 79 | +- Define TypeScript interfaces for all props |
| 80 | +- Use function declarations, not arrow functions for components |
| 81 | +- Keep hooks at the top of components |
| 82 | +- Use early returns for conditional rendering |
| 83 | +- Export default at the bottom |
| 84 | + |
| 85 | +### Styling Rules |
| 86 | + |
| 87 | +- Always use `StyleSheet.create` for performance |
| 88 | +- Import colors from theme, never hardcode |
| 89 | +- Use platform-specific styles when needed |
| 90 | +- Keep styles at component bottom |
| 91 | + |
| 92 | +### Testing Requirements |
| 93 | + |
| 94 | +- One test file per component |
| 95 | +- Test component behavior, not implementation |
| 96 | +- Use descriptive test names |
| 97 | +- Mock external dependencies |
| 98 | + |
| 99 | +## Built-in Architecture Patterns |
| 100 | + |
| 101 | +### Navigation (Expo Router v5) |
| 102 | + |
| 103 | +- **Use flat config format** as project is configured |
| 104 | +- **Keep route files minimal** - delegate to scene components |
| 105 | +- **Use `<Redirect>` for programmatic navigation** |
| 106 | +- **Handle deep linking through router** |
| 107 | + |
| 108 | +### Error Handling |
| 109 | + |
| 110 | +- **Use try-catch for async operations** |
| 111 | +- **Provide user-friendly error messages** |
| 112 | +- **Log errors appropriately for debugging** |
| 113 | +- **Implement fallback UI states** |
| 114 | + |
| 115 | +### Performance |
| 116 | + |
| 117 | +- **Use React.memo for expensive components** |
| 118 | +- **Implement proper useCallback/useMemo** |
| 119 | +- **Optimize lists with proper keys** |
| 120 | +- **Lazy load components when possible** |
| 121 | + |
| 122 | +## Project-Specific Features |
| 123 | + |
| 124 | +### Environment Configuration |
| 125 | + |
| 126 | +- Project uses `expo-constants` for environment variables |
| 127 | +- Configuration is typed and validated |
| 128 | +- Use `utils/config.ts` for all config access |
| 129 | + |
| 130 | +### Theme and Styling |
| 131 | + |
| 132 | +- Dark/light mode support built-in |
| 133 | +- Theme colors are centralized and typed |
| 134 | +- Responsive design utilities available |
| 135 | + |
| 136 | +### Data Persistence |
| 137 | + |
| 138 | +- Custom hook for local data storage |
| 139 | +- Redux Toolkit for global state management |
| 140 | +- Proper data flow architecture |
| 141 | + |
| 142 | +### Platform Support |
| 143 | + |
| 144 | +- iOS, Android, and Web platform support |
| 145 | +- Platform-specific utilities available |
| 146 | +- Responsive design considerations |
| 147 | + |
| 148 | +## Development Rules |
| 149 | + |
| 150 | +### Code Quality |
| 151 | + |
| 152 | +- No `console.log` in production code |
| 153 | +- Always handle loading and error states |
| 154 | +- Write self-documenting code |
| 155 | +- Keep functions focused and small |
| 156 | + |
| 157 | +### Reusability Focus |
| 158 | + |
| 159 | +- Always check existing components before creating new ones |
| 160 | +- Use built-in utilities instead of reinventing |
| 161 | +- Extend existing components rather than duplicating |
| 162 | +- Follow established patterns in the codebase |
| 163 | + |
| 164 | +### Testing |
| 165 | + |
| 166 | +- Write tests for all new components |
| 167 | +- Ensure tests pass before committing |
| 168 | +- Test both happy path and error scenarios |
| 169 | +- Use React Native Testing Library patterns |
| 170 | + |
| 171 | +## Migration and Updates |
| 172 | + |
| 173 | +- Currently on Expo SDK 53 with React 19 |
| 174 | +- ESLint 9 with flat config |
| 175 | +- Modern React Native 0.79.5 |
| 176 | +- TypeScript strict mode enabled |
| 177 | + |
| 178 | +## Key Principles |
| 179 | + |
| 180 | +1. **Reuse existing built-in features** before creating new ones |
| 181 | +2. **Follow established patterns** in the codebase |
| 182 | +3. **Use TypeScript strictly** for better code quality |
| 183 | +4. **Test all components** for reliability |
| 184 | +5. **Keep components focused** and single-purpose |
| 185 | +6. **Use the theme system** for consistent UI |
| 186 | +7. **Leverage built-in hooks** for common functionality |
| 187 | +8. **Follow import/export conventions** for maintainability |
0 commit comments