Skip to main content

Project Structure

React Native apps become expensive when the repository reflects every short-term feature decision. Structure should make ownership clear, minimize circular dependencies, and keep shared product logic discoverable.

A practical app structure​

src/
  app/
    providers/
    store/
  features/
    auth/
    onboarding/
    payments/
  navigation/
  screens/
  components/
    primitives/
    composed/
  hooks/
  services/
    api/
    analytics/
    storage/
  theme/
    tokens/
    typography/
  utils/
  types/
  tests/

Structural guidelines​

Organize by feature where behavior lives together​

Feature folders reduce the tendency to scatter state, hooks, API adapters, and presentation files across unrelated global directories.

Keep primitives separate from product-specific components​

Reusable UI primitives such as buttons, inputs, typography, layout wrappers, and feedback states should be easy to find and stable across features.

Isolate service boundaries​

Analytics, API clients, secure storage, notifications, and third-party SDK wrappers should live behind app-owned interfaces. That keeps vendors from leaking across the codebase.

Native project placement​

When you own ios/ and android/, treat them as platform delivery surfaces, not as a second application layer. Product logic should not drift into native folders unless there is a platform-specific reason.

  • Use feature ownership to guide folder design.
  • Keep a single source of truth for route definitions and deep links.
  • Centralize theme tokens rather than duplicating constants inside screens.
  • Put testing utilities near the app layer instead of copying setup into every feature.
  • Separate server state, local state, and persistent storage concerns.

Avoid these anti-patterns​

  • A giant components/ folder with no distinction between primitives and feature-specific UI.
  • A utils/ folder that becomes a dumping ground for business logic.
  • Screens owning API calls directly with no service layer.
  • Native bridge code mixed into product folders without documentation.

Team conventions to document​

  • File naming style.
  • Import alias rules.
  • Whether features can import each other directly.
  • How to place types, hooks, and tests.
  • What belongs in services/ versus features/.

Scaling rule​

If a folder is growing rapidly, ask whether it represents a stable concept or just accumulated convenience. Stable concepts deserve a module. Convenience piles usually need to be broken apart.

Once the structure is stable, move into styling and layout.