Wanna See Magic Star & Clone Repo Demo.mp4
- Node 22.18+ (pinned in
engines— thescript/*.tstools run directly on Node's built-in type stripping), pnpm 10+ (corepack enable) - Android: Android Studio with an SDK + emulator (AVD), and JDK 17. iOS: Xcode (macOS only).
- Watchman — required for the dev server on large projects. Without it Metro falls back to Node's
fs.watchand crashes withEMFILE: too many open files, watch(especially on Windows). Install:choco install watchman(Windows) /brew install watchman(macOS).
git clone https://github.com/MOHAMED-LAAGUILI/react-native-expo-starter-kit.git my-react-native-app
cd my-react-native-app
pnpm run setupImportant
This project cannot run in Expo Go. It uses native modules (e.g. react-native-mmkv) that Expo Go doesn't include, so it runs in a development build — your own app binary with expo-dev-client.
1. Build and install the dev client — only the first time, and again whenever native dependencies or config plugins change (e.g. after an Expo SDK upgrade):
# List your emulators (AVD names)
emulator -list-avds
# Prebuild, compile, install and launch — pass the AVD *name*, not the adb serial (emulator-5554)
npx cross-env EXPO_PUBLIC_APP_ENV=development npx expo run:android --device <avd-name>The first build compiles every native module and can take a long time (tens of minutes on Windows); later ones are incremental.
2. Day to day — the dev client is already installed, so just start Metro:
pnpm run android:devWeb runs without a native build: pnpm run web. For iOS use npx expo run:ios, then pnpm run ios:dev.
Note
The dev client connects to Metro on port 8081. If another project's Metro already holds that port, the app loads that project's bundle and shows a blank screen. Stop the other server, or run this one on a free port — npx expo start --dev-client --port 8082 — and open it from the dev client.
| Script | Purpose |
|---|---|
pnpm run setup |
Bootstrap: install:safe + skills from skills-lock.json + env:create |
pnpm run install:safe |
pnpm install behind the guard check — use this instead of a bare pnpm install |
pnpm run guard |
Check nothing is using node_modules (pnpm, Metro, Gradle) and clear idle locks |
pnpm run skills:install |
Install pinned skills from skills-lock.json into .claude/skills/ |
pnpm run skills:check |
Preview the skill install without writing (dry run) |
pnpm run env:create |
Create missing .env.{development,preview,production} from .env.example |
pnpm run env:check |
Preview the env file creation without writing (dry run) |
pnpm skills |
Re-detect skills from deps and re-pin skills-lock.json (installs globally) |
pnpm dev |
Start Expo dev server (fresh cache) |
pnpm run ios |
Dev server targeting iOS |
pnpm run android |
Dev server targeting Android |
pnpm run web |
Dev server targeting Web |
pnpm run clean:app |
Clean pnpm cache, node_modules, native builds, and lockfile |
pnpm run mac:ios |
Install pods for iOS |
pnpm run deps:fix |
Fix dependency versions via Expo (runs guard first) |
pnpm run lint:fix |
Run ESLint with auto-fix on all source files |
pnpm run type:check |
Type-check the app, then script/ under Node types (two tsc passes) |
pnpm run doctor |
Run Expo doctor diagnostics & React Doctor |
pnpm run checks |
Run all checks (deps:fix → lint:fix → type:check → doctor) |
pnpm run expo:config |
Print public Expo config |
pnpm run generate:apk |
Build Android APK and install via ADB |
pnpm run prebuild |
Prebuild native project (all platforms) |
pnpm run prebuild:dev |
Prebuild native project (development env) |
pnpm run prebuild:prev |
Prebuild native project (preview env) |
pnpm run prebuild:prod |
Prebuild native project (production env) |
pnpm run prebuild:generate |
Prebuild native project & generate APK |
pnpm run android:dev |
Android dev server (development env) |
pnpm run ios:dev |
iOS dev server (development env) |
pnpm run android:prev |
Android dev server (preview env) |
pnpm run ios:prev |
iOS dev server (preview env) |
pnpm run android:prod |
Android dev server (production env) |
pnpm run ios:prod |
iOS dev server (production env) |
pnpm run eas:in |
EAS login |
pnpm run eas:out |
EAS logout |
pnpm run eas:id |
EAS reveal connected account |
pnpm run build:dev:ios |
Build development iOS (EAS) |
pnpm run build:dev:android |
Build development Android (EAS) |
pnpm run build:prev:ios |
Build preview iOS (EAS) |
pnpm run build:prev:android |
Build preview Android (EAS) |
pnpm run build:prod:ios |
Build production iOS (EAS) |
pnpm run build:prod:android |
Build production Android (EAS) |
pnpm run flow:build-ios:main |
Trigger EAS workflow to build iOS from github branch named main |
pnpm run flow:build-android:main |
Trigger EAS workflow to build Android from github branch named main |
pnpm run submit:android |
Submit Android build to Play Store |
pnpm run submit:ios |
Submit iOS build to App Store |
pnpm run eas:update:config |
Configure EAS Update for the project |
pnpm run eas:update:prod |
Push OTA update to production channel |
pnpm run export:web |
Export web build locally static files |
pnpm run deploy:web |
Deploy web build to production |
Windows can't delete a file another process has open. If an install overlaps Metro, a Gradle build, Watchman or a second pnpm, it dies half-way and leaves node_modules broken. Avoid it:
- Install with
pnpm run install:safe, not a barepnpm install. It runspnpm run guardfirst, which stops if another pnpm, this project's Metro /expo run, or a Gradle build is running, and clears idle Gradle/Kotlin daemons and the Watchman watch for you.deps:fixandsetuprun the guard too. - Run one pnpm command at a time.
Note
The guard is also registered as the pnpm:devPreinstall hook, but pnpm skips all lifecycle hooks — including Husky's prepare — when ignore-scripts=true is set in your ~/.npmrc. Check with pnpm config get ignore-scripts; if it prints true, install:safe is the only guarded install, and the git hooks are not installed.
Symptoms: 'eslint' is not recognized (or another missing binary) in lint:fix, or expo-doctor reporting duplicate native module dependencies with identical versions. A partial install caused it; repairing in place can leave duplicates behind, so reinstall cleanly:
pnpm run guard
rm -rf node_modules
pnpm run install:safeThe dev client connected to a Metro server from another project on port 8081. See the note under Run on an Android emulator.
After upgrading Expo or adding a package with native code, rebuild the dev client (npx expo run:android --device <avd-name>). Restarting Metro only reloads JavaScript.
- Expo Router — File-based routing with Stack, Drawer, and Tab navigators
- Uniwind + Tailwind v4 — Runtime CSS-in-JS with
classNameprops,cn()utility, dark mode via oklch CSS vars - Zustand — Lightweight client state with MMKV persistence and hydration
- TanStack Query — Server state, caching, and auto-refetching (staleTime 5min, gcTime 30min, retry 2)
- TanStack Form + Zod — Type-safe form validation
- Axios — HTTP client with auth token interceptor and refresh queue
- i18next — Internationalization (English, French)
- MMKV — High-performance key-value storage (SSR-safe lazy init)
- Authentication — Login/register flow with token management, demo mode skip
- Drawer + Tabs — Left drawer with PanelLeftOpen header button, bottom tab bar (Search, Report, Home, Settings, Device Info) sorted by centralized config
- Bottom Sheet — Reusable bottom sheet component via
@gorhom/bottom-sheetwith snap points, backdrop, pan-to-close - Modal — Three variants: bottom-sheet (slide-up), centered (scale-in with icon/title/description), centered-action (with action buttons). Uses Reanimated for enter/exit animations.
- Toast — Notification toasts via
react-native-toast-message-tswith success/error/info variants, callable from anywhere viashowToast() - Dark/Light/System theme — CSS variables in oklch, persisted preference, follows system
- Accent Color System — 8 color palettes (blue, purple, green, orange, red, teal, pink) switchable at runtime; all screens react instantly via
Uniwind.updateCSSVariables() - Splash Screen — Custom splash with auto-hide after i18n + auth hydration ready
- System UI — Background color synced with theme mode
- Charts — 17 chart types on the report screen: line, area, stacked area, candlestick, bar, column, stacked bar, scatter, bubble, pie, doughnut, polar area, radar, treemap, heatmap, progress ring and radial bar (
react-native-gifted-charts+react-native-svg) - Calendar — Date picking via
react-native-calendarswith marked dates - Video — Cross-platform video player (
expo-videoon native, HTML<video>on web) - QR Code — QR code generation via
react-native-qrcode-svg - Cross-platform — iOS, Android, Web
- Expo Observe — error tracking and performance monitoring via
expo-observe - Permissions — centralized permission management for Notifications, Camera, and Location via
react-native-permissions,expo-notifications,expo-image-picker,expo-location - Settings Permissions Section — "App Permissions" toggle rows with
Badgestatus indicators +Switchcontrols in the settings screen - Home Permission Cards — demo cards on the home screen to trigger test notification, take a photo, and get GPS coordinates
├── app/ # Expo Router routes
│ ├── _layout.tsx # Root: GestureHandler, SafeAreaProvider, Query, Theme, StatusBar, Splash, SystemUI, Stack
│ ├── index.tsx # Auth redirect (→ login or home)
│ ├── +not-found.tsx # 404
│ ├── +html.tsx # Web HTML shell
│ ├── (auth)/ # Unauthenticated routes
│ │ ├── _layout.tsx
│ │ └── login.tsx
│ └── (app)/ # Authenticated routes
│ ├── _layout.tsx # Drawer (left PanelLeftOpen via custom Pressable) + auth guard
│ ├── report.tsx # Drawer-only report route
│ ├── dev-preferences.tsx # only in dev mode
│ ├── dev-onboarding.tsx # only in dev mode
│ └── (tabs)/ # Bottom tabs
│ ├── _layout.tsx
│ ├── index.tsx # Home (component showcase, floating center button)
│ ├── search.tsx
│ ├── profile.tsx # Drawer-only, hidden from tab bar
│ ├── report.tsx # Report (summary sections + 17-chart gallery)
│ ├── settings.tsx
│ └── device-info.tsx
├── src/
│ ├── api/ # Axios client + TanStack Query hooks
│ ├── components/
│ │ ├── common/ # LoadingScreen, ErrorFallback
│ │ ├── drawer/ # DrawerHeaderLeft, AppDrawerContent, etc.
│ │ ├── home/ # Demo components (cards-demo, extended-demos, overview-cards, etc.)
│ │ ├── report/ # ReportTabs, ReportSection, HoursDistribution, UnifiedProjects, ChartsShowcase + gallery groups
│ │ ├── test/ # Test playground (AdaptiveSlider, AnimatedNumber/NumberFlow, ChangeablePricingSection)
│ │ └── ui/ # Button, Text, Input, BottomSheet, Modal, Calendar, Video, WebView, QRCode, Menu, ...
│ ├── config/ # Constants, env helpers, color-palettes.ts
│ ├── data/ # Mock data (report.ts)
│ ├── hooks/ # Shared hooks (useThemeColors, usePrimaryHex, useDebounce, useRefreshOnFocus)
│ ├── i18n/ # i18next + locales/{en,fr}
│ ├── permissions/ # Permission hooks + utils (usePermissionsStatus, loadExpoLocation, etc.)
│ ├── providers/ # QueryProvider, ThemeProvider, AuthProvider
│ ├── screens/ # Screen components (HomeScreen, ReportScreen, etc.)
│ ├── storage/ # MMKV wrapper (SSR-safe, lazy init)
│ ├── store/ # Zustand stores (authStore, themeStore, onboardingStore)
│ ├── types/ # Type declarations (uniwind.d.ts)
│ ├── utils/ # cn() utility, format helpers, platform helpers
│ ├── widgets/ # android/ios widget
│ └── validation/ # Zod schemas (login, register, forgotPassword)
├── app.config.ts # Expo config (EAS, plugins, fonts, localization)
├── metro.config.js # Expo + Uniwind Metro plugin
├── babel.config.js # module-resolver, reanimated, dotenv
├── eas.json # EAS Build profiles
├── eslint.config.mjs # eslint config
├── tsconfig.json
├── package.json
├── global.css # Tailwind v4 + Uniwind entry, oklch CSS vars (light/dark)
└── .eas/
└── workflows/
└── create-build-all.yml # Eas Actions: auto-build apk
└── .github/
└── workflows/
└── release.yml # GitHub Actions: auto-release on push to main
| Category | Library |
|---|---|
| Framework | React 19 + React Native 0.86 |
| Platform | Expo SDK 57 |
| Language | TypeScript 6 (strict) |
| Package Manager | pnpm 10 (node-linker=hoisted) |
| Routing | Expo Router (Stack/Drawer/Tabs) |
| Styling | Tailwind CSS v4 + Uniwind + cn() |
| Theme | oklch CSS variables (light/dark + 7 accent color palettes) |
| Client State | Zustand 5 (MMKV persistence) |
| Server State | TanStack Query 5 + Devtools (web only) |
| Forms | TanStack Form 1 + Zod 3 |
| Storage | react-native-mmkv 4 (lazy, SSR-safe) |
| i18n | i18next 26 + react-i18next (EN/FR) |
| UI Primitives | @rn-primitives 1.5 (Portal, Slot, Dialog, etc.) |
| Bottom Sheet | @gorhom/bottom-sheet 5 |
| Permissions | react-native-permissions (Notifications, Camera, Location) |
| Icons | lucide-react-native |
| HTTP | Axios (auth interceptor, refresh queue) |
| Animation | react-native-reanimated + gesture-handler |
| Font | @expo-google-fonts/inter (4 weights, via expo-font plugin) |
| Linting | Eslint |
| Git hooks | Husky |
| Dates | date-fns |
| Charts | react-native-gifted-charts + react-native-svg (17 chart types) |
| Calendar | react-native-calendars |
| Video | expo-video (native) / HTML <video> (web) |
| QR Code | react-native-qrcode-svg |
| Animation Extras | moti |
This project uses Context7 to provide AI coding agents with up-to-date documentation for all libraries and frameworks. Context7 fetches current API docs at query time instead of relying on stale training data — ensuring accurate syntax, version migrations, and configuration for React Native, Expo, Tailwind, Zustand, TanStack, and every other dependency.
- Expo Assets Generator — Generate splash, adaptive icon, favicon, and icon for Expo projects
# 1. Development
pnpm dev
# 2. Run checks before committing
pnpm run checks# Push changes
git push
# Login to EAS (one-time)
pnpm run eas:in
# Logout (optional, e.g. switch accounts)
pnpm run eas:outBuild directly from your local code. No need to push to GitHub.
pnpm run build:prev:android
pnpm run build:prev:iosBuild using the latest code on the main branch via the EAS workflow.
Requires pushing your changes first.
pnpm run flow:build-android:main
pnpm run flow:build-ios:mainConnect your GitHub repository in Expo EAS.
Once connected, every push to main automatically runs the workflows in:
.eas/workflows/
No manual CLI commands required.
After connecting your GitHub repository, you can manage builds, updates, and deployments entirely from the Expo website.
Publish JavaScript/asset updates without submitting a new app version.
pnpm run eas:update:prodOnly needed after configuring your App Store Connect / Google Play accounts.
pnpm run submit:ios
pnpm run submit:androidUse Expo Application Services (EAS) for builds, updates, and submissions.
| Profile | Distribution | Channel | Use Case |
|---|---|---|---|
development |
Internal (APK) | development | Dev client builds for local testing (Expo Go) development build for native |
preview |
Internal (APK) | preview | Internal QA builds |
production |
Store (AAB) | production | App Store / Play Store release |
autoIncrement: trueonpreviewandproduction— EAS auto-bumps build numbersappVersionSource: "remote"— version numbers managed by EAS- Environment variables set per-profile in
eas.json
A GitHub Actions workflow (.github/workflows/release.yml) automatically manages releases:
- Triggers on every push to
main - Reads version from
package.json→ creates/updates tagv{version} - New version → creates a GitHub release with auto-generated notes
- Existing version → updates the release notes with commits since the previous release
- Uses
ghCLI withGITHUB_TOKEN— no extra secrets needed
To release, just bump the version in package.json and push to main.
| File | Purpose |
|---|---|
.env.development |
Local dev values |
.env.preview |
Preview/QA builds |
.env.production |
Production builds |
.env.example |
Template the other three are generated from |
src/config/env.ts |
Shared constants (EXPO_PUBLIC_SLUG, EXPO_PUBLIC_PACKAGE, EAS_PROJECT_ID) |
- Android package:
com.rntemplate.app(underscores, not hyphens — Android requirement) - EAS profiles inject
EXPO_PUBLIC_APP_ENVviaeas.jsonenvblock pnpm run env:creategenerates the three files from.env.example, setting onlyEXPO_PUBLIC_APP_ENVper environment; existing files are skipped unless you pass--force
- Consola - for better developer command experience
- Maestro + Jest — E2E testing framework for mobile
- App Store Connect — EAS Submit pipeline for App Store and Play Store release
- Sentry — Crash reporting and error tracking
- Vexo — AI-powered in-app chatbot and customer support
- Backend Service - Supabase / Convex
- Expo Other Expo Features
- Immersive Focus Hide Navigation bar
- Expo Widget Android Widgets
- Accessible RN Primitive Components - RN-Primitives