Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.swiftaiboilerplate.com/llms.txt

Use this file to discover all available pages before exploring further.

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.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/BerkinSi/SwiftAIBoilerplatePro-Distribution.git
cd SwiftAIBoilerplatePro
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), see the Production Setup Guide.

​
4. Explore the App

​
What You’ll See

1

Onboarding

Swipe through 3 onboarding pages → tap “Get Started”
2

Sign In

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

Home Screen

See feature cards, quick actions, and subscription status
4

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

  • Sign in with any email/password (mock mode)
  • Sign out and sign back in
  • Profile persists across restarts
  • Create conversation
  • Send messages
  • Receive echo responses
  • Switch UI styles
  • Rename/delete conversations
  • Edit display name
  • Upload photo (compresses automatically)
  • View subscription status
  • 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:
ComponentMock BehaviorProduction
AuthMockAuthClient - any credentials workSupabaseAuthClient
AIEchoLLMClient - echoes messagesProxyLLMClient → OpenRouter
PaymentsMockPaymentsClient - simulated statesRevenueCatClient
StorageLocal SwiftDataLocal + optional cloud sync
Mock mode is perfect for:
  • Learning the codebase
  • UI development
  • Testing without API costs
  • Demo purposes

​
Next Steps

Jump straight to customization:Change branding (5 minutes):
  1. App name: Edit Config/App.xcconfig
  2. Colors: Edit DesignSystemColors.xcassets
  3. 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
xcodebuild test \
  -scheme SwiftAIBoilerplatePro \
  -destination 'platform=iOS Simulator,name=iPhone 15'
Expected: 338+ tests pass ✅

​
Troubleshooting

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.
.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.
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”.
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.
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.
Solution:
# Clean and rebuild
⌘ + Shift + K
File → Packages → Reset Package Caches
⌘ + B
Cause: Running in Release modeSolution:
  1. Product → Scheme → Edit Scheme
  2. Run → Build Configuration → Debug
  3. Clean and rebuild
Solution:
File → Packages → Resolve Package Versions
# If still fails:
File → Packages → Update to Latest Package Versions

​
Quick Reference

​
File Locations

Config/Secrets.xcconfig               # API keys (gitignored)
SwiftAIBoilerplatePro/AppShell/       # UI screens
SwiftAIBoilerplatePro/Composition/    # DI container
Packages/*/                           # 11 Swift Packages

​
Key Files for Customization

What to ChangeFile Location
App nameConfig/App.xcconfig
ColorsResources/DesignSystemColors.xcassets/
OnboardingAppShell/OnboardingPage.swift
Home screenAppShell/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
  • ✅ Crashlytics setup
  • ✅ 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!