react-native-ts.mdc

---
description: React Native rules — theme tokens, keyboard handling, React Query for server state.
globs: ""
alwaysApply: true
---

## File Structure and Naming

- All screen components live in `src/screens/` with PascalCase names: `LoginScreen.tsx`, `ProfileScreen.tsx`
- All reusable components live in `src/components/` with PascalCase names, one component per file
- All hooks live in `src/hooks/` with camelCase names prefixed with `use`: `useAuth.ts`, `useTheme.ts`
- All utilities live in `src/utils/` with camelCase names: `formatDate.ts`, `validateEmail.ts`
- All types live in `src/types/` with PascalCase names: `User.ts`, `ApiResponse.ts`
- All constants live in `src/constants/` with UPPER_SNAKE_CASE names: `API_ENDPOINTS.ts`, `THEME_COLORS.ts`
- Navigation configuration lives in `src/navigation/` with descriptive names: `RootNavigator.tsx`, `AuthNavigator.tsx`
- API client code lives in `src/api/` with resource-based names: `userApi.ts`, `postsApi.ts`
- Theme configuration lives in `src/theme/` with files: `colors.ts`, `spacing.ts`, `typography.ts`
- All test files live adjacent to source with `.test.ts` or `.test.tsx` suffix, never in separate `__tests__` directory

## Exports and Module Organization

- Every file exports exactly one default export (the main component, hook, or utility)
- Named exports are forbidden except for type definitions
- Type definitions use `export type` not `export interface` in `.ts` files
- Barrel exports forbidden: never create `index.ts` files that re-export from sibling files
- Import paths must be relative (`../hooks/useAuth`) never absolute aliases

## TypeScript Strictness

- Never use `any` type anywhere except in `.test.ts` files
- Never use `as` type assertions outside test files; use type guards with `if (x instanceof Type)` or Zod `.parse()`
- All function parameters must have explicit types; no implicit `any`
- All function return types must be explicit; use `void` not implicit undefined
- All object literals must use `satisfies` with a type: `const config = { ... } satisfies Config`
- Never use `!` non-null assertion operator; use optional chaining `?.` and nullish coalescing `??` instead

## React and Component Patterns

- All components must be functional components with TypeScript props interface named `{ComponentName}Props`
- Props interface must be exported as named type: `export type LoginScreenProps = { ... }`
- Never use `React.FC` or `React.FunctionComponent`; use function declaration with explicit return type
- All useState calls must specify the type explicitly: `const [count, setCount] = useState<number>(0)`
- Never use useState for server data; use React Query with `useQuery` hook from `@tanstack/react-query`
- All useEffect hooks must have explicit dependency array; never omit it
- useEffect cleanup functions required for subscriptions, timers, and listeners; verify with `return () => { ... }`

## Styling and Theme

- Never use hardcoded colors in components; import from `src/theme/colors.ts`
- All colors referenced as `colors.primary`, `colors.background`, `colors.error` — never hex values in component files
- All spacing values must use `src/theme/spacing.ts` constants: `spacing.xs`, `spacing.sm`, `spacing.md`, `spacing.lg`, `spacing.xl`
- StyleSheet.create must be called at module level, never inside component function
- All StyleSheet.create calls must use theme tokens: `color: colors.text`, `marginBottom: spacing.md`
- Never use inline styles; all styles must be in StyleSheet.create
- Platform-specific styles must use `Platform.select()`: `Platform.select({ ios: {...}, android: {...}, default: {...} })`

## Navigation

- All navigation logic must live in `src/navigation/` files, never in screen components
- Screen components receive navigation via props typed as `NativeStackScreenProps<RootStackParamList, 'ScreenName'>`
- Navigation params must be defined in `src/types/Navigation.ts` with `RootStackParamList` type
- Never call navigation functions directly in component render; use `useEffect` with navigation listener
- Deep linking configuration must live in `src/navigation/linking.ts` with explicit route mapping

## Error Handling

- All async functions must have try/catch blocks
- Caught errors must be typed: `catch (err) { if (err instanceof AppError) { ... } else if (err instanceof NetworkError) { ... } }`
- Never catch with `catch (e: any)` or bare `catch`
- All API calls must catch and transform errors to `AppError` type defined in `src/types/Error.ts`
- AppError must have properties: `code: string`, `message: string`, `statusCode?: number`, `originalError?: Error`
- Network errors must be caught separately and transformed to AppError with `code: 'NETWORK_ERROR'`
- All error messages shown to users must come from `src/constants/ERROR_MESSAGES.ts`, never hardcoded strings

## API and Data Fetching

- All API calls must use React Query `useQuery` or `useMutation` from `@tanstack/react-query`
- API client functions live in `src/api/` and return typed responses matching `src/types/`
- All API responses must be validated with Zod schema before use: `const parsed = UserSchema.parse(response)`
- Zod schemas live in `src/types/` with filename matching the type: `User.ts` contains `UserSchema`
- Never make fetch calls directly in components; always use custom hooks wrapping React Query
- All API endpoints must be constants in `src/constants/API_ENDPOINTS.ts` with UPPER_SNAKE_CASE names
- Request/response interceptors must be configured in `src/api/client.ts` for auth headers and error handling

## Input Validation and Security

- All user inputs must be validated at component boundary before API submission
- Validation must use Zod schema with `.parse()` or `.safeParse()`
- Never trust data from navigation params; validate with Zod before use
- Never hardcode API keys, tokens, or secrets; use environment variables via `process.env.EXPO_PUBLIC_*`
- All environment variables must be prefixed with `EXPO_PUBLIC_` to be accessible in Expo
- Sensitive data (tokens, passwords) must never be logged; use `console.debug` only in development

## Keyboard and Input Handling

- Every screen with TextInput must wrap content in `<KeyboardAvoidingView behavior={Platform.OS === 'ios' ? 'padding' : 'height'} />`
- TextInput components must have `returnKeyType` set explicitly: `returnKeyType="done"` or `returnKeyType="next"`
- TextInput must have `onSubmitEditing` handler that moves focus or submits form
- Form submission must be prevented on empty inputs with explicit validation before API call
- All numeric inputs must have `keyboardType="number-pad"` or `keyboardType="decimal-pad"`
- Email inputs must have `keyboardType="email-address"` and `autoCapitalize="none"`

## Platform-Specific Code

- All platform-specific logic must use `Platform.OS === 'ios'` or `Platform.OS === 'android'`, never `Platform.select()` for logic
- Use `Platform.select()` only for styling or component selection
- iOS-specific features must be wrapped in `Platform.OS === 'ios'` check before use
- Android-specific features must be wrapped in `Platform.OS === 'android'` check before use
- StatusBar configuration must be platform-aware in `src/navigation/RootNavigator.tsx`

## Testing

- Every custom hook must have a `.test.ts` file using `@testing-library/react-native`
- Every utility function must have a `.test.ts` file with minimum 3 test cases
- Screen components must have `.test.tsx` file testing navigation and error states
- Test files must use `describe()` blocks organized by function name
- Test names must start with `should`: `should render login form`, `should submit with valid email`
- Mock API calls with `jest.mock('src/api/userApi')` at top of test file
- Never test implementation details; test user behavior and output only

## Logging and Debugging

- Never use `console.log` in production code; use `console.debug` for development only
- All errors must be logged with context: `console.error('Failed to fetch user', { userId, error })`
- Sensitive data must never appear in logs; sanitize before logging
- Use `__DEV__` flag for development-only logging: `if (__DEV__) console.debug(...)`

---

> Source: [Codelibrium](https://codelibrium.com) — the marketplace for AI behaviour files.
> Browse multiple rulesets at [codelibrium.com](https://codelibrium.com) or install via CLI:
> `npx codelibrium-cli install <ruleset-name>`