Skip to content

Sync engage-native docs with Expo 55 / RN 0.83 upgrade #298

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Sync engage-native docs with Expo 55 / RN 0.83 upgrade #298

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 27 additions & 5 deletions repositories/d-sports-engage-native.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,16 @@ icon: "smartphone"

| Category | Technology |
| ---------- | ------------------------- |
| Framework | Expo 54, React Native 0.81, React 19 |
| Framework | Expo 55, React Native 0.83, React 19 |
| Language | TypeScript 5.9 |
| Auth | Clerk (Expo) |
| Payments | RevenueCat (react-native-purchases) |
| Web3 | Thirdweb |
| State | Zustand |
| Storage | MMKV |
| State | Zustand 5 |
| Storage | MMKV 4 |
| UI | Lucide React Native |
| Navigation | Expo Router |
| Animations | React Native Reanimated 4 |
| Package | Bun |

## Features
Expand All @@ -35,6 +37,10 @@ icon: "smartphone"

## What changed since last docs sync

- Upgraded from Expo 54 / React Native 0.81 to **Expo 55 / React Native 0.83** with TypeScript 5.9.
- iOS tab bar now uses `NativeTabs` (`expo-router/unstable-native-tabs`) with Liquid Glass dark material; Android and web use a custom `PillTabBar` overlay with `expo-blur`.
- Added CI workflow for **EAS OTA updates** — pushes to `develop` or `main` trigger automatic over-the-air updates via `eas update`.
- Added **widgets** support (iOS Live Activities and Android home-screen widgets via `expo-widgets`).
- Team-aware experiences were expanded to align with backend team/favorites behavior.
- Quest and rewards surfaces were updated to support per-team progression and pass-aware eligibility.
- Pack opening and odds disclosure UX were upgraded with safer interactions and clearer status/error handling.
Expand Down Expand Up @@ -62,12 +68,28 @@ icon: "smartphone"
- Native odds disclosure behavior is documented with policy-aligned copy and evidence requirements.
- Disclosure values must come from backend payloads and remain visible/accessible near open actions.

## Environment variables

The native app uses `EXPO_PUBLIC_*` keys, which are embedded at build time:

| Variable | Purpose |
| -------- | ------- |
| `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY` | Clerk authentication |
| `EXPO_PUBLIC_API_URL` | Backend API base URL (`https://api.d-sports.org`) |
| `EXPO_PUBLIC_TW_CLIENT_ID` | Thirdweb Web3 client ID |
| `EXPO_PUBLIC_REVENUECAT_API_KEY` | RevenueCat in-app purchases |
| `EXPO_PUBLIC_REVENUECAT_APPSTORE_ID` | RevenueCat App Store ID |
| `EXPO_PUBLIC_REVENUECAT_ENTITLEMENT` | RevenueCat entitlement identifier |
| `EXPO_PUBLIC_SUPABASE_URL` | Supabase project URL |
| `EXPO_PUBLIC_SUPABASE_KEY` | Supabase publishable (anon) key |

## Getting started

1. Clone the repository and run `bun install`.
2. Configure environment (Clerk, RevenueCat, Thirdweb, API base URL) per repo README.
3. Run `bunx expo start`.
2. Copy `.env` and configure the `EXPO_PUBLIC_*` variables listed above.
3. Run `bunx expo start` — press `a` for Android, `i` for iOS, or scan the QR code with Expo Go.
4. For development builds: `bun run build:dev` (EAS) or run with Expo dev client.
5. TypeScript check: `bun tsc --noEmit`.

The app targets both native and web (responsive) and uses the same backend (d-sports-api) as the PWA for API and checkout flows.

Expand Down
38 changes: 27 additions & 11 deletions repositories/d-sports-engage-native/architecture.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,26 +5,42 @@ description: "Architecture overview for d-sports-engage-native application layer

## App architecture

The native app is structured around Expo Router screens, feature-oriented components, shared hooks, and API modules.
The native app follows a **modular screen architecture** built on Expo Router with file-based routing. Screen files contain only imports and JSX — all state, effects, and handlers live in dedicated hooks.

- Routing: `app/*` with grouped routes for tabs/auth/onboarding/settings.
- Feature logic: extracted hooks for wallet, shop, locker room, and settings.
- Shared contexts: user, collectibles, accessibility, and UI visibility/state controls.
```
app/
├── (auth)/ # Login, signup, SSO, password reset
├── (onboarding)/ # New user onboarding flow
├── (tabs)/ # Main tab navigation (wallet, shop, leaderboard, locker room, profile)
├── settings/ # Settings pages with nested modals and tabs
└── _layout.tsx # Root layout with provider hierarchy and auth protection
```

- **Feature logic:** extracted hooks (`hooks/use-wallet-screen.ts`, `hooks/use-shop-screen.ts`, `hooks/use-feed-section.ts`, etc.)
- **Sub-components:** barrel-exported from `components/wallet/`, `components/shop/`, `components/leaderboard/`, `components/locker-room/`
- **Shared contexts:** user, collectibles, accessibility, navbar visibility, and action modal state

## State and context boundaries

- **Zustand** store in `services/store.ts` with MMKV persistence for global state (theme, cart, points).
- **React Context** providers in `context/` for auth (`UserContext`), collectibles (`CollectiblesContext`), and UI controls.
- Local/ephemeral UI state lives near feature hooks and components.
- Cross-screen state is managed with context providers and persisted storage where required.
- User/session-sensitive state is coordinated with backend auth and profile sync endpoints.

## API client and retry behavior

- All network calls route through `lib/api/*` modules.
- Client wrappers handle auth token propagation, error normalization, and retry strategy.
- Quest/reward/team flows should consume backend eligibility as source of truth.
- All network calls route through `lib/api/*` modules with a centralized client (`lib/api/client.ts`).
- Auth token injection, error normalization, and retry strategy are handled by the client wrapper.
- `lib/api/cache.ts` provides `fetchWithCache()` with MMKV cache-first fetching for offline resilience.
- Quest/reward/team flows consume backend eligibility as source of truth.

## Platform-specific behavior

- iOS/Android platform differences are handled in native-specific components and runtime checks.
- Web-target support exists but mobile behavior is primary for interaction and performance design.
- Haptics, modal controls, and animation handling are implemented with platform-safe fallbacks.
- **iOS tab bar:** uses `NativeTabs` from `expo-router/unstable-native-tabs` with system chrome material (dark) and gold accent.
- **Android and web tab bar:** uses a custom `PillTabBar` overlay with `expo-blur`.
- Haptics, modal controls, and animation handling use platform-safe fallbacks via Reanimated 4.
- Web target uses responsive `maxWidth: 480px` container and hover states for desktop.

## CI and OTA updates

The repository includes a GitHub Actions workflow (`eas-update.yml`) that publishes over-the-air updates on push to `develop` or `main` using `eas update`. This allows shipping bug fixes and small changes without a full App Store / Play Store review cycle.