Skip to content

CLAUDE.md

Latest commit

 

History

History
236 lines (171 loc) · 7.38 KB

CLAUDE.md

File metadata and controls

236 lines (171 loc) · 7.38 KB

Claude AI Development Guide

This React Native Expo project follows specific patterns and uses built-in features for consistency and reusability.

Project Context

Technology Stack:

  • React Native with Expo SDK 54
  • TypeScript (strict mode)
  • Expo Router v6 (flat config)
  • Redux Toolkit for state management
  • ESLint 9 with flat config
  • React 19.1 and React Native 0.81.4

Always Use These Built-in Features

Configuration & Environment

  • utils/config.ts - For all environment variables and app configuration
  • utils/deviceInfo.ts - For platform detection, screen dimensions, and device info
  • Never hardcode values that should come from configuration

Theme & Styling

  • @/theme/colors - For all color values (supports dark/light mode)
  • @/theme/fonts - For font loading and typography
  • @/theme/images - For image assets and loading
  • Always use theme system instead of hardcoded styles

Custom Hooks (Reuse These)

  • useColorScheme from @/hooks - For dark/light theme detection
  • useDataPersist from @/hooks - For local storage operations
  • useKeyboard from @/hooks - For keyboard state management
  • useAppSlice from @/slices - For global state operations

State Management

  • Redux Toolkit slices in @/slices - For all global state
  • Use useAppSlice for accessing global state
  • Keep local state minimal, prefer global state for shared data

Services & API

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

Type Definitions

  • @/types - For all TypeScript interfaces and types
  • Always define component prop interfaces
  • Use strict TypeScript - project is configured for it

Directory Structure

app/                 # Expo Router routes (keep minimal, delegate to scenes)
components/
  elements/          # Reusable UI components (Button, Image, etc.)
  layouts/           # Layout-specific components (headers, navigation)
scenes/              # Screen components (main UI logic)
hooks/               # Custom React hooks
slices/              # Redux Toolkit slices
services/            # API and external services
theme/               # Colors, fonts, styling system
types/               # TypeScript type definitions
utils/               # Utility functions (config, deviceInfo)

Component Development Patterns

Component Structure

  1. Define TypeScript interface for props
  2. Use function declarations (not arrow functions)
  3. Place hooks at the top
  4. Use early returns for conditional rendering
  5. Use StyleSheet.create for styles
  6. Export default at bottom

Import Order

  1. React and React Native
  2. Third-party libraries
  3. Internal imports with @/ paths
  4. Relative imports

File Naming

  • Components: PascalCase (Button.tsx)
  • Hooks: camelCase with "use" prefix (useColorScheme.ts)
  • Utils: camelCase (deviceInfo.ts)
  • Types: PascalCase (User.ts)

Development Guidelines

When Creating Components

  1. Check if similar component exists in components/elements
  2. Use existing built-in features instead of creating new ones
  3. Import theme colors instead of hardcoding
  4. Use TypeScript interfaces for all props
  5. Write tests for all new components

State Management Rules

  • Use Redux Toolkit for global state
  • Use useAppSlice for state operations
  • Keep component state local only when not shared
  • Use built-in hooks for common functionality

Styling Rules

  • Always import from @/theme/colors
  • Use StyleSheet.create for performance
  • Use platform-specific styles when needed
  • Support dark/light mode through theme system

Testing Requirements

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

Navigation (Expo Router v5)

  • Use flat config format (already configured)
  • Keep route files minimal - delegate to scene components
  • Use <Redirect> for programmatic navigation
  • Handle deep linking through router

Code Quality Standards

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

Key Development Principles

  1. Reuse First - Always check existing components and utilities before creating new ones
  2. Follow Patterns - Use established patterns in the codebase
  3. Use Built-ins - Leverage project's built-in features (theme, hooks, utils)
  4. Type Safety - Use TypeScript strictly for better code quality
  5. Test Everything - Write tests for all components
  6. Stay Consistent - Follow naming conventions and code structure

Common Utilities Available

Device & Platform

// From utils/deviceInfo.ts
import { isIos, isAndroid, windowWidth, windowHeight } from '@/utils/deviceInfo';

Configuration

// From utils/config.ts
import config from '@/utils/config';
// Access env and apiUrl

Theme

// From @/theme
import { colors, loadFonts, loadImages } from '@/theme';

Hooks

// From @/hooks
import useColorScheme from '@/hooks/useColorScheme';
import { useDataPersist } from '@/hooks';

Architecture Notes

  • Project upgraded to Expo SDK 54
  • Using React 19.1 with React Native 0.81.4
  • ESLint 9 with flat config
  • Directory "pages" was renamed to "scenes"
  • TypeScript strict mode enabled (v5.9.2)
  • Custom theme system with dark/light support
  • SafeAreaView imported from react-native-safe-area-context (not React Native)
  • Required peer dependencies: @expo/metro-runtime, react-native-worklets

Available Scripts

Development Commands:

  • npm run dev - Start Expo development server for all platforms with cache cleared
  • npm run dev:ios - Start development server for iOS simulator only
  • npm run dev:android - Start development server for Android emulator only
  • npm run dev:web - Start development server for web browser only
  • npm run dev:doctor - Run Expo diagnostics to check project health

Building & Deployment:

  • npm run dev:build:mobile - Build iOS (IPA) and Android (APK) using EAS Build for development
  • npm run dev:build:web - Export static web application to dist/ directory
  • npm run dev:serve:web - Serve the built web app locally (run after dev:build:web)
  • npm run dev:deploy:web - Build and deploy web app to EAS Hosting

Environment & Configuration:

  • npm run dev:secret:push - Upload environment variables from .env.dev to EAS secrets
  • npm run dev:secret:list - List all environment variables stored in EAS
  • npm run dev:config:public - Display current Expo configuration for debugging

Code Quality & Testing:

  • npm run lint - Run ESLint to check code quality and style
  • npm run lint:staged - Run linting only on staged Git files (used in pre-commit)
  • npm run format - Format code using Prettier
  • npm run test - Run Jest unit tests
  • npm run test:watch - Run Jest tests in watch mode for development

Git Hooks:

  • npm run prepare - Set up Husky Git hooks for pre-commit quality checks

When in Doubt

  • Check existing components in components/elements for similar functionality
  • Use built-in utilities from utils/, @/theme, and @/hooks
  • Follow the established patterns in the codebase
  • Prefer extending existing components over creating new ones
  • Always use the theme system for consistent UI
⚡