Why?

Every Expo starter out there gives you a flat screens/ folder and calls it a day. That works for a todo app. It doesn't work for production.

create-expo-clean separates two decisions that are always conflated:

• Architecture — how you organize and separate responsibilities
• Stack — which tools you use for each layer

A developer building a prototype picks MVC + AsyncStorage. A developer building a fintech app picks DDD + WatermelonDB. Same CLI, radically different — and appropriate — output.

Quick start

npx create-expo-clean my-app

That's it. The interactive wizard guides you through every decision.

You can also pass the project name as an argument to skip the first step:

npx create-expo-clean        # asks for name interactively
npx create-expo-clean my-app # skips to architecture selection

What you get to choose

1. Architecture

| Pattern | Structure | Best for | |---|---|---| | Clean Architecture | domain/ data/ presentation/ | Complex apps with heavy business logic | | MVVM | model/ view-model/ view/ | Standard mobile pattern, very readable | | MVC | model/ controller/ view/ | Small to medium apps, quick to understand | | DDD | bounded-contexts/ aggregates/ value-objects/ | Domain-heavy apps (fintech, health, logistics) | | Feature Sliced Design | app/ pages/ widgets/ features/ entities/ shared/ | Strict layer boundaries, scales to large teams |

2. Navigation

| Option | Notes | |---|---| | Expo Router v4 | File-based routing (recommended) | | React Navigation v7 | Stack/tab/drawer, maximum flexibility |

3. State management

| Option | Notes | |---|---| | Zustand | Lightweight, minimal boilerplate (recommended) | | Redux Toolkit | Enterprise, highly structured | | Jotai | Atomic, local/global mix | | MobX | Reactive, observable — natural fit with MVVM |

4. Server state / Data fetching

| Option | Notes | |---|---| | TanStack Query v5 | Smart cache, optimistic UI (recommended) | | SWR | Lightweight, stale-while-revalidate | | Apollo Client | GraphQL only | | None | Manual fetch/axios |

5. Styling

| Option | Notes | |---|---| | NativeWind v4 | Tailwind CSS for RN (recommended) | | Unistyles v3 | Advanced theming, responsive | | Native StyleSheet | Zero dependency | | Tamagui | Full design system |

6. Local storage

| Option | Notes | |---|---| | MMKV | Ultra-fast, synchronous (recommended) | | expo-sqlite + Drizzle | Relational SQL, offline-first | | WatermelonDB | Server sync, large datasets | | AsyncStorage | Simple, community standard |

7. Forms & Validation

| Option | Notes | |---|---| | React Hook Form + Zod | De facto standard, typesafe (recommended) | | React Hook Form + Yup | Declarative, verbose | | Formik | Legacy standard | | None | Manual handling |

8. Extras

| Option | What it adds | |---|---| | Internationalization | expo-localization + i18next with fr/en locales | | Animations | react-native-reanimated + Gesture Handler | | Push notifications | expo-notifications | | Error tracking | Sentry integration | | Testing | Jest + React Native Testing Library | | EAS Build config | eas.json with dev/staging/production profiles |

Generated project structure

Every generated project includes:

• TypeScript strict mode with path aliases tailored to your architecture
• Themed design tokens (colors, spacing, typography, border radius)
• Reusable Button and Input components
• Axios client with token interceptor and 401 handling
• A complete auth feature implemented in your chosen architecture
• Dynamic README.md with architecture rules and "Add a feature" guide
• .env.example with documented variables

Example: Clean Architecture + Zustand + TanStack Query

my-app/
  src/
    features/
      auth/
        domain/
          entities/User.ts
          use-cases/LoginUseCase.ts
          ports/IAuthRepository.ts
        data/
          repositories/AuthRepository.ts
          sources/authApi.ts
        presentation/
          hooks/useAuth.ts
          components/LoginForm.tsx
        index.ts
    shared/
      components/Button.tsx, Input.tsx
      theme/index.ts
    infrastructure/
      api/client.ts
      storage/storageAdapter.ts
  app/
    _layout.tsx
    index.tsx

Example: Feature Sliced Design

my-app/
  src/
    app/providers/index.tsx
    pages/login/ui/LoginPage.tsx
    widgets/auth-form/ui/AuthForm.tsx
    features/login-by-email/model/loginByEmail.ts
    entities/user/model/userStore.ts
    shared/api/client.ts, ui/Button.tsx

Compatibility notes

The CLI warns you when a combination is suboptimal:

| Architecture | Recommended state | Warning | |---|---|---| | MVVM | MobX, Zustand | RTK adds overhead to the ViewModel pattern | | DDD | RTK, Zustand | MobX can conflict with DDD immutability |

What makes this different

| Feature | create-expo-clean | Other starters | |---|---|---| | Architecture choice | 5 patterns | None or 1 | | Real code in templates | Yes — entities, use-cases, hooks | // TODO: implement | | TypeScript strict | Always | Sometimes | | Path aliases per architecture | Automatic | Manual | | Compatibility warnings | Yes | No | | Dynamic README | Tailored to your stack | Generic |

Development

git clone https://github.com/FenosoaA4/Expo-RN-Boilerplate-CLI.git
cd create-expo-clean
npm install
npm run dev     # watch mode
npm run build   # production build
npm start       # run the CLI locally

Project structure

src/
  index.ts          # Entry point, parses args
  wizard.ts         # Interactive prompts (@clack/prompts)
  generator.ts      # Orchestrates scaffold -> install -> git
  scaffold.ts       # Copies and renders EJS templates
  installer.ts      # Detects package manager, installs deps
  git.ts            # git init + initial commit
  compatibility.ts  # Architecture x state matrix
  readme.ts         # Dynamic README generator
  types.ts          # UserChoices, ProjectConfig

templates/
  base/             # Always copied (theme, components, api client)
  architecture/     # One folder per pattern (clean, mvvm, mvc, ddd, fsd)
  nav/              # expo-router, react-navigation
  state/            # zustand, redux-toolkit, jotai, mobx
  query/            # tanstack-query, swr, apollo
  style/            # nativewind, unistyles, stylesheet, tamagui
  storage/          # mmkv, expo-sqlite, watermelondb, async-storage
  forms/            # rhf-zod, rhf-yup, formik
  extras/           # i18n, animations, notifications, sentry, testing, eas

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

License

MIT