expo-project-structure

name	expo-project-structure
description	Opinionated Expo + React Native + TypeScript project structure and screen-splitting guidance. Use this whenever the user asks how to organize a mobile codebase, where files should live, how to split large screens or components, how to structure components, hooks, services, store, constants, types, or navigation, or when an Expo app feels messy and needs a consistent architecture.
version	1.0.0
type	skill
tags	["expo","react-native","typescript","architecture","folder-structure","mobile"]
category	Mobile
author	agent-skills

Expo Project Structure

Use this skill for Expo + React Native + TypeScript codebases when the real problem is structure, ownership, and boundaries.

This skill defines:

• where code should live in an Expo app
• when to keep code local vs promote it to shared
• how to split large screens and components
• how to name files consistently
• how Expo Router file-based routing affects architecture
• how native modules and config plugins fit into the structure

The default architecture is:

• layer-first
• with a shared foundation
• and domain folders inside each layer

If the repo already has clear, good conventions, preserve them unless they are directly causing problems.

When to Use

Use this skill when the user asks any variation of:

• "How should I organize this Expo/React Native app?"
• "This screen is too large."
• "Where should this hook/service/store/types file live?"
• "How should we structure navigation?"
• "How do I make this mobile architecture scalable?"
• "Can you refactor this messy mobile folder structure?"

Use it even if the user does not explicitly ask for "folder structure," but the actual problem is architectural sprawl.

Guide Categories

Priority	Category	Prefix
1	Architecture Principles	architecture-
2	App Directory & Routing	app-directory-
3	Components Organization	components-
4	Hooks Organization	hooks-
5	Services Layer	services-
6	State Management	store-
7	Navigation Patterns	navigation-
8	Naming Conventions	naming-
9	Splitting Guidelines	splitting-
10	Native Modules & Config	native-modules-

Recommended Structure

app/                    # Expo Router file-based routes
  (tabs)/               # Tab group layout
    _layout.tsx
    index.tsx
    profile.tsx
  (auth)/               # Auth flow group
    _layout.tsx
    login.tsx
    register.tsx
  (modals)/             # Modal presentation group
    _layout.tsx
    confirm.tsx
  _layout.tsx           # Root layout
  +not-found.tsx        # 404 screen
components/
  ui/                   # Primitives (Button, Input, Card)
  shared/               # Cross-domain composites
  screens/              # Screen composition sections
  <domain>/             # Domain-owned components
hooks/
  <domain>/
  native/               # Platform-specific hooks
services/
  <domain>/
  app/                  # Shared services (API client, analytics)
store/
  <domain>/
  app/                  # App-wide state
constants/
  <domain>/
types/
  <domain>/
lib/
  <concern>/
assets/
  images/
  fonts/
plugins/                # Expo config plugins

Quick Reference

• architecture-layer-first — Organize by responsibility first, domain second, adapted for mobile constraints.
• architecture-feature-boundaries — When to use feature folders vs layer-first in React Native apps.
• app-directory-expo-router — Expo Router file-based routing: app/ directory conventions, groups, dynamic routes.
• app-directory-layouts — Layout patterns with _layout.tsx for Stack, Tabs, and Drawer navigators.
• components-ui-primitives — Native UI primitives: Button wrapping Pressable, themed Text, Card with shadows.
• components-shared — Cross-domain composites: EmptyState, LoadingOverlay, ErrorFallback.
• components-domain — Domain-owned components under components/<domain>/.
• components-screens — Screen section extraction to keep route files lean.
• hooks-domain — Domain hooks: hooks/auth/use-auth.hook.ts, hooks/profile/use-profile.hook.ts.
• hooks-native — Native hooks: hooks/native/use-permissions.hook.ts, hooks/native/use-app-state.hook.ts.
• services-api — API services with typed clients and response transformations.
• services-storage — Storage services abstracting MMKV, AsyncStorage, and SecureStore.
• store-global-vs-local — When to use Zustand/Jotai vs Context vs local state in React Native.
• store-offline-sync — Offline sync store patterns with persisted Zustand and mutation queues.
• navigation-file-based — File-based routing conventions with Expo Router groups and deep links.
• navigation-type-safe — Type-safe navigation with typed route params and link helpers.
• naming-conventions — kebab-case files with responsibility suffixes for mobile projects.
• naming-suffixes — Complete suffix reference: .screen.tsx, .hook.ts, .service.ts, .store.ts, .types.ts.
• splitting-screens — When and how to break apart large screen files.
• splitting-components — When and how to decompose components in React Native.
• native-modules-config — Where Expo config plugins live and app.config.ts conventions.
• native-modules-plugins — How to organize wrappers around native modules and Expo packages.

Full Compiled Document

For the complete guide with all content expanded: AGENTS.md