# Tuist Best Practices

> Best practices for Tuist manifests, ProjectDescriptionHelpers, caching, and iOS project workflows.

- Skill: `vril-labs/tuist-best-practices` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add vril-labs/tuist-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vril-labs/tuist-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: VRIL-LABS (https://skillmd.com/u/vril-labs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vril-labs/tuist-best-practices

---


# 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)