Installation
Get the SwiftUI template building and running in the iOS Simulator.
This guide takes you from a fresh clone to the app running in the iOS Simulator.
The app builds and boots with zero secrets. Every service degrades gracefully — a missing key makes its controller no-op instead of crashing — so you can run the whole app before configuring anything. Wire services in later via Configuration.
Prerequisites
- macOS with Xcode 16+. The project was tooled with Xcode 26.x, but the minimum-deployment target is iOS 17.0.
- An iOS 17+ simulator — iPhone 17 Pro is the canonical simulator the tests target — or a physical iOS 17+ device.
- A paid Apple Developer team — needed only for device runs that exercise APNs push registration. Simulator builds work with the default signing identity. See Push Notifications.
Setup
Clone and open
git clone <repo-url>
cd soar-swift
open SoarStarterSwift.xcodeprojLet Swift Package Manager resolve
On first open, Xcode resolves the package dependencies. Wait for it to finish before building:
- Kingfisher (image loading)
supabase-swift(auth, PostgREST, storage)purchases-ios(RevenueCat)posthog-ios(analytics)sentry-cocoa(crash reporting)- GoogleSignIn (native Google Sign-In)
(Optional) Create your secrets file
Copy the example to create your local, git-ignored secrets file:
cp Secrets.example.xcconfig Secrets.xcconfigThis is optional — skip it for a first run. The tracked AppConfig.xcconfig
supplies safe placeholders, and any key you leave as a placeholder is treated as
unset. See Configuration for the key reference.
Build and run
Select the SoarStarterSwift scheme and an iPhone simulator, then press ⌘R. The app boots to the consent → onboarding → login flow.
Command-line build & run
The canonical commands (matching the template's CLAUDE.md):
# Build (Debug, iPhone 17 Pro simulator — the canonical test destination)
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer \
xcodebuild -project SoarStarterSwift.xcodeproj \
-scheme SoarStarterSwift \
-destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
build
# Run unit + UI tests
xcodebuild -project SoarStarterSwift.xcodeproj \
-scheme SoarStarterSwift \
-destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
-parallel-testing-enabled NO \
test-parallel-testing-enabled NO is required for tests. By default
xcodebuild clones the destination into multiple simulators and runs the unit
target and the XCUITest smoke target concurrently; the unit suites saturate the
CPU and the smoke test's first waitForExistence (Onboarding) times out.
Serial execution keeps them from starving each other. DEVELOPER_DIR is only
needed when multiple Xcode versions are installed and xcode-select points
elsewhere.
Install and launch on a booted simulator after a Debug build:
# Boot a simulator if none is running
xcrun simctl boot "iPhone 17 Pro" && open -a Simulator
# Install the built .app, then launch by bundle id
xcrun simctl install booted /path/to/Build/Products/Debug-iphonesimulator/SoarStarterSwift.app
xcrun simctl launch booted com.soarstarter.SoarStarterSwiftThe bundle id is com.soarstarter.SoarStarterSwift.
Verify the installation
With no secrets configured, confirm the app boots through its launch gates:
- Consent screen appears first and can be accepted.
- Onboarding — the 4-slide carousel advances and completes.
- Login screen renders (email/password fields + social tiles; the Google
tile is dimmed until
GOOGLE_IOS_CLIENT_IDis set). - Component gallery — the Component tab works offline (it renders local UI in every state without a network call).
Auth, todos, subscriptions, and uploads require a Supabase project — continue to Supabase Setup.
Common first-run failures
| Symptom | Likely cause | Fix |
|---|---|---|
Build fails on import Kingfisher / import Supabase | SPM hasn't finished resolving | Wait for package resolution, or File → Packages → Resolve Package Versions |
xcodebuild uses the wrong toolchain | Multiple Xcode versions installed | Prefix with DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer |
Unable to find a destination | The named simulator doesn't exist | Create an iPhone 17 Pro sim in Xcode, or change the -destination name |
| UI tests flake / time out on launch | Parallel testing enabled | Always pass -parallel-testing-enabled NO |
| Signing error on a device run | No paid team selected | Set your team in Signing & Capabilities (device push needs a paid team) |