# React Native Architecture

> 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)

- Skill: `comeonoliver/react-native-architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add comeonoliver/react-native-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/comeonoliver/react-native-architecture/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ComeOnOliver (https://skillmd.com/u/comeonoliver)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/comeonoliver/react-native-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)

- [ ] **Feature-First**: Is the file inside a feature directory?
- [ ] **Colocation**: Are hooks/services colocated with screens?
- [ ] **Logic-Free Screens**: Is there any business logic in the screen component?
- [ ] **Navigation Choice**: Does the project use the navigation strategy defined above?

## References

See [references/folder-structure.md](references/folder-structure.md) for full directory tree, path alias config, and service layer patterns.