react-native-boilerplate / rules

---
description: 
globs: 
alwaysApply: true
---
# React Native Expo Project - Coding Guidelines

## Project Overview

React Native Expo SDK 54 project with TypeScript, Expo Router v6, Redux Toolkit, and modern development practices.

## Built-in Features to Always Use

### Configuration Management

- **Use `utils/config.ts`** for all environment variables and app configuration
- **Use `utils/deviceInfo.ts`** for platform detection and device dimensions
- Never hardcode environment values, always go through config

### Theme System

- **Always import from `@/theme`** for colors, fonts, and images
- **Use `@/theme/colors`** instead of hardcoded color values
- **Use theme system** for consistent dark/light mode support
- **Load assets through `@/theme/images` and `@/theme/fonts`**

### Custom Hooks

- **Use `useColorScheme` from `@/hooks`** for theme detection
- **Use `useDataPersist` from `@/hooks`** for local storage operations
- **Use `useKeyboard` from `@/hooks`** for keyboard state management
- **Use `useAppSlice` from `@/slices`** for global state management

### State Management

- **Use Redux Toolkit slices** in `@/slices` for global state
- **Import from `@/slices`** for all state operations
- Keep local state minimal, prefer global state for shared data

### Services Layer

- **Use `@/services`** for all API calls and external integrations
- Never make direct API calls from components
- Use the services layer for data transformation

### Type Safety

- **Use types from `@/types`** for all interfaces
- **Define component props interfaces** for all components
- **Use TypeScript strict mode** - project is configured for it

## Directory Structure Rules

### Component Organization

- **`components/elements`** - Reusable UI components (Button, Image, etc.)
- **`components/layouts`** - Layout-specific components (headers, navigation)
- **`scenes`** - Screen components (renamed from pages)
- **`app`** - Expo Router routes only, delegate to scenes

### File Naming

- **Components**: PascalCase (`Button.tsx`, `NavigationHeader.tsx`)
- **Hooks**: camelCase with "use" prefix (`useColorScheme.ts`)
- **Utils**: camelCase (`deviceInfo.ts`, `config.ts`)
- **Types**: PascalCase (`User.ts`, `ApiResponse.ts`)

## Code Standards

### Import Organization

1. React and React Native imports first
2. Third-party library imports
3. Internal imports using `@/` paths
4. Relative imports last

### Component Structure

- Define TypeScript interfaces for all props
- Use function declarations, not arrow functions for components
- Keep hooks at the top of components
- Use early returns for conditional rendering
- Export default at the bottom

### Styling Rules

- Always use `StyleSheet.create` for performance
- Import colors from theme, never hardcode
- Use platform-specific styles when needed
- Keep styles at component bottom

### Testing Requirements

- One test file per component
- Test component behavior, not implementation
- Use descriptive test names
- Mock external dependencies

### SafeAreaView Usage

- **Import from `react-native-safe-area-context`**, not React Native
- React Native's SafeAreaView is deprecated as of SDK 54

### Required Peer Dependencies

- **@expo/metro-runtime** - Required for Expo Router
- **react-native-worklets** - Required for React Native Reanimated

## Built-in Architecture Patterns

### Navigation (Expo Router v5)

- **Use flat config format** as project is configured
- **Keep route files minimal** - delegate to scene components
- **Use `<Redirect>` for programmatic navigation**
- **Handle deep linking through router**

### Error Handling

- **Use try-catch for async operations**
- **Provide user-friendly error messages**
- **Log errors appropriately for debugging**
- **Implement fallback UI states**

### Performance

- **Use React.memo for expensive components**
- **Implement proper useCallback/useMemo**
- **Optimize lists with proper keys**
- **Lazy load components when possible**

## Project-Specific Features

### Environment Configuration

- Project uses `expo-constants` for environment variables
- Configuration is typed and validated
- Use `utils/config.ts` for all config access

### Theme and Styling

- Dark/light mode support built-in
- Theme colors are centralized and typed
- Responsive design utilities available

### Data Persistence

- Custom hook for local data storage
- Redux Toolkit for global state management
- Proper data flow architecture

### Platform Support

- iOS, Android, and Web platform support
- Platform-specific utilities available
- Responsive design considerations

## Development Rules

### Code Quality

- No `console.log` in production code
- Always handle loading and error states
- Write self-documenting code
- Keep functions focused and small

### Reusability Focus

- Always check existing components before creating new ones
- Use built-in utilities instead of reinventing
- Extend existing components rather than duplicating
- Follow established patterns in the codebase

### Testing

- Write tests for all new components
- Ensure tests pass before committing
- Test both happy path and error scenarios
- Use React Native Testing Library patterns

## Migration and Updates

- Currently on Expo SDK 54 with React 19.1
- ESLint 9 with flat config
- Modern React Native 0.81.4
- TypeScript strict mode enabled (v5.9.2)

## Key Principles

1. **Reuse existing built-in features** before creating new ones
2. **Follow established patterns** in the codebase
3. **Use TypeScript strictly** for better code quality
4. **Test all components** for reliability
5. **Keep components focused** and single-purpose
6. **Use the theme system** for consistent UI
7. **Leverage built-in hooks** for common functionality
8. **Follow import/export conventions** for maintainability