abanoub-ashraf/ios-tuist

Tuist Expert

You are an expert in Tuist for iOS project management. When this skill activates, help set up and manage Tuist-based projects.

Why Tuist?

| Problem | Tuist Solution | |---------|---------------| | .xcodeproj merge conflicts | Generate projects, don't commit them | | Inconsistent project settings | Define in Swift, share across targets | | Slow Xcode indexing | Focused projects with only needed targets | | Complex dependency graphs | Declarative Swift manifests | | Onboarding new developers | tuist generate and you're ready |

Installation

# Install via Homebrew
brew install tuist

# Or install via mise (recommended for teams)
mise install tuist

# Verify installation
tuist version

Project Structure

MyApp/
├── Tuist/
│   ├── Config.swift           # Global configuration
│   ├── ProjectDescriptionHelpers/
│   │   ├── Project+Templates.swift
│   │   └── Target+Templates.swift
│   └── Dependencies.swift     # External dependencies
│
├── Projects/
│   ├── App/
│   │   └── Project.swift      # Main app project
│   ├── Features/
│   │   ├── Home/
│   │   │   └── Project.swift
│   │   └── Profile/
│   │       └── Project.swift
│   └── Core/
│       ├── Networking/
│       │   └── Project.swift
│       └── DesignSystem/
│           └── Project.swift
│
├── Workspace.swift            # Root workspace
└── .gitignore                 # Ignore *.xcodeproj, *.xcworkspace

Core Manifests

Workspace.swift

import ProjectDescription

let workspace = Workspace(
    name: "MyApp",
    projects: [
        "Projects/App",
        "Projects/Features/**",
        "Projects/Core/**"
    ],
    schemes: [
        .scheme(
            name: "MyApp-Development",
            shared: true,
            buildAction: .buildAction(targets: [.project(path: "Projects/App", target: "MyApp")]),
            runAction: .runAction(configuration: .debug),
            archiveAction: .archiveAction(configuration: .release),
            profileAction: .profileAction(configuration: .release),
            analyzeAction: .analyzeAction(configuration: .debug)
        )
    ],
    additionalFiles: [
        "README.md",
        ".swiftlint.yml"
    ]
)

Project.swift (App)

import ProjectDescription
import ProjectDescriptionHelpers

let project = Project(
    name: "MyApp",
    organizationName: "Company",
    options: .options(
        automaticSchemesOptions: .disabled,
        disableBundleAccessors: false,
        disableSynthesizedResourceAccessors: false
    ),
    settings: .settings(
        base: [
            "DEVELOPMENT_TEAM": "XXXXXXXXXX",
            "MARKETING_VERSION": "1.0.0",
            "CURRENT_PROJECT_VERSION": "1"
        ],
        configurations: [
            .debug(name: "Debug", settings: [:], xcconfig: nil),
            .release(name: "Release", settings: [:], xcconfig: nil)
        ]
    ),
    targets: [
        .target(
            name: "MyApp",
            destinations: .iOS,
            product: .app,
            bundleId: "com.company.myapp",
            deploymentTargets: .iOS("17.0"),
            infoPlist: .extendingDefault(with: [
                "CFBundleDisplayName": "My App",
                "UILaunchScreen": [
                    "UIColorName": "LaunchBackground"
                ],
                "NSFaceIDUsageDescription": "Authenticate securely"
            ]),
            sources: ["Sources/**"],
            resources: ["Resources/**"],
            dependencies: [
                .project(target: "HomeFeature", path: "../Features/Home"),
                .project(target: "ProfileFeature", path: "../Features/Profile"),
                .project(target: "DesignSystem", path: "../Core/DesignSystem"),
                .project(target: "Networking", path: "../Core/Networking"),
                .external(name: "ComposableArchitecture")
            ]
        ),
        .target(
            name: "MyAppTests",
            destinations: .iOS,
            product: .unitTests,
            bundleId: "com.company.myapp.tests",
            sources: ["Tests/**"],
            dependencies: [
                .target(name: "MyApp")
            ]
        )
    ],
    schemes: [
        .scheme(
            name: "MyApp",
            shared: true,
            buildAction: .buildAction(targets: [.init(stringLiteral: "MyApp")]),
            testAction: .targets([.init(stringLiteral: "MyAppTests")]),
            runAction: .runAction(configuration: .debug)
        )
    ]
)

Project.swift (Feature Module)

import ProjectDescription
import ProjectDescriptionHelpers

let project = Project(
    name: "HomeFeature",
    targets: [
        // Interface target
        .target(
            name: "HomeFeatureInterface",
            destinations: .iOS,
            product: .framework,
            bundleId: "com.company.homefeature.interface",
            deploymentTargets: .iOS("17.0"),
            sources: ["Interface/**"],
            dependencies: [
                .project(target: "Models", path: "../../Core/Models")
            ]
        ),
        // Implementation target
        .target(
            name: "HomeFeature",
            destinations: .iOS,
            product: .framework,
            bundleId: "com.company.homefeature",
            deploymentTargets: .iOS("17.0"),
            sources: ["Sources/**"],
            resources: ["Resources/**"],
            dependencies: [
                .target(name: "HomeFeatureInterface"),
                .project(target: "DesignSystem", path: "../../Core/DesignSystem"),
                .project(target: "Networking", path: "../../Core/Networking")
            ]
        ),
        // Tests
        .target(
            name: "HomeFeatureTests",
            destinations: .iOS,
            product: .unitTests,
            bundleId: "com.company.homefeature.tests",
            sources: ["Tests/**"],
            dependencies: [
                .target(name: "HomeFeature")
            ]
        )
    ]
)

Config.swift (Global Settings)

import ProjectDescription

let config = Config(
    compatibleXcodeVersions: .upToNextMajor("15.0"),
    swiftVersion: "5.9",
    generationOptions: .options(
        enforceExplicitDependencies: true,
        resolveDependenciesWithSystemScm: false,
        disablePackageVersionLocking: false
    )
)

Dependencies.swift (External)

import ProjectDescription

let dependencies = Dependencies(
    swiftPackageManager: SwiftPackageManagerDependencies(
        [
            .remote(
                url: "https://github.com/pointfreeco/swift-composable-architecture",
                requirement: .upToNextMajor(from: "1.5.0")
            ),
            .remote(
                url: "https://github.com/pointfreeco/swift-dependencies",
                requirement: .upToNextMajor(from: "1.0.0")
            ),
            .remote(
                url: "https://github.com/onevcat/Kingfisher",
                requirement: .upToNextMajor(from: "7.0.0")
            )
        ],
        productTypes: [
            "ComposableArchitecture": .framework,
            "Dependencies": .framework
        ]
    ),
    platforms: [.iOS]
)

ProjectDescriptionHelpers

Project+Templates.swift

import ProjectDescription

public extension Project {
    static func feature(
        name: String,
        dependencies: [TargetDependency] = []
    ) -> Project {
        Project(
            name: name,
            targets: [
                .target(
                    name: "\(name)Interface",
                    destinations: .iOS,
                    product: .framework,
                    bundleId: "com.company.\(name.lowercased()).interface",
                    deploymentTargets: .iOS("17.0"),
                    sources: ["Interface/**"]
                ),
                .target(
                    name: name,
                    destinations: .iOS,
                    product: .framework,
                    bundleId: "com.company.\(name.lowercased())",
                    deploymentTargets: .iOS("17.0"),
                    sources: ["Sources/**"],
                    resources: ["Resources/**"],
                    dependencies: [.target(name: "\(name)Interface")] + dependencies
                ),
                .target(
                    name: "\(name)Tests",
                    destinations: .iOS,
                    product: .unitTests,
                    bundleId: "com.company.\(name.lowercased()).tests",
                    sources: ["Tests/**"],
                    dependencies: [.target(name: name)]
                )
            ]
        )
    }

    static func core(
        name: String,
        dependencies: [TargetDependency] = []
    ) -> Project {
        Project(
            name: name,
            targets: [
                .target(
                    name: name,
                    destinations: .iOS,
                    product: .framework,
                    bundleId: "com.company.\(name.lowercased())",
                    deploymentTargets: .iOS("17.0"),
                    sources: ["Sources/**"],
                    resources: ["Resources/**"],
                    dependencies: dependencies
                ),
                .target(
                    name: "\(name)Tests",
                    destinations: .iOS,
                    product: .unitTests,
                    bundleId: "com.company.\(name.lowercased()).tests",
                    sources: ["Tests/**"],
                    dependencies: [.target(name: name)]
                )
            ]
        )
    }
}

Using Templates

// Projects/Features/Home/Project.swift
import ProjectDescription
import ProjectDescriptionHelpers

let project = Project.feature(
    name: "HomeFeature",
    dependencies: [
        .project(target: "DesignSystem", path: "../../Core/DesignSystem"),
        .project(target: "Networking", path: "../../Core/Networking")
    ]
)

Common Commands

# Generate Xcode project
tuist generate

# Generate and open Xcode
tuist generate --open

# Edit Tuist manifests in Xcode
tuist edit

# Fetch external dependencies
tuist fetch

# Clean generated files
tuist clean

# Build from CLI
tuist build

# Run tests from CLI
tuist test

# Graph dependencies
tuist graph

# Graph specific target
tuist graph MyApp --format png

# Cache frameworks (speed up generation)
tuist cache

# Scaffold new module
tuist scaffold feature --name Profile

Scaffold Templates

Template Definition

// Tuist/Templates/feature/feature.swift
import ProjectDescription

let nameAttribute: Template.Attribute = .required("name")

let template = Template(
    description: "Creates a new feature module",
    attributes: [nameAttribute],
    items: [
        .file(
            path: "Projects/Features/\(nameAttribute)/Project.swift",
            templatePath: "project.stencil"
        ),
        .file(
            path: "Projects/Features/\(nameAttribute)/Sources/\(nameAttribute)View.swift",
            templatePath: "view.stencil"
        ),
        .file(
            path: "Projects/Features/\(nameAttribute)/Interface/\(nameAttribute)API.swift",
            templatePath: "interface.stencil"
        ),
        .directory(
            path: "Projects/Features/\(nameAttribute)/Resources",
            sourcePath: "resources"
        )
    ]
)

Stencil Template

// Tuist/Templates/feature/project.stencil
import ProjectDescription
import ProjectDescriptionHelpers

let project = Project.feature(
    name: "{{ name }}Feature",
    dependencies: [
        .project(target: "DesignSystem", path: "../../Core/DesignSystem")
    ]
)

Using Scaffold

tuist scaffold feature --name Profile

Caching for Speed

# Cache all cacheable targets
tuist cache

# Cache specific targets
tuist cache HomeFeature ProfileFeature

# Use cached frameworks
tuist generate  # Automatically uses cache

# Clear cache
tuist cache --clean

CI/CD Integration

GitHub Actions

name: iOS CI

on: [push, pull_request]

jobs:
  build:
    runs-on: macos-14

    steps:
      - uses: actions/checkout@v4

      - name: Install Tuist
        run: brew install tuist

      - name: Fetch Dependencies
        run: tuist fetch

      - name: Generate Project
        run: tuist generate --no-open

      - name: Build
        run: tuist build -- -configuration Debug

      - name: Test
        run: tuist test

.gitignore for Tuist

# Tuist managed
*.xcodeproj
*.xcworkspace
Derived/

# Keep Tuist cache locally only
.tuist-cache/

# Dependencies
Tuist/Dependencies/

Best Practices

1. Never commit .xcodeproj - Generate fresh each time
2. Use helpers - DRY up common patterns
3. Keep manifests simple - Extract complexity to helpers
4. Cache in CI - Speed up builds significantly
5. Use scaffold - Consistent module creation
6. Enforce explicit dependencies - No implicit linking
7. Graph regularly - Visualize and validate structure