| name | react-native-architecture |
| description | Feature-first project structure and separation of concerns for React Native. Use when structuring a React Native project or applying clean architecture patterns. (triggers: src/**/*.tsx, src/**/*.ts, app.json, feature, module, directory structure, separation of concerns, Expo, React Navigation, StyleSheet.create, react-native, mobile architecture) |
React Native Architecture
Priority: P0 (CRITICAL)
Feature-first organization for scalable mobile apps.
Implementation Guidelines
- Feature-First: Organize by feature/module, not by type.
- Colocation: Keep related files together (screens, components, hooks within feature).
- Separation: UI (screens/components) separate from logic (hooks/services). Example structure:
features/auth/ contains screens, hooks, and services together.
- Atomic Components: Reusable components in
/components. Feature-specific in feature folder.
- Absolute Imports: Configure tsconfig.json paths (
@/components, @/features).
- Single Responsibility: Each file has one clear purpose.
- Expo vs CLI: Structure works for both. Expo uses
app.json, CLI uses index.js.
Anti-Patterns
- No Type-Based Folders: Avoid
/containers, /screens at root. Use features.
- No Logic in Screens: Extract to hooks or services.
- No Circular Deps: Features should not import from each other directly.
- No Deep Nesting: Max 3 levels deep.
Navigation Strategy
- Expo Router: Use for new projects, web-parity, and file-based routing.
- React Navigation: Use for complex deep-linking, legacy apps, or high-customization needs.
Verification Checklist (Mandatory)
References
See references/folder-structure.md for full directory tree, path alias config, and service layer patterns.
