From 7576d413ca6927f622598649d239827e1e97eac9 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 26 Oct 2026 11:39:41 +0000 Subject: [PATCH 1/2] feat: in-app OTA update banner and EAS update CI fixes Add UpdateBanner using expo-updates useUpdates(), foreground update checks, and i18n strings. Fix eas-update and eas-preview workflows to pass EAS --environment, --message, and APP_ENV. Document OTA behavior in README. Co-authored-by: prdHugo --- .github/workflows/eas-preview.yml | 15 +++- .github/workflows/eas-update.yml | 12 +++- README.md | 13 ++++ src/app/_layout.tsx | 4 +- src/features/updates/update-banner.tsx | 96 ++++++++++++++++++++++++++ src/locales/en/index.ts | 2 + src/locales/en/updates.json | 8 +++ src/locales/fr/index.ts | 2 + src/locales/fr/updates.json | 8 +++ 9 files changed, 157 insertions(+), 3 deletions(-) create mode 100644 src/features/updates/update-banner.tsx create mode 100644 src/locales/en/updates.json create mode 100644 src/locales/fr/updates.json diff --git a/.github/workflows/eas-preview.yml b/.github/workflows/eas-preview.yml index f257f459..6b2764c9 100644 --- a/.github/workflows/eas-preview.yml +++ b/.github/workflows/eas-preview.yml @@ -6,9 +6,17 @@ env: EXPO_PUBLIC_OPENAPI_URL: ${{ vars.OPENAPI_URL }} on: [pull_request] + +permissions: + contents: read + pull-requests: write + jobs: preview: runs-on: ubuntu-latest + env: + # Staging bundle identifiers; preview uses the EAS "preview" environment for secrets. + APP_ENV: staging steps: - name: 🏗 Setup repo uses: actions/checkout@v4 @@ -38,4 +46,9 @@ jobs: with: # `github.event.pull_request.head.ref` is only available on `pull_request` triggers. # Use your own, or keep the automatically inferred branch name from `--auto`, when using different triggers. - command: eas update --auto --branch ${{ github.event.pull_request.head.ref }} + command: >- + eas update --auto + --branch ${{ github.event.pull_request.head.ref }} + --environment preview + --message "PR #${{ github.event.pull_request.number }} (${{ github.sha }})" + --non-interactive diff --git a/.github/workflows/eas-update.yml b/.github/workflows/eas-update.yml index b680f9a6..e5ba430b 100644 --- a/.github/workflows/eas-update.yml +++ b/.github/workflows/eas-update.yml @@ -21,6 +21,11 @@ on: jobs: update: runs-on: ubuntu-latest + env: + # Matches eas.json build profile env and app.config.ts APP_ENV. + APP_ENV: ${{ github.event.inputs.channel }} + # EAS server environments: development | preview | production (staging channel → preview). + EAS_ENVIRONMENT: ${{ github.event.inputs.channel == 'production' && 'production' || (github.event.inputs.channel == 'staging' && 'preview' || 'development') }} steps: - name: 🏗 Setup repo uses: actions/checkout@v5 @@ -46,4 +51,9 @@ jobs: run: pnpm install - name: 🚀 Publish update - run: eas update --branch ${{ github.event.inputs.channel }} --non-interactive + run: >- + eas update + --branch "${{ github.event.inputs.channel }}" + --environment "$EAS_ENVIRONMENT" + --message "Manual update to ${{ github.event.inputs.channel }} (${{ github.sha }})" + --non-interactive diff --git a/README.md b/README.md index 19957976..501740c6 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,19 @@ It represents our team's up-to-date stack that we use when creating native apps > [!NOTE] > OTA updates use `runtimeVersion: { policy: 'fingerprint' }` (balanced preset). New native binaries are required when the fingerprint changes. +## Over-the-air (OTA) updates + +In release builds where `expo-updates` is enabled, the app checks for a newer update when it returns to the foreground (`AppState` → `active`). When an update is available, a small banner at the top of the screen lets users download and reload immediately (or reload if the update was already downloaded). The banner is hidden in development and when updates are disabled (for example Expo Go). + +GitHub Actions publish updates per EAS channel: + +| Channel / workflow | EAS `--environment` | `APP_ENV` (app.config) | Notes | +| ------------------ | --------------------- | ---------------------- | ----- | +| **development** (manual EAS Update workflow) | `development` | `development` | Matches the development build profile | +| **staging** (manual EAS Update workflow) | `preview` | `staging` | Staging channel uses the EAS preview environment for server-side env vars | +| **production** (manual EAS Update workflow) | `production` | `production` | Store / production builds | +| **PR branch** (EAS Preview workflow) | `preview` | `staging` | Publishes to the PR head branch; uses staging app identifiers | + # Requirements - [Node.js](https://nodejs.org) >= 22 diff --git a/src/app/_layout.tsx b/src/app/_layout.tsx index 811e8507..4be5249b 100644 --- a/src/app/_layout.tsx +++ b/src/app/_layout.tsx @@ -19,6 +19,7 @@ import { env } from '@/env'; import { DevTools } from '@/features/devtools/devtools'; import { useThemeSync } from '@/features/theme/use-theme-sync'; import { useThemedStyle } from '@/features/theme/use-themed-style'; +import { UpdateBanner } from '@/features/updates/update-banner'; import { SplashScreenManager } from '@/layout/splash-screen-manager'; // SplashScreen hide management in splash-screen-manager.tsx @@ -37,12 +38,13 @@ export default function RootLayout() { > - + + {env.NODE_ENV === 'development' && ( )} diff --git a/src/features/updates/update-banner.tsx b/src/features/updates/update-banner.tsx new file mode 100644 index 00000000..d491ca8c --- /dev/null +++ b/src/features/updates/update-banner.tsx @@ -0,0 +1,96 @@ +import * as Updates from 'expo-updates'; +import { useCallback, useEffect, useState } from 'react'; +import { useTranslation } from 'react-i18next'; +import { AppState, type AppStateStatus, View } from 'react-native'; +import { useSafeAreaInsets } from 'react-native-safe-area-context'; + +import { Button } from '@/components/ui/button'; +import { Text } from '@/components/ui/text'; + +const logUpdateCheckError = (error: unknown) => { + console.warn('[expo-updates] checkForUpdateAsync failed', error); +}; + +export function UpdateBanner() { + if (__DEV__ || !Updates.isEnabled) { + return null; + } + + return ; +} + +function UpdateBannerContent() { + const { t } = useTranslation(['updates']); + const insets = useSafeAreaInsets(); + const { isUpdateAvailable, isUpdatePending, isDownloading } = + Updates.useUpdates(); + const [isApplying, setIsApplying] = useState(false); + + const checkForUpdate = useCallback(() => { + Updates.checkForUpdateAsync().catch(logUpdateCheckError); + }, []); + + useEffect(() => { + if (AppState.currentState === 'active') { + checkForUpdate(); + } + + const subscription = AppState.addEventListener( + 'change', + (nextState: AppStateStatus) => { + if (nextState === 'active') { + checkForUpdate(); + } + } + ); + + return () => subscription.remove(); + }, [checkForUpdate]); + + const showBanner = isUpdateAvailable || isUpdatePending; + if (!showBanner) { + return null; + } + + const isLoading = isDownloading || isApplying; + + const handlePress = async () => { + try { + setIsApplying(true); + if (isUpdatePending) { + await Updates.reloadAsync(); + return; + } + await Updates.fetchUpdateAsync(); + await Updates.reloadAsync(); + } catch (error) { + console.warn('[expo-updates] apply update failed', error); + } finally { + setIsApplying(false); + } + }; + + const actionLabel = isUpdatePending + ? t('updates:banner.reload') + : isLoading + ? t('updates:banner.downloading') + : t('updates:banner.update'); + + return ( + + {t('updates:banner.message')} + + + ); +} diff --git a/src/locales/en/index.ts b/src/locales/en/index.ts index d0f621eb..8d7d46c6 100644 --- a/src/locales/en/index.ts +++ b/src/locales/en/index.ts @@ -7,6 +7,7 @@ import books from './books.json' with { type: 'json' }; import common from './common.json' with { type: 'json' }; import home from './home.json' with { type: 'json' }; import layout from './layout.json' with { type: 'json' }; +import updates from './updates.json' with { type: 'json' }; export default { account, @@ -16,4 +17,5 @@ export default { home, layout, appOnboarding, + updates, } as const; diff --git a/src/locales/en/updates.json b/src/locales/en/updates.json new file mode 100644 index 00000000..1cd436e7 --- /dev/null +++ b/src/locales/en/updates.json @@ -0,0 +1,8 @@ +{ + "banner": { + "message": "A new version of the app is available.", + "update": "Update", + "reload": "Reload", + "downloading": "Downloading…" + } +} diff --git a/src/locales/fr/index.ts b/src/locales/fr/index.ts index e41ce3cd..434bf343 100644 --- a/src/locales/fr/index.ts +++ b/src/locales/fr/index.ts @@ -7,6 +7,7 @@ import books from './books.json' with { type: 'json' }; import common from './common.json' with { type: 'json' }; import home from './home.json' with { type: 'json' }; import layout from './layout.json' with { type: 'json' }; +import updates from './updates.json' with { type: 'json' }; export default { account, @@ -16,4 +17,5 @@ export default { home, layout, appOnboarding, + updates, } as const; diff --git a/src/locales/fr/updates.json b/src/locales/fr/updates.json new file mode 100644 index 00000000..a5fe64d9 --- /dev/null +++ b/src/locales/fr/updates.json @@ -0,0 +1,8 @@ +{ + "banner": { + "message": "Une nouvelle version de l'application est disponible.", + "update": "Mettre à jour", + "reload": "Recharger", + "downloading": "Téléchargement…" + } +} From 50969863b4b31248543d641e06e96572febd0209 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 26 Oct 2026 11:43:01 +0000 Subject: [PATCH 2/2] docs: add Expo/EAS OTA setup guide for forks Document project linking, update:configure, channels/branches, EAS environments and env vars, EXPO_TOKEN, initial builds, and staging test flow. Co-authored-by: prdHugo --- README.md | 122 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) diff --git a/README.md b/README.md index 501740c6..5876a400 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,128 @@ GitHub Actions publish updates per EAS channel: | **production** (manual EAS Update workflow) | `production` | `production` | Store / production builds | | **PR branch** (EAS Preview workflow) | `preview` | `staging` | Publishes to the PR head branch; uses staging app identifiers | +### Expo / EAS setup + +Follow these steps after forking so OTA updates work end to end. Official references: [EAS Update](https://docs.expo.dev/eas-update/getting-started/), [environment variables](https://docs.expo.dev/eas/environment-variables/), [GitHub Actions with Expo](https://github.com/expo/expo-github-action). + +1. **Create or link an EAS project** + + ```bash + npm install -g eas-cli # or: pnpm add -g eas-cli + eas login + eas whoami + eas init # create a new project, or link an existing one + # Link to a project you already created on expo.dev: + # eas init --id + ``` + + In `app.config.ts`, replace Bear Studio values with your own: + + | Field | Purpose | + | ----- | ------- | + | `EAS_PROJECT_ID` | UUID from [expo.dev](https://expo.dev) → your project → **Project settings** | + | `owner` | Expo account or organization slug | + | `PROJECT_SLUG` | Project slug on Expo (must match the linked project) | + | `updates.url` | `https://u.expo.dev/` (keep in sync with the project ID) | + | `extra.eas.projectId` | Same UUID as `EAS_PROJECT_ID` | + +2. **Configure EAS Update** + + ```bash + eas update:configure + ``` + + This command adds or updates `updates.url`, `runtimeVersion`, and `extra.eas.projectId` in your app config ([docs](https://docs.expo.dev/eas-update/getting-started/#configure-your-project)). + + This repo already sets `runtimeVersion: { policy: 'fingerprint' }` instead of a fixed string. The fingerprint changes when native dependencies or config change, so users need a **new `eas build`** for those changes; JavaScript-only fixes can ship via `eas update`. + +3. **Channels, branches, and build profiles** + + Each `eas.json` build profile pins a **channel** (embedded in the binary at build time): + + | Profile | Channel in `eas.json` | + | ------- | --------------------- | + | `development` | `development` | + | `staging` | `staging` | + | `production` | `production` | + + On EAS, a **channel** points at an **update branch** (where `eas update` publishes). By default, channel and branch names often match; verify or fix the mapping: + + ```bash + eas channel:list + eas branch:list + # Point channel "staging" at branch "staging" (example): + eas channel:edit staging --branch staging + # Create a channel or branch if missing: + eas channel:create staging + eas branch:create staging + ``` + + **PR previews:** the [EAS Preview](.github/workflows/eas-preview.yml) workflow runs `eas update` on the **PR head branch** name. A device only receives that update if its installed build’s channel is pointed at that branch (via `eas channel:edit`), or you open the update using the **preview link / QR code** from the GitHub PR comment (development client or compatible preview flow). Production/staging channel builds do not automatically subscribe to arbitrary PR branch names. + +4. **EAS environments and variables** + + EAS provides three environments: `development`, `preview`, and `production`. For **SDK 55+**, `eas update` must pass `--environment` so the job uses the matching variables ([docs](https://docs.expo.dev/eas/environment-variables/#quick-start)). + + This starter’s CI maps **update channel → EAS environment** as follows (staging channel uses EAS `preview` because there is no separate `staging` environment on Expo): + + | Update target | `--environment` | `APP_ENV` at publish time | + | ------------- | ----------------- | ------------------------- | + | `development` channel | `development` | `development` | + | `staging` channel | `preview` | `staging` | + | `production` channel | `production` | `production` | + | PR preview workflow | `preview` | `staging` | + + Set project variables on [expo.dev](https://expo.dev) → your project → **Environment variables**, or with the CLI: + + ```bash + # Required for the app bundle (see src/env.ts) + eas env:set --name EXPO_PUBLIC_BASE_URL --value https://your-api.example.com --environment production --visibility plaintext + + # Optional overrides (defaults are derived from EXPO_PUBLIC_BASE_URL in src/env.ts) + eas env:set --name EXPO_PUBLIC_AUTH_URL --value https://your-api.example.com/api/auth --environment production --visibility plaintext + eas env:set --name EXPO_PUBLIC_OPENAPI_URL --value https://your-api.example.com/openapi/app/schema --environment production --visibility plaintext + eas env:set --name EXPO_PUBLIC_API_URL --value https://your-api.example.com/api/rest --environment production --visibility plaintext + + # Baked into app.config.ts at update/build time (icons, bundle ID, scheme) + eas env:set --name APP_ENV --value production --environment production --visibility plaintext + ``` + + Repeat for `development` and `preview` with values appropriate to each environment (`APP_ENV` should be `development`, `staging`, or `production` to match the flavor you are publishing). + + GitHub Actions workflows read `EXPO_PUBLIC_*` from repository **Variables** (`API_URL`, `AUTH_URL`, `OPENAPI_URL`); keep those aligned with your EAS variables for CI publishes. + +5. **GitHub Actions: `EXPO_TOKEN` and permissions** + + 1. Create an [access token](https://docs.expo.dev/accounts/programmatic-access/) on expo.dev (robot or personal token with access to the project). + 2. Add it as repository secret **`EXPO_TOKEN`** ([Settings → Secrets and variables → Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions)). + 3. Configure [GitHub variables](#variables) (`API_URL`, etc.) as documented below. + 4. **EAS Preview** needs `permissions: pull-requests: write` and `contents: read` so `expo/expo-github-action/preview` can comment on PRs (already set in `.github/workflows/eas-preview.yml`). + +6. **Install a release binary before OTA** + + Updates apply only to builds that include `expo-updates` with your channel and runtime version. Build and install once per channel you use: + + ```bash + eas build --profile development --platform ios # or android, or --platform all + eas build --profile staging --platform all + eas build --profile production --platform all + ``` + + OTA does **not** apply in **Expo Go**, in Metro dev mode (`__DEV__`), or when `expo-updates` is disabled; the in-app banner is hidden in those cases. + +7. **Test the flow (staging example)** + + 1. Install a **staging** build (`eas build --profile staging` + internal distribution). + 2. Publish an update: GitHub Actions → **EAS Update** → channel `staging`, or locally: + + ```bash + APP_ENV=staging eas update --branch staging --environment preview --message "Test staging OTA" --non-interactive + ``` + + 3. Open the staging app, send it to the background, then foreground again (triggers `checkForUpdateAsync`). + 4. When the banner appears, tap **Update** (or **Reload** if the update was already downloaded) and confirm the app reloads with your change. + # Requirements - [Node.js](https://nodejs.org) >= 22