Migrates existing Xcode projects to Tuist generated workspaces with build and run validation, external dependency mapping, and migration checklists. Use when adopting Tuist for an existing app or converting a hand-edited Xcode project to generated projects.
Tuist.swift, Project.swift, and Tuist/Package.swift..xcconfig files and wire them in Project.swift.tuist generate --no-open then xcodebuild build.Project.swift and Tuist.swiftTuist/Package.swift for external dependencies.xcconfig files (optional but recommended)Start by proving the current project builds and runs. Capture the command you use so the generated workspace can be validated the same way.
xcodebuild build \
-project App.xcodeproj \
-scheme App \
-configuration Debug \
-destination "generic/platform=iOS Simulator" \
-derivedDataPath DerivedDataBaseline
List every target and its role. Extract build settings into .xcconfig files when they are large or shared across targets. Keep deployment targets and bundle identifiers identical to the original project to avoid runtime surprises.
Create the manifests and keep them minimal and close to the existing project.
Tuist.swift: enable generation options you need and keep them explicit.Project.swift: define targets, sources, resources, scripts, and dependencies.Tuist/Package.swift: list external dependencies and map product types.Use .external for third-party dependencies to keep the graph consistent.
Be precise here. Small mistakes often cause large failures later.
.intentdefinition files belong in sources, not resources..xcstrings should remain the primary localization source. Avoid double-including .strings or .stringsdict from overlapping globs..folderReference for bundles like Settings.bundle..process("Resources").tuist install
tuist generate --no-open
xcodebuild build \
-workspace App.xcworkspace \
-scheme App \
-configuration Debug \
-destination "generic/platform=iOS Simulator" \
-derivedDataPath DerivedDataTuist
Common fixes you will likely need:
.sdk(name: ..., type: .framework)..process("Resources") and Bundle.module usage.PackageSettings or vendor a local package.A build is not enough; launch the app on a simulator.
xcrun simctl boot "iPhone 17 Pro"
xcrun simctl install booted DerivedDataTuist/Build/Products/Debug-iphonesimulator/App.app
xcrun simctl launch booted com.example.app
.xcstrings colliding with .strings globs.-ObjC to OTHER_LDFLAGS or -force_load for the library that defines the category.Project.swift and why.external