Skip to content

Sync engage-native docs with Expo 55 and v1.18.3 #295

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 and v1.18.3 #295

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
55 changes: 32 additions & 23 deletions repositories/d-sports-engage-native.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,50 +1,58 @@
---
title: "d-sports-engage-native"
description: "Native iOS and Android app for D-Sports Engage. Expo 54, React Native, Clerk, RevenueCat, Thirdweb."
description: "Native iOS and Android app for D-Sports Engage. Expo 55, React Native, Clerk, RevenueCat, Thirdweb."
icon: "smartphone"
---

## Overview

**d-sports-engage-native** (package name: `engage-native`) is the native mobile app for D-Sports. It mirrors the core PWA experience on iOS and Android: wallet, shop, leaderboard, locker room, and profile.
**d-sports-engage-native** (package name: `engage-native`, current version: **1.18.3**) is the native mobile app for D-Sports. It mirrors the core PWA experience on iOS and Android: wallet, shop, leaderboard, locker room, and profile.

- **Run:** `bunx expo start` or `bun run start` — then press `a` for Android or `i` for iOS, or scan the QR code with Expo Go.

## Tech stack

| Category | Technology |
| ---------- | ------------------------- |
| Framework | Expo 54, React Native 0.81, React 19 |
| Auth | Clerk (Expo) |
| Payments | RevenueCat (react-native-purchases) |
| Web3 | Thirdweb |
| State | Zustand |
| Storage | MMKV |
| UI | Lucide React Native |
| Navigation | Expo Router |
| Package | Bun |
| Category | Technology |
| ------------- | ------------------------------------------- |
| Framework | Expo 55, React Native, React 19 |
| Auth | Clerk (Expo) |
| Payments | RevenueCat (react-native-purchases) |
| Web3 | Thirdweb |
| State | Zustand |
| Storage | MMKV |
| UI | Lucide React Native |
| Navigation | Expo Router (`~6.0.22`, typed routes) |
| Notifications | OneSignal |
| Monitoring | Sentry (`@sentry/react-native`) |
| CI/CD | EAS Build + EAS Update (OTA) |
| Package | Bun |

## Features

- **Wallet** — Tokens, holdings, pack opening, crypto checkout (via PWA backend)
- **Shop** — Collectibles, cart, coin bundles, checkout
- **Leaderboard** — Rankings and filters
- **Locker room** — Social feed and engagement
- **Profile** — User profile and settings
- **Wallet** — Tokens, holdings, pack opening, send/receive, crypto checkout (via PWA backend)
- **Shop** — Collectibles, cart, coin bundles, fiat (RevenueCat) and crypto checkout
- **Leaderboard** — Rankings, filters, and team-scoped views
- **Locker room** — Social feed, daily games (pick-em, spin wheel, guess-the-player), and engagement
- **Profile** — User profile, achievements, milestones, and settings
- **Widgets** — iOS home screen widgets (rank/points) and Live Activities; Android widgets via `react-native-android-widget`
- **Theme** — Dark/light mode (default dark)

## What changed since last docs sync

- 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.
- Upgraded from **Expo 54 to Expo 55** with Expo Router 6 and typed routes.
- iOS tab bar now uses native `NativeTabs` (`expo-router/unstable-native-tabs`) with Liquid Glass dark material; Android and web use a custom `PillTabBar` with blur overlay.
- Added **home screen widgets** for iOS (rank/points widget, Live Activity) and Android (rank/points widget).
- Added **CI/CD via GitHub Actions** with an EAS Update workflow for OTA pushes to `develop` and `main` branches.
- Android release builds now include **ProGuard rules** (`-dontwarn java.awt.**`, `-dontwarn com.sun.jna.**`) to suppress non-Android desktop class warnings and keep R8 minification enabled.
- Wallet send/receive flows and import-wallet UX were expanded.
- Daily games (pick-em, spin wheel, guess-the-player) added to locker room.
- Settings and account flows were expanded, including in-app account deletion and richer support/data controls.

## Backend integration surfaces

- Primary API source: `d-sports-api` under `/api/*`.
- Native app consumes team, league, quest, reward, wallet, commerce, and social endpoints.
- Retry/caching logic and auth token injection are centralized in app API client modules.
- Retry/caching logic and auth token injection are centralized in `lib/api/client.ts` and domain-specific API modules.

## Quest and pass UX integration

Expand All @@ -65,9 +73,10 @@ icon: "smartphone"
## Getting started

1. Clone the repository and run `bun install`.
2. Configure environment (Clerk, RevenueCat, Thirdweb, API base URL) per repo README.
2. Create a `.env` file with required keys: `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`, `EXPO_PUBLIC_API_URL`, `EXPO_PUBLIC_TW_CLIENT_ID`, `EXPO_PUBLIC_REVENUECAT_API_KEY`, `EXPO_PUBLIC_SUPABASE_URL`, and `EXPO_PUBLIC_SUPABASE_KEY`.
3. Run `bunx expo start`.
4. For development builds: `bun run build:dev` (EAS) or run with Expo dev client.
5. For production builds: `bun run build:prod` or `bun run build:submit:all` for build-and-submit.

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
91 changes: 61 additions & 30 deletions repositories/d-sports-engage-native/architecture.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,61 @@
---
title: "Native architecture"
description: "Architecture overview for d-sports-engage-native application layers and platform behavior."
---

## App architecture

The native app is structured around Expo Router screens, feature-oriented components, shared hooks, and API modules.

- 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.

## State and context boundaries

- 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.

## 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.
---
title: "Native architecture"
description: "Architecture overview for d-sports-engage-native application layers and platform behavior."
---

## App architecture

The native app is structured around Expo Router screens, feature-oriented components, shared hooks, and API modules. It follows a **modular architecture** where screen files are thin render shells and all business logic lives in dedicated hooks.

- **Routing:** `app/*` with grouped routes for `(tabs)`, `(auth)`, `(onboarding)`, and `settings/`.
- **Feature logic:** extracted hooks (`hooks/use-wallet-screen.ts`, `hooks/use-shop-screen.ts`, etc.) return flat objects of state and handlers.
- **Shared contexts:** user, collectibles, accessibility, navbar visibility, and action modal state.
- **Components:** organized in domain directories (`components/wallet/`, `components/shop/`, `components/locker-room/`, `components/leaderboard/`) with barrel `index.ts` exports.
- **Styles:** external stylesheets in `styles/` or `components/<domain>/styles/` directories — never inline `StyleSheet.create()` in component files.

## Tab bar

The tab bar implementation differs by platform:

- **iOS:** `app/(tabs)/_layout.ios.tsx` uses `NativeTabs` from `expo-router/unstable-native-tabs` with system tab bar styling, Liquid Glass dark material (`systemChromeMaterialDark`), and gold accent selection (`#FFD700`).
- **Android and web:** `app/(tabs)/_layout.tsx` uses a custom `PillTabBar` overlay with `expo-blur` on Android. The default system tab bar is hidden.
- **Shared config:** `components/navigation/tab-config.ts` defines tab order, SF Symbol pairs (iOS), and active-tab detection helpers.

## State and context boundaries

- Local/ephemeral UI state lives near feature hooks and components.
- Cross-screen state is managed with Zustand (`services/store.ts`) persisted via MMKV (`services/storage.ts`).
- User/session-sensitive state is coordinated with Clerk auth and backend profile sync endpoints via `context/user-context.tsx`.

## API client and retry behavior

- All network calls route through `lib/api/*` modules.
- `lib/api/client.ts` handles auth token injection, error normalization, and retry strategy.
- `lib/api/cache.ts` provides `fetchWithCache()` for MMKV-backed cache-first fetching.
- Quest/reward/team flows consume backend eligibility as source of truth.

## Platform-specific behavior

- iOS/Android platform differences are handled in native-specific layout files and runtime checks.
- Web-target support exists but mobile behavior is primary for interaction and performance design.
- Haptics, modal controls, and animation handling (React Native Reanimated) use platform-safe fallbacks.

## Widgets

The app supports home screen widgets on both platforms:

- **iOS:** `expo-widgets` with a `RankOrPointsWidget` (small/medium) and a `LiveStatusActivity` for Live Activities on the lock screen.
- **Android:** `react-native-android-widget` with a `RankOrPointsWidget` (3x2 cells, 30-minute refresh).
- Widget data is coordinated through `lib/widget-data.ts` and `widgets/widget-controls.ts`.

## CI/CD and OTA updates

- **EAS Build** profiles for development, preview, staging, and production are defined in `eas.json`.
- **EAS Update (OTA)** is triggered via GitHub Actions on pushes to `develop` and `main`, publishing iOS-only updates to the corresponding branch/environment.
- Build and submit commands: `bun run build:prod`, `bun run build:submit:all` (auto-submit to App Store and Play Store).

## Android build configuration

- R8 minification and resource shrinking are enabled for release builds.
- ProGuard rules suppress non-Android desktop class warnings (`-dontwarn java.awt.**`, `-dontwarn com.sun.jna.**`) to prevent release build failures while keeping R8 active.
- Kotlin version is pinned to `2.1.20` via `expo-build-properties` and a custom `withKotlinJvmTarget` plugin.