Skip to content

Update engage-native docs for SDK 55 migration #284

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

Update engage-native docs for SDK 55 migration #284

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
38 changes: 32 additions & 6 deletions repositories/d-sports-engage-native.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
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 0.83, Clerk, RevenueCat, Thirdweb."
icon: "smartphone"
---

Expand All @@ -14,32 +14,57 @@ icon: "smartphone"

| Category | Technology |
| ---------- | ------------------------- |
| Framework | Expo 54, React Native 0.81, React 19 |
| Framework | Expo 55, React Native 0.83, React 19.2 |
| Auth | Clerk (Expo) |
| Payments | RevenueCat (react-native-purchases) |
| Web3 | Thirdweb |
| State | Zustand |
| Storage | MMKV |
| UI | Lucide React Native |
| Navigation | Expo Router |
| Navigation | Expo Router (file-based, typed routes) |
| Widgets | `expo-widgets` (iOS), `react-native-android-widget` (Android) |
| Monitoring | Sentry |
| Push | OneSignal |
| 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
- **Locker room** — Social feed, daily games (Pick 'Em, Spin Wheel, Guess the Player)
- **Profile** — User profile, achievements, milestone avatars, and settings
- **Widgets** — Cross-platform home-screen widgets showing rank or wallet points (iOS and Android)
- **Live Activities** — iOS Live Activity for real-time score and status updates
- **Theme** — Dark/light mode (default dark)

## What changed since last docs sync

- **Expo SDK 55 migration** — upgraded from Expo 54 / React Native 0.81 to Expo 55 / React Native 0.83 / React 19.2.
- **Cross-platform widgets** — added iOS home-screen widget (`RankOrPointsWidget`) via `expo-widgets`, iOS Live Activity (`LiveStatusActivity`), and Android widget via `react-native-android-widget`.
- **iOS native tab bar** — iOS now uses `NativeTabs` from `expo-router/unstable-native-tabs` with Liquid Glass dark material and gold accent. Android and web use a custom `PillTabBar` overlay with blur.
- **Router features** — adopted Apple zoom transitions for leaderboard card navigation and `NativeTabs` screen listeners for selection haptics.
- **EAS Update and CI** — added GitHub Actions workflow for OTA updates via `eas-cli update`.
- 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.
- Settings and account flows were expanded, including in-app account deletion and richer support/data controls.

## Environment variables

The app uses `EXPO_PUBLIC_*` environment variables at runtime:

| 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 client ID for Web3 |
| `EXPO_PUBLIC_REVENUECAT_API_KEY` | RevenueCat in-app purchases |
| `EXPO_PUBLIC_REVENUECAT_APPSTORE_ID` | RevenueCat App Store identifier |
| `EXPO_PUBLIC_REVENUECAT_ENTITLEMENT` | RevenueCat entitlement name |
| `EXPO_PUBLIC_SUPABASE_URL` | Supabase client URL |
| `EXPO_PUBLIC_SUPABASE_KEY` | Supabase publishable key |

## Backend integration surfaces

- Primary API source: `d-sports-api` under `/api/*`.
Expand All @@ -65,9 +90,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. Copy `.env` and configure environment variables (Clerk, RevenueCat, Thirdweb, API base URL, Supabase).
3. Run `bunx expo start`.
4. For development builds: `bun run build:dev` (EAS) or run with Expo dev client.
5. For OTA updates: `bun run update` (production) or `bun run update:preview` (preview channel).

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
36 changes: 31 additions & 5 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 @@ -7,24 +7,50 @@ description: "Architecture overview for d-sports-engage-native application layer

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.
- **Routing:** `app/*` with grouped routes — `(tabs)` for main navigation, `(auth)` for login/signup, `(onboarding)` for new users, and `settings/` for nested settings pages.
- **Feature logic:** extracted hooks for wallet (`use-wallet-screen.ts`), shop (`use-shop-screen.ts`), feed (`use-feed-section.ts`), and settings (`use-user-settings.ts`).
- **Shared contexts:** user, collectibles, accessibility, navbar visibility, and action modal state.
- **Modular screens:** screen files contain only JSX; all state, effects, and handlers live in dedicated hooks.

## 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.
- **Zustand + MMKV** provides global synchronous state (theme, cart, points) via `services/store.ts`.

## API client and retry behavior

- All network calls route through `lib/api/*` modules.
- All network calls route through `lib/api/*` modules (wallet, shop, user, quests, leaderboard, locker room, teams, collectibles, checkout, games).
- Client wrappers handle auth token propagation, error normalization, and retry strategy.
- MMKV-backed cache-first fetching is available via `lib/api/cache.ts`.
- Quest/reward/team flows should consume backend eligibility as source of truth.

## Tab bar — platform split

The tab bar implementation differs by platform:

- **iOS:** uses `NativeTabs` from `expo-router/unstable-native-tabs` with `systemChromeMaterialDark` blur and gold selection accent (`#FFD700`). Wallet tab shows a numeric badge for unopened packs.
- **Android and web:** uses a custom `PillTabBar` overlay with `expo-blur` and `Tabs` from Expo Router (default tab bar hidden).
- **Shared config:** `components/navigation/tab-config.ts` defines tab order, SF Symbol pairs for iOS, and active-tab pathname rules.

## Widgets and Live Activities

Cross-platform home-screen widgets were added as part of the SDK 55 migration:

- **iOS widget** (`widgets/ios/RankOrPointsWidget.tsx`) — displays team rank or wallet points. Configured via `expo-widgets` plugin with `systemSmall` and `systemMedium` families.
- **iOS Live Activity** (`widgets/ios/LiveActivityStatus.tsx`) — real-time score/status updates using `accessoryRectangular` and `accessoryInline` families.
- **Android widget** (`widgets/android/registry.tsx`) — uses `react-native-android-widget` with a 30-minute auto-refresh interval.
- Widget controls are isolated to dev-only usage via `globalThis.__DS_WIDGETS__` and `__DEV__` guards.

## Platform-specific behavior

- iOS/Android platform differences are handled in native-specific components and runtime checks.
- iOS/Android platform differences are handled in native-specific components (e.g., `_layout.ios.tsx` vs `_layout.android.tsx`) 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.

## EAS builds and OTA updates

- EAS profiles are defined in `eas.json` for development, preview, and production builds.
- OTA updates use `expo-updates` with runtime version pinned to the app version (currently `1.18.0`).
- CI publishes updates via GitHub Actions (`eas-update.yml`) using `bunx eas-cli update`.