playbooks

home / skills / derklinke / codex-config / tuist-best-practices

tuist-best-practices skill

/skills/tuist-best-practices

This skill helps you implement Tuist best practices for manifests, helpers, and caching to streamline iOS project workflows.

npx playbooks add skill derklinke/codex-config --skill tuist-best-practices

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.7 KB
---
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)

Overview

This skill captures practical best practices for working with Tuist manifests, ProjectDescriptionHelpers, caching, and common iOS project workflows. It focuses on repository layout, safe manifest patterns, efficient caching, and a repeatable change workflow to keep projects consistent and maintainable.

How this skill works

The skill inspects recommended file organization and naming conventions for Tuist manifests and shared helper code. It describes how to use the binary cache, when to opt out, and how to run generation and build tasks through repo-provided scripts. It also outlines where helpers should live and how to import and use them in manifests.

When to use it

  • Editing Tuist manifests or adding new targets to a project
  • Refactoring project structure or centralizing configuration in helpers
  • Generating Xcode projects or troubleshooting Tuist behavior
  • Configuring or troubleshooting Tuist binary cache usage
  • Onboarding contributors to a standardized Tuist workflow

Best practices

  • Keep a single root Tuist.swift for repo-wide configuration; Tuist will be discovered from subfolders
  • Place shared manifest helpers under Tuist/ProjectDescriptionHelpers and import them with import ProjectDescriptionHelpers
  • Name the project root variable consistently (e.g., let project = Project(...)) to avoid confusion
  • Prefer repo-provided task runners (just, make, etc.) for generate/build/test/open to ensure consistent flags and ordering
  • Use tuist cache for faster dev/test iteration, but opt out with --no-binary-cache for release workflows or when building locally from source

Example use cases

  • Add a new app target and reuse shared target settings via a helper in Tuist/ProjectDescriptionHelpers
  • Run the repo generate task (just generate) after adding files to ensure Xcode project is up to date
  • Enable tuist cache to speed up CI and local development, falling back to --no-binary-cache when debugging build issues
  • Keep Workspace.swift optional and let Tuist auto-generate a workspace from projects and dependencies
  • Use tuist xcodebuild with the subcommand first to avoid argument reordering problems

FAQ

Where should I put shared helper code for manifests?

Put helpers in Tuist/ProjectDescriptionHelpers and import them in manifests with import ProjectDescriptionHelpers so they are available to Project.swift, Workspace.swift, and Package.swift (behind #TUIST).

When should I disable the binary cache?

Disable the binary cache with --no-binary-cache when you need to build from source for debugging, when reproducing release builds, or if a cached artifact causes unexpected behavior.