Tuist

Core Rules

• Always run tuist install before tuist generate if the project uses external (remote) dependencies.
• Always pass --no-open to tuist generate when running in an agent or CI environment.
• Use buildableFolders on targets to avoid regenerating the project when files are added or removed.
• Target Swift 6.0+ with SWIFT_STRICT_CONCURRENCY: "complete".
• Disable code signing in CI/agent builds with CODE_SIGN_IDENTITY: "".

Target Declaration

.target(
    name: "MyApp",
    destinations: [.iPhone],
    product: .app,
    bundleId: "com.example.app",
    deploymentTargets: .iOS("18.0"),
    infoPlist: .extendingDefault(with: [
        "CFBundleDisplayName": "My App",
        "UILaunchScreen": [:],
    ]),
    sources: ["Sources/**"],
    resources: ["Resources/**"],
    buildableFolders: ["Sources/", "Resources/"],
    dependencies: [
        .target(name: "SharedKit"),
    ],
    settings: .settings(
        base: [
            "SWIFT_VERSION": "6.0",
            "SWIFT_STRICT_CONCURRENCY": "complete",
        ]
    )
)

Dependency Patterns (5 Types)

// 1. Internal target in same Project.swift
.target(name: "SharedKit")

// 2. Local SPM package (declared in project packages: [])
.package(product: "CPCore")

// 3. External/remote SPM package (declared in Tuist.swift)
.external(name: "Alamofire")

// 4. Apple SDK framework
.sdk(name: "HealthKit", type: .framework)

// 5. Local binary / XCFramework
.xcframework(path: "Frameworks/Analytics.xcframework")

Modular Architecture

Feature modules depend DOWN on shared kit, NEVER sideways on other features:

App → FeatureA, FeatureB, SharedKit
FeatureA → SharedKit (NEVER → FeatureB)
FeatureB → SharedKit (NEVER → FeatureA)
SharedKit → (no internal deps)

Common LLM Mistakes

1. Forgetting tuist install — external deps won't resolve without it.
2. Using .package(product:) for internal targets — use .target(name:) instead.
3. Using .target(name:) for local SPM packages — use .package(product:) and declare the package in packages: [.local(path: "...")].
4. Missing --no-open — Xcode launches in headless CI/agent environments, causing hangs.
5. Signing in CI — always set CODE_SIGN_IDENTITY: "" for CI builds.
6. Wrong deployment target API — use .iOS("18.0") for single-platform, .multiplatform(iOS: "18.0", watchOS: "11.0") for multi-platform targets.
7. Forgetting entitlements — use .dictionary([...]) inline, not a file reference, for agent-generated targets.