Files
otunes/apps/mobile/README.md
T

88 lines
4.1 KiB
Markdown

# Mobile build variants
EAS profiles set `APP_VARIANT` to select the app identity in `app.config.ts`.
Both iOS bundle identifiers and Android package names use these values:
| Profile | App name | Identifier |
| --- | --- | --- |
| development | oTunes (Development) | com.abunchofknowitalls.otunes.development |
| preview | oTunes (Preview) | com.abunchofknowitalls.otunes.preview |
| production | oTunes | com.abunchofknowitalls.otunes |
Build with `eas build --profile development`, `--profile preview`, or
`--profile production` from this directory.
For local builds and Metro, select the same variant explicitly:
```sh
APP_VARIANT=development pnpm ios
APP_VARIANT=development pnpm android
APP_VARIANT=development pnpm start
```
An unset `APP_VARIANT` keeps the production identity. Unknown variants fail
configuration. URL schemes are `otunes-development`, `otunes-preview`, and
`otunes` respectively, allowing the apps to be installed together.
### Shared links and artwork
Shared URLs stay as ordinary HTTPS links. The web page's "Open App" action
opens `otunes://open?url=<encoded HTTPS URL>`, including the server address and
album, artist, or playlist destination. No domain association files, signing
settings, or per-server mobile builds are needed.
The app checks the link's server against its configured server before opening
media. Links for another server do not switch the current server. On a fresh
installation, the server address is prefilled in setup. The destination is kept
in memory through setup and sign-in, and is opened after authentication.
The browser may ask before opening the app. If the app is absent, the web page
remains available. Native changes still require a new mobile build.
Native sharing supplies media titles and artwork through iOS link metadata and Android's chooser
thumbnail, while sharing the original HTTPS URL. Receiving apps control whether
they display previews. If artwork cannot load, the URL is still shared. Existing
builds without the native sharing module fall back to URL-only sharing.
### iPad sidebar
Expo Router owns navigation through `NativeTabs sidebarAdaptable`.
`native/TabletSidebar.swift` adds UIKit Library and Playlists groups and the pinned
account footer, which the current Expo Router API does not expose. The bridge
reuses the router's tab instances so each destination retains its navigation stack.
The `react-native-screens` patch checks the selected leaf controller rather than
the group's root controller. It also notifies the sidebar bridge after each native
tab reconciliation, so startup updates cannot replace the Library and Playlists
sections with a flat tab list. Keep both behaviors when updating the dependency.
After changing native modules or dependency patches, run `pod install` in `ios`
and rebuild the development app.
### Mac Catalyst
On a Mac with Xcode and CocoaPods installed, generate the iOS project with
Catalyst enabled. Use a separate checkout for Catalyst builds, since prebuild
changes the generated iOS project and its dependency configuration.
```sh
MAC_CATALYST=1 APP_VARIANT=development pnpm exec expo prebuild --platform ios --clean
open ios/*.xcworkspace
```
In Xcode, select the app scheme and the **My Mac (Mac Catalyst)** destination,
select your signing team, then build and run. For a Release build, use Xcode's
Archive action with the Catalyst destination. EAS's existing iOS profiles still
build iPhone/iPad apps.
Don't enable Catalyst by hand in Xcode; the plugin configures everything during
prebuild. It enables the Xcode target and React Native's CocoaPods patches,
raises pod deployment targets to the app's, and disables precompiled React
Native and Expo modules so dependencies can compile for Catalyst. System volume
stays under macOS control.
The Mac app uses the same bundle identifier as the iOS app, so sign both with the
same team. Handoff only pairs apps with a matching team and activity type, which
`app.config.ts` declares once per build profile in `NSUserActivityTypes`.
To return a checkout to ordinary iOS builds, rerun prebuild without
`MAC_CATALYST=1`. Keep `APP_VARIANT` consistent when starting Metro.