tuist

name	tuist
description	Guides day-to-day work in Tuist-generated Xcode workspaces, including generation, build and test commands, TMA module conventions, and troubleshooting. Use when working with Tuist manifests, generating projects, or building/testing with xcodebuild.
metadata	{"author":"habitus","version":"1.0"}

Using Tuist in this project

Quick start

# Install dependencies (run when Package.swift or dependency graph changes)
tuist install

# Generate workspace without opening Xcode
tuist generate --no-open

# Generate only specific targets or tags
tuist generate tag:feature:payments
tuist generate PaymentsUI PaymentsTests

Build with xcodebuild

Use xcodebuild build against the generated workspace and scheme:

xcodebuild build \
  -workspace App.xcworkspace \
  -scheme App \
  -destination "generic/platform=iOS Simulator"

Test with xcodebuild

Prefer xcodebuild test over tuist test — tuist test regenerates the project on each invocation, which slows down iteration.

To optimize test run time:

• Use --only-testing to run only the specific test suite or case you're working on
• Pick the scheme with the fewest compilation targets that still includes your test target

# Run a specific test suite
xcodebuild test \
  -workspace App.xcworkspace \
  -scheme AppTests \
  -only-testing AppTests/MyTestSuite

# Run a single test case
xcodebuild test \
  -workspace App.xcworkspace \
  -scheme AppTests \
  -only-testing AppTests/MyTestSuite/testMyFunction

TMA module structure

Each feature module can have up to 5 targets:

Target	Dependencies	Content
Feature	FeatureInterface	Source code and resources
FeatureInterface	—	Public interface and models
FeatureTests	Feature, FeatureTesting	Unit and integration tests
FeatureTesting	FeatureInterface	Testing data and mocks
FeatureExample	FeatureTesting, Feature	Example app for trying the feature

Key rules:

• Modules depend on other modules via their Interface target only
• This decouples implementations and speeds up clean builds
• Apps wire the implementation graph at runtime via dependency injection

Project definition conventions

• Prefer buildableFolders over sources/resources globs — they stay in sync with the filesystem without regeneration
• Use target tags for focused generation: tag:team:*, tag:feature:*, tag:layer:*
• Align build configurations between the project and external dependencies using PackageSettings

Directory structure

Tuist.swift                          # Shared Tuist configuration
Tuist/
  Package.swift                      # Swift Package dependencies
  ProjectDescriptionHelpers/         # Shared Swift code for manifests
Projects/
  App/
    Project.swift                    # App target manifest
  Feature/
    Project.swift                    # Feature module manifest
Workspace.swift                      # Workspace definition (optional)

Troubleshooting

• Generation fails with missing products: Run tuist install first, then retry tuist generate
• Static side effects warnings: Adjust product types deliberately. Prefer static products when they don't introduce side effects. Use Target.product for local targets, PackageSettings(productTypes:) for external ones
• Objective-C dependency crashes: Add -ObjC or -force_load via OTHER_LDFLAGS on consuming targets

References

• Full docs: https://docs.tuist.dev/en/guides/features/projects
• TMA architecture: https://docs.tuist.dev/en/guides/features/projects/tma-architecture
• Directory structure: https://docs.tuist.dev/en/guides/features/projects/directory-structure
• Dependencies: https://docs.tuist.dev/en/guides/features/projects/dependencies
• Manifests: https://docs.tuist.dev/en/guides/features/projects/manifests