A mobile app project template built with React Native and Expo, using the latest React Native / TypeScript practices. It is the React Native member of nventive's application-template family, built on a layered architecture with MVVM state management.
- It follows the MVVM principle, with an idiomatic React shape (RxJS observables + hooks instead of ViewModel classes).
- Code is organized by application layer — Access, Business, and Presentation — and by feature within each layer.
- It comes with a lightweight dependency-injection composition root (no container).
- There are built-in logs and diagnostic tools.
- It ships the cross-cutting concerns a production app needs out of the box: environments, HTTP, storage, serialization, navigation, localization, theming, forced update, kill switch, remote config, analytics, crash reporting, and more (see Documentation).
- There is scaffolding code showing a full sample feature. When you run it as-is, you get a Dad Jokes application.
| All platforms | Android | iOS (macOS only) |
|---|---|---|
| Node 22 LTS | Android Studio (SDK 35+, an AVD/emulator) | Xcode 26+ (Swift 6.2) |
| Yarn 1 (classic) | JDK 17 | CocoaPods |
This template uses Expo with Continuous Native Generation: the android/
and ios/ projects are generated by expo prebuild and are gitignored —
never hand-edit or commit them. There is no EAS Build and no Expo Go
dependency; the app runs as a dev-client debug build produced by Gradle / Xcode.
See doc/GettingStarted.md for the full setup and day-to-day workflow.
yarn install # install dependencies
yarn android # build & run on Android (expo run:android)
yarn ios # build & run on iOS (macOS only, expo run:ios)expo run:android / expo run:ios performs the prebuild automatically, builds
the debug app, installs it on the emulator/simulator, and starts Metro. Once a
dev-client build is installed, yarn start alone is enough for JavaScript
changes.
After checking out the template, rename it into your own application with the built-in generator:
yarn install
yarn generate --name "Acme App" --bundle-id com.acme.acmeappThis substitutes the app name, slug, and bundle identifier / Android package
throughout the project, rewrites this README into a starter README, and removes
the template-only files (governance files and the generator itself). Add
--dry-run to preview. See doc/ProjectGenerator.md
for all options.
- Rename the project with the generator (above).
- Open app.config.ts to review the app identity and per-environment configuration.
- Copy the Dad Jokes feature (
src/{access,business,presentation}/jokes/) as the pattern for your first feature — see doc/DadJokes.md.
The app is split into layers, with dependencies pointing strictly downward and code organized by feature within each layer:
| Layer | Folder | Contains | May depend on |
|---|---|---|---|
| Access (DAL) | src/access/ |
HTTP clients, storage, native wrappers, DTOs (zod-parsed) | nothing above it |
| Business | src/business/ |
Domain services & immutable entities (plain TS, RxJS) | Access interfaces |
| Presentation | src/presentation/ |
Screens, hooks, navigation, theme | Business interfaces (useServices()) |
| Framework | src/framework/ |
Composition root, providers, i18n, logging setup | all (it wires them) |
State reaches the UI through two explicit paths: fetched request/response
data via React Query (keys from a central factory), and live
domain state via an RxJS BehaviorSubject behind a service interface, consumed
through the single useObservable bridge. The full picture — including how state
management follows MVVM — is in doc/Architecture.md.
Every topic has a recipe under the doc/ folder. Start with doc/README.md for the complete index.
| Topic | Implementation |
|---|---|
| Getting Started | Expo (Continuous Native Generation), Gradle / Xcode |
| Architecture | Layered (Access / Business / Presentation), MVVM |
| Dependency Injection | Composition root + ServicesProvider / useServices() |
| Navigation | React Navigation (typed routes) |
| Environments | EnvironmentService (MMKV + expo-constants, restart-to-apply) |
| Design System | Theme tokens + base components, light/dark |
| HTTP | axios + interceptors |
| Async Data Loading | TanStack Query + queryKeys |
| Local Storage | MMKV + expo-secure-store |
| Serialization | zod DTO schemas |
| Logging | Logger interface + console/file transports |
| Diagnostics | In-app overlay (env picker, mocking, log viewer) |
| Error Handling | Typed error taxonomy + QueryStateView + error boundary |
| Localization | i18next + expo-localization, en/fr |
| Forced Update | Observable gate (AppGate) vs. remote minimum version |
| Kill Switch | Observable gate (AppGate), auto-recovering |
| Remote Config | RemoteConfigProvider seam (mock / static) |
| Firebase Remote Config | Opt-in Firebase provider behind the seam |
| Analytics | AnalyticsSink seam (logging no-op by default) |
| Crash Reporting | CrashReporter seam (opt-in Bugsee, internal builds) |
| Validation / Forms | react-hook-form + zod resolver |
| App Reviews | expo-store-review behind a policy service |
| Testing | Jest + RNTL + MSW + Maestro |
| Security Scan | Dependency (SCA) audit, nightly and non-blocking |
| CI Pipeline | Azure Pipelines (prebuild + Gradle/Xcode) |
| Project Generator | In-place rename CLI (yarn generate) |
| Dad Jokes sample | Full vertical slice through every layer |
src/
access/ Access layer — API clients, storage, native wrappers, DTOs
business/ Business layer — domain services & entities
presentation/ Presentation layer — screens, hooks, navigation, theme
framework/ Composition root, providers, i18n, logging setup
app/ App entry point
doc/ Per-concern documentation (this index)
test/ Cross-cutting & integration test suites
e2e/ Maestro end-to-end smoke flows
build/ Azure Pipelines definition & templates
cli/ Project-rename generator
Run the verify loop before proposing any change; it is the same sequence CI runs on every PR:
yarn typecheck # TypeScript, no emit
yarn lint # ESLint + Prettier
yarn test # Jest unit & component testsAdditional scripts: yarn test:coverage (coverage report), yarn e2e
(Maestro smoke flows, device/CI only), and yarn audit:scan (dependency audit).
See doc/Testing.md.
Please consult BREAKING_CHANGES.md for more information about version history and compatibility.
This project is licensed under the Apache 2.0 license — see the LICENSE file for details.
Please read CONTRIBUTING.md for details on the process for contributing to this project.
Be mindful of our Code of Conduct.