Quick Start

This guide gets you running fast. For a full production setup with real backends, follow the step-by-step instructions in the setup guides.

1. Prerequisites

Ensure you have:

✅ macOS 15+
✅ Xcode 26.2+ (iOS 26 SDK, Swift 6.0)
✅ 10 minutes

v2.2.0 ships with iOS 26 Liquid Glass. Runtime still supports iOS 17+ thanks to a Material fallback in SAIGlass, but the build requires Xcode 26.2+. Stuck on older Xcode? Pin the v1.9.0 tag.

2. Clone and Open

git clone https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution.git
cd SwiftAIBoilerplatePro-Distribution
open SwiftAIBoilerplatePro.xcodeproj

Xcode will automatically resolve Swift Package dependencies. Wait ~30 seconds for this to complete.

3. Run Immediately (No Configuration Needed!)

Press ⌘ + R in Xcode - that’s it!

The app works immediately with placeholder configuration:

MockAuthClient - Sign in with any email/password
EchoLLMClient - AI echoes your messages back
All features work for exploration
No API keys or setup required

To use real services (Supabase, OpenRouter, RevenueCat), follow the Production setup path below.

4. Explore the App

What You’ll See

Onboarding

Swipe through 3 onboarding pages → tap “Get Started”

Tap “Debug Sign In” (or use any email/password in mock mode)

Home Screen

See feature cards, quick actions, and subscription status

Chat

Tap “Start Chat” → send a message → receive echo response

Success! If you can send chat messages, you have a working AI app foundation.

5. Explore Features

Try These Flows

Chat UI Styles:

Tap the style switcher icon (top-right in chat)
Switch between bubble style (WhatsApp) and centered style (ChatGPT)

Profile:

Tap profile icon → edit display name
Try uploading a photo (iOS 17+ PhotosPicker)
Check subscription status

Settings:

Open Settings tab
Try different themes (5 included: System, Light, Dark, Aurora, Obsidian)
Toggle preferences

Chat Management:

Create multiple conversations
Rename conversations (long press)
Delete conversations (swipe left)
Search conversations

Verify Everything Works

✅ Authentication

Sign in with any email/password (mock mode)
Sign out and sign back in
Profile persists across restarts

✅ Chat

Create conversation
Send messages
Receive echo responses
Switch UI styles
Rename/delete conversations

✅ Profile

Edit display name
Upload photo (compresses automatically)
View subscription status

✅ Settings

Change themes (instant update)
Toggle preferences
All settings persist

What’s Running in Mock Mode

The app automatically detects missing backend configuration and uses mocks:

Component	Mock Behavior	Production
Auth	`MockAuthClient` - any credentials work	`SupabaseAuthClient`
AI	`EchoLLMClient` - echoes messages	`ProxyLLMClient` → OpenRouter
Payments	`MockPaymentsClient` - simulated states	`RevenueCatClient`
Storage	Local SwiftData	Local + optional cloud sync

Mock mode is perfect for:

Learning the codebase
UI development
Testing without API costs
Demo purposes

Next Steps

Customize Immediately
Understand Architecture
Setup Production Backends

Jump straight to customization:Change branding (5 minutes):

App display name: set appDisplayName in Packages/DesignSystem/Sources/DesignSystem/Tokens/BrandConfig.swift (and the target’s Display Name under Xcode → General). Set the bundle ID via APP_BUNDLE_ID in Config/App.xcconfig.
Colors: Edit SwiftAIBoilerplatePro/Resources/DesignSystemColors.xcassets
Icon: Replace in Assets.xcassets/AppIcon.appiconset

Full customization guide in project →

Run Tests

Verify everything with the test suite:

# In Xcode
⌘ + U

# Or command line — runs the Boilerplate.xctestplan in one pass
xcodebuild test \
  -scheme SwiftAIBoilerplatePro \
  -testPlan Boilerplate \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=26.2'

Expected: ~598 tests pass across 12 package test targets + the app test suites (one Boilerplate.xctestplan run). ✅

Troubleshooting

Cannot find 'Glass' in scope on older Xcode

Cause: Liquid Glass APIs (Glass, glassEffect, GlassEffectContainer) are iOS 26 SDK symbols. Older toolchains cannot compile them, even behind #available checks.Solution: Upgrade to Xcode 26.2+ (the repo pins 26.3 via .xcode-version), or stay on the v1.9.0 tag until you can upgrade.

Tab bar doesn't minimise on scroll

.tabBarMinimizeBehavior(.onScrollDown) is iOS 26 only. On iOS 17–25 the saiTabBarMinimize(_:) modifier is a no-op and returns the same view. No action needed; behaviour is progressive.

Dark blobs under my sheets / sheets look opaque

Cause: You (or downstream code) applied DSColors.background.ignoresSafeArea() or .background(.black) under the container. These block the Material SwiftUI already provides and fight Liquid Glass on iOS 26.Solution: Remove the manual background. SwiftUI handles sheet materials for you on iOS 26. See the Migration Guide section “Fighting glass cleanup”.

`any` keyword required everywhere

Swift 6 enforces explicit any on protocol-typed stored properties and parameters. The boilerplate has been audited for this already; your own types may need updates. See the Migration Guide.

MainActor-isolated error on ModelContext

Cause: MessageRepositoryImpl, ConversationRepositoryImpl, and SettingsRepositoryImpl are now @MainActor-pinned in v2.0.Solution: Create repositories from the main thread, or await when constructing them from a background context.

App won't build

Solution:

# Clean and rebuild
⌘ + Shift + K
File → Packages → Reset Package Caches
⌘ + B

Dependencies won't resolve

Solution:

File → Packages → Resolve Package Versions
# If still fails:
File → Packages → Update to Latest Package Versions

Production Setup Path

When you are ready to leave mock mode, set up real services in this order:

Configure Supabase

Create the Supabase project, copy Config/Secrets.example.xcconfig to Config/Secrets.xcconfig, and add your project URL and anon key.Supabase setup guide

Configure authentication providers

Keep mock auth while exploring. Set up Apple, Google, and email auth when you are ready for real accounts.Authentication guide

Deploy the AI proxy

Add your OpenRouter key to the Supabase Edge Function and deploy the ai function so API keys stay server-side.Deployment guide

Configure subscriptions

Set up RevenueCat products, entitlements, and API keys before testing paywalls.RevenueCat setup guide

Add optional production services

Add Crashlytics, OneSignal push notifications, chat sync, and profile photos only when your app needs them.Crashlytics · OneSignal · Chat Sync · Profile Photos

Quick Reference

File Locations

Config/Secrets.xcconfig               # API keys (gitignored)
SwiftAIBoilerplatePro/AppShell/       # UI screens
SwiftAIBoilerplatePro/Composition/    # DI container
Packages/*/                           # 11 reusable Swift packages + TestSupport (test infra)

Key Files for Customization

What to Change	File Location
App display name	`Packages/DesignSystem/Sources/DesignSystem/Tokens/BrandConfig.swift` (`appDisplayName`)
App bundle ID	`Config/App.xcconfig` (`APP_BUNDLE_ID`)
Colors	`SwiftAIBoilerplatePro/Resources/DesignSystemColors.xcassets/`
Onboarding	`AppShell/OnboardingPage.swift`
Home screen	`AppShell/HomeContent.swift`

Useful Commands

# Run tests with coverage
./scripts/run-tests.sh --coverage --open

# Clean build
⌘ + Shift + K (in Xcode)

# Resolve packages
File → Packages → Resolve Package Versions

What You’ve Learned

You now have:

✅ A running AI chat app
✅ Working authentication (mock mode)
✅ Functional chat with dual UIs
✅ Profile management
✅ Theme system (5 themes)
✅ Understanding of mock vs production

Ready to Build?

Customize

Change branding, features, and UI

Architecture

Learn the system design

Deploy

Ship to production

Pro tip: Use the Building Your App guide which includes ready-to-use LLM prompts for Cursor/Claude to speed up customization!

The App Generator — a standalone macOS app that drives your own coding-agent CLI (Claude Code, Codex, Gemini, or Cursor) to generate a differentiated app from this template — is a separate product (coming soon). See pricing & license for details.

Getting Started

Setup Guides

Core Modules

Feature Modules

Migration

Reference

Before You Submit

1. Prerequisites

2. Clone and Open

3. Run Immediately (No Configuration Needed!)

4. Explore the App

What You’ll See

5. Explore Features

Try These Flows

Verify Everything Works

What’s Running in Mock Mode

Next Steps

Run Tests

Troubleshooting

Production Setup Path

Quick Reference

File Locations

Key Files for Customization

Useful Commands

What You’ve Learned

Ready to Build?

Customize

Architecture

Deploy

​1. Prerequisites

​2. Clone and Open

​3. Run Immediately (No Configuration Needed!)

​4. Explore the App

​What You’ll See

​5. Explore Features

​Try These Flows

​Verify Everything Works

​What’s Running in Mock Mode

​Next Steps

​Run Tests

​Troubleshooting

​Production Setup Path

​Quick Reference

​File Locations

​Key Files for Customization

​Useful Commands

​What You’ve Learned

​Ready to Build?

Customize

Architecture

Deploy

1. Prerequisites

2. Clone and Open

3. Run Immediately (No Configuration Needed!)

4. Explore the App

What You’ll See

5. Explore Features

Try These Flows

Verify Everything Works

What’s Running in Mock Mode

Next Steps

Run Tests

Troubleshooting

Production Setup Path

Quick Reference

File Locations

Key Files for Customization

Useful Commands

What You’ve Learned

Ready to Build?