# Converting a Web App to iOS / iPadOS / macOS

Step-by-step instructions for using the XCode-Claude-Workflow to convert any web-based project (React, HTML5, Vue, vanilla JS, etc.) into a native SwiftUI app.

## Prerequisites

- **Xcode 16.3+** installed
- **xcodegen** installed (`brew install xcodegen`)
- **Claude Code** running in your terminal or IDE
- A **Forgejo/GitHub account** for the new repo
- The **source project** folder on your local machine

## Steps

### 1. Create a new repo for the app

On your Forgejo (or GitHub) instance, create an empty repo. Use a descriptive name:

```
MyApp-iOS-iPadOS-MacOS
```

Clone it locally:

```bash
cd ~/Documents/FORGEJO
git clone https://git.istratai.cloud/aj/MyApp-iOS-iPadOS-MacOS.git
cd MyApp-iOS-iPadOS-MacOS
```

### 2. Copy the workflow prompt

```bash
cp ~/Documents/FORGEJO/XCode-Claude-Workflow/PROMPT.md .
```

### 3. Open Claude Code in the new repo

```bash
claude
```

Or open the folder in VS Code / Cursor with Claude Code extension.

### 4. Start the workflow

Tell Claude:

```
@PROMPT.md execute this prompt
```

Claude will ask for the target platform (iOS, macOS, etc.) and then ask you to point to the source code folder. Provide the full path:

```
/Users/macpro2019/Documents/FORGEJO/my-web-app/
```

### 5. Follow the 8 phases

Claude will walk you through each phase and ask for approval before proceeding:

| Phase | What Happens | Your Role |
|-------|-------------|-----------|
| **0 — Audit** | Reads every file, produces audit report | Review and approve |
| **1 — Architecture** | Proposes MVVM/TCA, scaffolds Xcode project | Choose architecture, confirm |
| **2 — Features** | Implements one feature at a time with tests | Test in Simulator after each |
| **3 — Persistence** | Adds SwiftData, auto-save, preferences | Verify save/resume works |
| **4 — Accessibility** | VoiceOver, Dynamic Type, localization | Test with VoiceOver on |
| **5 — Quality** | Static analysis, 70%+ test coverage | Review test results |
| **6 — App Store** | Privacy manifest, icons, metadata | Provide App Store details |
| **7 — Documentation** | SETUP.md, CHANGELOG.md, ARCHITECTURE.md | Review and commit |

### 6. Test on simulators

```bash
# Generate Xcode project
xcodegen generate

# Build and run on iPhone
xcodebuild build -project MyApp.xcodeproj -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 16'

# Build and run on iPad
xcodebuild build -project MyApp.xcodeproj -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPad Pro 11-inch (M4)'

# Build and run on Mac
xcodebuild build -project MyApp.xcodeproj -scheme MyApp \
  -destination 'platform=macOS' CODE_SIGN_IDENTITY=- CODE_SIGNING_REQUIRED=NO
```

Or just open the `.xcodeproj` in Xcode and press **Cmd+R**.

### 7. Commit and push

```bash
git add -A
git commit -m "feat: MyApp v1.0.0 — native SwiftUI for iOS, iPadOS, macOS"
git push origin main
```

## Tips

- **Don't rush** — approve each phase before moving on. Quality > speed.
- **Test on device** — Simulator is good but real devices catch touch/scroll issues.
- **Screenshot everything** — share screenshots with Claude when something looks off. It will fix the layout.
- **Landscape matters** — always test both orientations on iPhone.
- **Start a new game/session** — if Claude's context gets too long, start a new conversation and point it to the repo + PROMPT.md again. It will pick up where you left off.
- **Keep PROMPT.md in the app repo** — it serves as documentation of the conversion methodology used.

## Template repo

The workflow template lives at:
```
https://git.istratai.cloud/aj/XCode-Claude-Workflow
```

## Example project

SoliCards (solitaire card game) was converted using this exact workflow:
```
Source:  https://git.istratai.cloud/aj/game-SoliCards
Result:  https://git.istratai.cloud/aj/SoliCards-iOS-iPadOS-MacOS
```