
swiftui-smart-build
Auto-install iOS apps after xcodebuild + SwiftUI best practices
- version
- 2.7.1
- GitHub stars
- 7
Install
/plugin install swiftui-smart-build@leepokaiRun it inside Claude Code after adding the marketplace with /plugin marketplace add leepokai/swiftui-smart-build.
Contents
Discovered from sourceSkills 1
Smart Build Workflow
Automated build workflow for iOS development with syntax checking, auto-formatting, and instant deployment.
Quick Start
1. Check Preferences (REQUIRED FIRST STEP)
find . -maxdepth 1 -name ".smart-build.json"
⚠️ CRITICAL: If no file is found in the project root:
- You MUST run the setup flow in
@../../references/setup-flow.mdBEFORE proceeding - DO NOT skip this step - build will fail without proper preferences
- DO NOT guess or hardcode values - follow the interactive setup
If .smart-build.json exists → Extract scheme and udid, then proceed to step 2
2. LSP Quick Check (Optional, Recommended for Large Changes)
Use LSP to verify types BEFORE building - faster than waiting for xcodebuild to fail.
After adding/modifying functions:
LSP hover on new function signature → verify return type resolves
After renaming symbols:
LSP findReferences on renamed symbol → verify all call sites updated
After importing new modules:
LSP hover on imported type → verify module is available
Example:
// You just added this function
func fetchUser(id: String) -> User { ... }
LSP hover at "fetchUser" → Returns "(String) -> User" ✓ types correct
LSP hover at "User" → Returns "struct User" ✓ type exists
If LSP returns error or empty → fix before building.
3. Build
xcodebuild \
-scheme "SAVED_SCHEME" \
-destination "platform=iOS Simulator,id=SAVED_UDID" \
build
4. Auto-Deploy (Hook)
When build succeeds, hook automatically:
- Boots target simulator (if needed)
- Installs app
- Launches app
Automatic Hooks
Swift Lint Check (on Edit/Write .swift)
swiftc -parse- instant syntax checkswiftformat- auto-fix style (when syntax OK)
Auto-Install (on xcodebuild success)
- Extracts UDID from destination (PRIORITY 0)
- Boots simulator if needed
- Installs and launches app
Simulator Selection Priority:
PRIORITY 0: UDID from destination (id=XXXX)
PRIORITY 1: Booted simulator matching name
PRIORITY 2: Any booted simulator
PRIORITY 3: Available simulator matching name
PRIORITY 4: First available iPhone
Preferences Validator (on Edit/Write .smart-build.json)
Validates JSON syntax and required fields.
Commands
| Command | Description |
|---|---|
/simulator-build-boot-install | Build with saved preferences |
/simulator-build-boot-install revise | Revise settings (runs setup flow) |
/device-build-boot-install | Build for physical device |
Workflow Summary
┌─────────────────────────────────────────────────┐
│ During Editing (Automatic) │
│ Edit .swift → swiftc -parse → swiftformat │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Pre-Build (Optional LSP Check) │
│ LSP hover → verify types │
│ LSP findReferences → verify no broken refs │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ Build & Deploy (Automatic) │
│ xcodebuild → Boot → Install → Launch │
└─────────────────────────────────────────────────┘
Troubleshooting (Only When User Requests)
Do NOT proactively run troubleshooting steps. Only use when user explicitly asks to debug or check logs.
# Check logs
cat /tmp/swiftui-smart-build/swift-lint-check.log
cat /tmp/swiftui-smart-build/post-build-install.log
cat /tmp/swiftui-smart-build/validate-preferences.log
| Problem | Solution |
|---|---|
| Hook not triggering | which jq - install if missing |
| Wrong simulator | /simulator-build-boot-install revise |
| No install after build | Check post-build-install.log |
Commands 2
Device: Build → Install → Launch
Build for physical iOS device with saved preferences.
Prerequisites
- Device connected via USB or Wi-Fi
- Device trusted on this Mac
- Signing configured in Xcode (Team + Bundle ID)
Workflow
Step 1: Check for saved preferences
find . -maxdepth 1 -name ".smart-build.json"
If no file is found OR no device section in preferences:
→ Run the setup flow in @../references/setup-flow.md (device only needs scheme selection)
If device preferences exist: → Go to Step 2
Step 2: Build with saved preferences
Read preferences from .smart-build.json in the project root and run:
xcodebuild \
-scheme "<SAVED_SCHEME>" \
-destination "generic/platform=iOS" \
-allowProvisioningUpdates \
build
# e.g., xcodebuild -scheme "App-DebugRemote" -destination "generic/platform=iOS" -allowProvisioningUpdates build
What Happens After Build
When build succeeds, the post-build hook automatically:
- Detects connected device
- Installs the app via
devicectl - Launches the app
Do NOT run install or launch commands yourself. The post-build hook handles everything automatically. Your job ends after a successful xcodebuild — never attempt to install or launch the app manually.
Check Connected Devices
xcrun devicectl list devices
Troubleshooting (Only When User Requests)
Do NOT proactively run troubleshooting steps. Only use when user explicitly asks to debug.
| Issue | Solution |
|---|---|
| No device found | Check USB connection, trust the Mac on device |
| Signing error | Open Xcode, configure Team in Signing & Capabilities |
| Install fails | Ensure device is unlocked, check provisioning profile |
Simulator: Build → Boot → Install
Build for iOS Simulator with saved preferences.
Workflow
Step 1: Check for saved preferences
find . -maxdepth 1 -name ".smart-build.json"
If no file is found OR no simulator section in preferences:
→ Run the setup flow in @../references/setup-flow.md
If simulator preferences exist: → Go to Step 2
Step 2: Build with saved preferences
Read preferences from .smart-build.json in the project root and run:
xcodebuild \
-scheme "<SAVED_SCHEME>" \
-destination "platform=iOS Simulator,id=<SAVED_UDID>" \
build
# e.g., xcodebuild -scheme "App-DebugLocal" -destination "platform=iOS Simulator,id=24A2580F-BABB-49D2-91EA-2B14498A4246" build
What Happens After Build
When build succeeds, the post-build hook automatically:
- Boots the simulator (if not running)
- Installs the app
- Launches the app
Do NOT run boot, install, or launch commands yourself. The post-build hook handles everything automatically. Your job ends after a successful xcodebuild — never attempt to boot the simulator, install, or launch the app manually.
Hooks 1
Sponsors
Details
- Marketplace
- leepokai/swiftui-smart-build
- Source
- plugin
- Author
- leepokai
- Category
- Development
- License
- MIT
- Keywords
- swift, swiftui, xcode, ios, build, simulator, deploy, best-practices