---
name: tuist-best-practices
description: Best practices for Tuist manifests, ProjectDescriptionHelpers, caching, and iOS project workflows.
metadata:
  short-description: Tuist best practices for iOS projects
---

# Tuist Best Practices

## When to use

- editing Tuist manifests or adding targets
- updating project structure or shared helpers
- generating Xcode projects or debugging Tuist behavior

## Repo layout

- root config in `Tuist.swift`
- shared helpers in `Tuist/ProjectDescriptionHelpers`
- iOS manifest in `Project.swift` (often under `ios/` but not required)
- prefer repo-provided task runner (`just`, `make`, etc.) for generate/build/test/open
- if using `tuist xcodebuild`, keep subcommand first to avoid argument reorder issues

## Manifests

- `Project.swift`: root variable should be `let project = Project(...)`
- `Workspace.swift` optional; Tuist auto-generates workspace with project + dependencies
- `Tuist.swift` recommended; Tuist walks up dirs to find it, so running from `ios/` still uses root config

## Code sharing

- place helpers in `Tuist/ProjectDescriptionHelpers`
- import with `import ProjectDescriptionHelpers` in manifests
- helpers available in `Project.swift`, `Workspace.swift`, and `Package.swift` (behind `#TUIST`)

## Caching

- `tuist cache` builds binaries; `tuist generate/test` use binary cache by default when available
- opt out with `--no-binary-cache`
- binary cache is for dev/test, not release builds

## Change workflow

- add targets/settings in `Project.swift` using helpers
- after adding files or project changes: run repo generate task (e.g. `just generate`)
- avoid running `xcodebuild` directly

## References

- Tuist docs: manifests, directory structure, code sharing, module cache, config (docs.tuist.dev)