> ## 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.

# Installation

> Get the boilerplate running in **under 10 minutes**.

## Prerequisites

Before starting, ensure you have:

* **macOS 15+ with Xcode 26.2+**. v2.2.0 uses the iOS 26 SDK to compile Liquid Glass APIs (`Glass`, `glassEffect`, `GlassEffectContainer`). Runtime still supports iOS 17+ via a SwiftUI `Material` fallback built into `SAIGlass`.
* Swift 6.0 toolchain (bundled with Xcode 26.2+)
* Git installed

<Note>
  No backend setup required for initial run. The app includes mock backends for immediate development.
</Note>

<Warning>
  **Using older Xcode?** Stay on the [`v1.9.0`](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.9.0) tag until you can upgrade. v2.0 and later use iOS 26 SDK symbols that older toolchains cannot compile, regardless of `#available` checks.
</Warning>

## Step 1: Get the Repository

You have three options to access the boilerplate:

<Tabs>
  <Tab title="Clone (Recommended)">
    Clone the repository to get started immediately with easy updates:

    ```bash theme={null}
    git clone https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution.git
    cd SwiftAIBoilerplatePro-Distribution
    ```

    Pull updates anytime with `git pull`.
  </Tab>

  <Tab title="Fork">
    Fork the repository to your own GitHub account for full control:

    1. Click **Fork** on the repository page
    2. Clone your fork:

    ```bash theme={null}
    git clone https://github.com/YOUR_USERNAME/SwiftAIBoilerplatePro-Distribution.git
    cd SwiftAIBoilerplatePro-Distribution
    ```

    Sync upstream updates when needed.
  </Tab>

  <Tab title="Download ZIP">
    Download directly without Git:

    1. Go to the repository page
    2. Click **Code** → **Download ZIP**
    3. Extract and open in Xcode
  </Tab>
</Tabs>

<Warning>
  **Keep it private!** All forks and copies must remain in **private repositories**. Do not make your fork public or share the boilerplate code publicly. This protects the code and your [license](/pages/reference/license).
</Warning>

## Step 1.1: Version Control Safely

If you cloned the boilerplate, do not push your app changes back to the boilerplate repository. The safest workflow is to keep two Git remotes:

* `upstream`: the original SwiftAI Boilerplate Pro repository, used only to pull future boilerplate updates
* `origin`: your private repository, used for your app's code

<Steps>
  <Step title="Rename the boilerplate remote to upstream">
    After cloning, Git names the boilerplate repository `origin`. Rename it so normal pushes do not go back to the boilerplate source.

    ```bash theme={null}
    git remote rename origin upstream
    git remote -v
    ```
  </Step>

  <Step title="Create an empty private repository">
    In GitHub, GitLab, or Bitbucket, create a new **private** repository for your app. Do not initialize it with a README, license, or `.gitignore` because the boilerplate already includes project files.
  </Step>

  <Step title="Add your private repository as origin">
    Replace the URL with your private repository URL:

    ```bash theme={null}
    git remote add origin https://github.com/YOUR_USERNAME/YOUR_PRIVATE_REPO.git
    ```
  </Step>

  <Step title="Push your first private copy">
    Most projects use `main`. If your local branch is named `master`, replace `main` with `master`.

    ```bash theme={null}
    git push -u origin main
    ```
  </Step>
</Steps>

### Daily Git Workflow

After setup, your normal commits go to your private repository:

```bash theme={null}
git add .
git commit -m "Add my custom feature"
git push
```

### Pull Boilerplate Updates Later

When a new boilerplate version ships, pull it from `upstream` and then push the merged result to your private `origin`:

```bash theme={null}
git fetch upstream
git merge upstream/main
git push
```

<Note>
  Future-version access depends on your tier. The **$199 lifetime license** includes all future versions and updates; the **$99 single download** is a current-version snapshot only. Existing buyers keep lifetime access (and get App Generator access when it ships). See [License & updates](/pages/reference/license).
</Note>

### Handling Merge Conflicts

Merge conflicts can happen when you and the boilerplate both changed the same lines. Git will pause the merge and mark the files with conflict markers:

```text theme={null}
<<<<<<< HEAD
your app changes
=======
new boilerplate changes
>>>>>>> upstream/main
```

Open each conflicted file, keep the final code you want, delete the marker lines, then finish the merge:

```bash theme={null}
git status
git add .
git commit -m "Resolve upstream merge conflicts"
git push
```

<Tip>
  Keep custom app code in your private `origin`. Use `upstream` only for reading and merging official boilerplate updates.
</Tip>

## Step 2: Open in Xcode

```bash theme={null}
open SwiftAIBoilerplatePro.xcodeproj
```

<Tip>
  The project uses Swift Package Manager. Xcode will automatically resolve dependencies on first open (takes \~30 seconds).
</Tip>

<Tip>
  If you use `xcodes` or `asdf-xcode`, the repo pins `26.3` via `.xcode-version`. Run `xcodes install` (or `asdf install xcode`) inside the repo to match.
</Tip>

## Step 3: Configure Environment (Optional)

**For immediate testing:** You can skip this step! The app runs with mock services out of the box.

**For production services:**

1. **Copy the config template:**

```bash theme={null}
cp Config/Secrets.example.xcconfig Config/Secrets.xcconfig
```

2. **Fill in your API keys** in `Config/Secrets.xcconfig`

3. **IMPORTANT - Update configuration:**

```bash theme={null}
bash scripts/update-config.sh
```

<Warning>
  Every time you change `Config/Secrets.xcconfig`, you **must** run `bash scripts/update-config.sh` and rebuild. This is **not automatic**.
</Warning>

<Info>
  **For immediate testing**, you can leave the default placeholder values! The app will use:

  * `MockAuthClient` (no Supabase needed)
  * `EchoLLMClient` (echoes messages back)
  * No payment functionality
</Info>

## Step 4: Build and Run

Press **⌘ + R** in Xcode or:

```bash theme={null}
xcodebuild -scheme SwiftAIBoilerplatePro \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=26.2'
```

## What You'll See

On first run, the app will:

1. **Show onboarding** - 3 swipeable pages
2. **Display sign-in** - Use any email/password (mock auth)
3. **Home screen** - Feature cards and quick actions
4. **Chat works!** - Send messages, get echo responses
5. **Settings screen** - Explore different themes

<Check>
  If you see the home screen, you're all set! The app is running with mock backends.
</Check>

## Project Structure

```text theme={null}
SwiftAIBoilerplatePro/
├── SwiftAIBoilerplatePro/        # Main app
│   ├── AppShell/                  # UI screens
│   ├── Composition/               # DI container (LLMClientFactory, etc.)
│   ├── Generated/                 # Configuration.swift (from update-config.sh)
│   └── Resources/                 # Assets
├── Packages/                      # 11 reusable Swift packages + TestSupport
│   ├── Core/                      # Foundation
│   ├── Networking/                # HTTP client
│   ├── Storage/                   # SwiftData
│   ├── Auth/                      # Authentication
│   ├── Payments/                  # Subscriptions
│   ├── AI/                        # LLM client (re-exports FeatureChat)
│   ├── FeatureChat/               # Chat UI (owns LLMClient/LLMMessage)
│   ├── FeatureRating/             # In-app review prompts
│   ├── FeatureSettings/           # Settings
│   ├── Localization/              # Strings + AppError.localizedUserMessage
│   ├── DesignSystem/              # UI components (SAIGlass)
│   └── TestSupport/               # Test-only infra (URLProtocolStub), v2.2
├── Config/                        # Build configuration
│   ├── App.xcconfig               # APP_BUNDLE_ID, SWIFT_VERSION, deployment target
│   └── Secrets.xcconfig           # Your API keys
├── Boilerplate.xctestplan         # Single workspace test plan
└── supabase/                      # Backend (optional)
    └── functions/ai/              # AI proxy → OpenRouter
```

## Mock vs Production Mode

### Mock Mode (Default)

Perfect for:

* ✅ Rapid initial development
* ✅ UI testing without setup
* ✅ Exploring the codebase
* ✅ Avoiding API or subscription costs

**What's mocked:**

* Authentication (any email works)
* AI responses (echoed locally)
* Payments (simulated states)

### Production Mode

When you're ready to go live, switching to Production Mode is seamless.
This boilerplate is designed so you can move from mock data to real users and APIs in just a few setup steps, all clearly documented.

Required when you need:

* Real user authentication (via Supabase)
* Actual AI responses
* Working subscriptions and payments

<Warning>
  To complete the backend setup see [Quick Start](/pages/quickstart) or [Setup Guides](/pages/guides/supabase-setup).
</Warning>

## Verify Installation

<Steps>
  <Step title="App Builds">
    No build errors in Xcode
  </Step>

  <Step title="Tests Pass">
    Run tests with **⌘ + U**. One pass of `Boilerplate.xctestplan` runs \~598 tests across 12 package test targets + the app test suites — all should pass.
  </Step>

  <Step title="UI Works">
    Navigate through onboarding → sign in → home → chat
  </Step>
</Steps>

## Common Issues

### Dependencies Won't Resolve

**Solution:**

```bash theme={null}
# In Xcode
File → Packages → Reset Package Caches
File → Packages → Update to Latest Package Versions
```

### Missing Config File

**Error:** `Config/Secrets.xcconfig not found`

**Solution:**

```bash theme={null}
cp Config/Secrets.example.xcconfig Config/Secrets.xcconfig
```

### Build Errors

**Solution:**

```bash theme={null}
# Clean build
⌘ + Shift + K

# Or from terminal
xcodebuild clean
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="bolt" href="/pages/quickstart">
    Get to your first running app
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/pages/architecture">
    Understand the system design
  </Card>

  <Card title="Build Your App" icon="hammer" href="/pages/guides/building-your-app">
    Complete customization guide
  </Card>

  <Card title="Setup Backends" icon="server" href="/pages/guides/supabase-setup">
    Connect real services
  </Card>
</CardGroup>

## Development Tips

<Tip>
  **Using AI assistants?** Check out [CLAUDE.md](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/CLAUDE.md) for guidelines on AI-assisted development.
</Tip>

<Info>
  **Want to customize immediately?** Read the [Building Your App guide](/pages/guides/building-your-app) which includes ready-to-use LLM prompts for common tasks.
</Info>