Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
15 changes: 14 additions & 1 deletion .github/workflows/eas-preview.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
12 changes: 11 additions & 1 deletion .github/workflows/eas-update.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
135 changes: 135 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,141 @@ 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 |

### 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 <your-eas-project-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/<EAS_PROJECT_ID>` (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
Expand Down
4 changes: 3 additions & 1 deletion src/app/_layout.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -37,12 +38,13 @@ export default function RootLayout() {
>
<ThemeProvider value={themedStyle.navigationTheme}>
<GestureHandlerRootView style={{ flex: 1 }}>
<View className="flex-1 bg-background">
<View className="bg-background flex-1">
<ThemedStatusBar />
<SplashScreenManager>
<Slot />
</SplashScreenManager>
<Sonner />
<UpdateBanner />
{env.NODE_ENV === 'development' && (
<DevTools queryClient={queryClient} />
)}
Expand Down
96 changes: 96 additions & 0 deletions src/features/updates/update-banner.tsx
Original file line number Diff line number Diff line change
@@ -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 <UpdateBannerContent />;
}

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 (
<View
className="border-border bg-card absolute inset-x-0 z-50 flex-row items-center justify-between gap-3 border-b px-4 py-2.5 shadow-sm"
style={{ top: insets.top }}
pointerEvents="box-none"
>
<Text className="flex-1 text-sm">{t('updates:banner.message')}</Text>
<Button
size="sm"
variant="default"
disabled={isLoading}
onPress={handlePress}
>
{actionLabel}
</Button>
</View>
);
}
2 changes: 2 additions & 0 deletions src/locales/en/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -16,4 +17,5 @@ export default {
home,
layout,
appOnboarding,
updates,
} as const;
8 changes: 8 additions & 0 deletions src/locales/en/updates.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"banner": {
"message": "A new version of the app is available.",
"update": "Update",
"reload": "Reload",
"downloading": "Downloading…"
}
}
2 changes: 2 additions & 0 deletions src/locales/fr/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -16,4 +17,5 @@ export default {
home,
layout,
appOnboarding,
updates,
} as const;
8 changes: 8 additions & 0 deletions src/locales/fr/updates.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"banner": {
"message": "Une nouvelle version de l'application est disponible.",
"update": "Mettre à jour",
"reload": "Recharger",
"downloading": "Téléchargement…"
}
}
Loading