iOS 개발자를 위한 Tuist 완벽 가이드

iOS 개발자를 위한 Tuist 완벽 가이드 

iOS 개발을 하다 보면 Xcode 프로젝트 설정이 점점 복잡해지고, 팀원이 많아질수록 설정 충돌이나 빌드 환경 불일치 문제가 발생합니다.

이런 문제를 해결하기 위해 등장한 도구가 바로 Tuist입니다.

 

Tuist란 무엇인가?

Tuist는 Xcode 프로젝트를 코드로 정의하고 자동 생성하는 CLI 도구입니다.

즉, “Xcode에서 클릭하며 설정하던 작업을 Swift 코드로 선언해두면 Tuist가 알아서 .xcodeproj 파일을 만들어주는 시스템”입니다. 

이 방식은 특히 대규모 프로젝트나 멀티 모듈 구조를 다루는 개발자들에게 필수적인 관리 방식입니다.

 

Tuist의 핵심 개념

개념설명

Project.swift	하나의 앱 혹은 프레임워크 단위 프로젝트 정의 파일
Workspace.swift	여러 프로젝트를 묶어 관리하는 워크스페이스 정의 파일
Tuist	프로젝트 정의 파일을 읽어 Xcode 프로젝트를 생성하는 CLI 도구
Target	실제 빌드 가능한 단위 (App, Framework, Tests 등)
Dependencies	타 모듈 혹은 외부 라이브러리와의 의존성 설정

 

Tuist의 주요 장점

1. 반복 작업 자동화

• Info.plist, Scheme, Build Settings 등 모든 설정을 Swift 코드로 관리
• Git을 통해 변경 이력 추적 가능

2. 모듈화에 최적화

• Feature, Core, Shared 등의 모듈을 독립적으로 구성 가능
• tuist generate 명령으로 전체 워크스페이스 자동 생성

3. 협업 충돌 최소화

• .xcodeproj 대신 Swift 코드로 관리하여 충돌 최소화

4. 빌드 속도 향상

• 모듈 단위 빌드로 불필요한 빌드 최소화

5. CI/CD 통합 용이

• GitHub Actions, Jenkins 등과 연동하여 일관된 환경 재현 가능

설치 및 기본 사용법

설치(mise 또는 brew 사용해서 설치)

// 1. mise 사용해서 설치하는 방법
// mise 설치
curl https://mise.run | sh
// 환경설정 등록
echo 'export PATH="$HOME/.local/bin:$HOME/.mise/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
source ~/.zshrc

// tuist 설치
mise install tuist 
// tuist 버젼 전역 등록
mise use -g tuist@4.103.0


// 2. HomeBrew 사용해서 설치하는 방법
// HomeBrew 설치
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

// tuist 설치
brew tap tuist/tuist
brew install tuist

프로젝트 초기화

tuist init --platform ios

기본 폴더 구조 예시

.
├── Project.swift
├── Targets/
│   └── App/
│       ├── Sources/
│       ├── Resources/
│       └── Info.plist
└── Tuist/
    └── Config.swift

Project.swift 기본 구조 예시

import ProjectDescription

let project = Project(
    name: "MyApp",
    targets: [
        Target(
            name: "MyApp",
            platform: .iOS,
            product: .app,
            bundleId: "com.example.myapp",
            deploymentTarget: .iOS(targetVersion: "17.0", devices: [.iphone]),
            infoPlist: .file(path: "Targets/App/Info.plist"),
            sources: ["Targets/App/Sources/**"],
            resources: ["Targets/App/Resources/**"],
            dependencies: [
                .target(name: "MyFeature"),
                .external(name: "Alamofire")
            ]
        )
    ]
)

---

Workspace.swift (멀티 모듈 구성 예시)

import ProjectDescription

let workspace = Workspace(
    name: "MyAppWorkspace",
    projects: [
        "Projects/App",
        "Projects/Feature/**",
        "Projects/Core/**"
    ]
)

Dependencies.swift (Swift Package Manager 연동)

import ProjectDescription

let dependencies = Dependencies(
    swiftPackageManager: .init(
        [
            .remote(
                url: "https://github.com/Alamofire/Alamofire.git",
                requirement: .upToNextMajor(from: "5.6.0")
            )
        ]
    ),
    platforms: [.iOS]
)

패키지 다운로드 명령:
bash
tuist fetch

Tuist 주요 명령어 정리

명령어설명

tuist init	새 프로젝트 초기화
tuist edit	Tuist 설정용 Xcode 프로젝트 열기
tuist generate	Xcode 프로젝트(.xcodeproj) 생성
tuist fetch	SPM Dependencies 다운로드
tuist clean	캐시 및 빌드 아티팩트 정리
tuist graph	의존성 그래프 시각화 (Mermaid 지원)

모듈 구조 예시

Projects/
 ├── App/
 │    └── Project.swift
 ├── Core/
 │    ├── Network/
 │    ├── Database/
 │    └── UI/
 └── Features/
      ├── Home/
      ├── Profile/
      └── Settings/

협업 환경에서의 Tuist 활용 예시

• 개발자 A: Features/Home 모듈 수정
• 개발자 B: Features/Profile 모듈 수정
  → 서로 다른 모듈에서 작업하므로 충돌이 거의 없음
  → tuist generate 명령으로 동일한 개발 환경 재현 가능

CI/CD 통합 예시 (GitHub Actions)

name: iOS CI

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Tuist
        run: curl -Ls https://install.tuist.io | bash
      - name: Generate Xcode Project
        run: tuist generate
      - name: Build
        run: xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -sdk iphonesimulator

실무 활용 팁

1. 각 모듈마다 별도의 Unit Test Target 생성 → 테스트 속도 향상
2. Info.plist 최소화 및 공통 설정은 Config.swift로 통합 관리
3. Team ID, Bundle Prefix 등은 Tuist/Config.swift에서 정의
4. tuist scaffold 기능으로 템플릿 기반 빠른 모듈 생성 가능

정리 및 결론

Tuist는 대규모 iOS 프로젝트의 생산성, 협업 효율, 유지보수성을 크게 높여주는 도구입니다.

프로젝트를 코드로 정의함으로써

- 설정 충돌 최소화

- 일관된 환경 구성

- 자동화된 빌드 파이프라인 

을 손쉽게 구현할 수 있습니다.

앞으로 SwiftUI, TCA, Modular Architecture를 함께 사용할 때 Tuist는 더욱 강력한 조합이 될 것입니다.