Skip to main content

​
Overview

Tuist.swift (also known as Config.swift) is the global configuration manifest for Tuist. It defines project-wide settings, cache configuration, server URL, and other options that apply across all projects in your repository.

​
Location

Tuist traverses up the directory hierarchy to find Tuist.swift. It’s typically placed at the root of your repository: 
/Tuist.swift           # Configuration manifest
/Workspace.swift       # Optional workspace definition
/App/Project.swift     # Project manifest
/Framework/Project.swift
This way, all projects in subdirectories share the same configuration.

​
Basic structure

import ProjectDescription

let config = Config(
    fullHandle: "my-org/my-project",
    url: "https://tuist.dev",
    cache: .cache(upload: true),
    project: .tuist(
        compatibleXcodeVersions: .all,
        swiftVersion: "6.0",
        plugins: [],
        generationOptions: .options(),
        installOptions: .options()
    )
)
Config is a type alias for Tuist.

​
Properties

​
fullHandle

​
fullHandle
String?
default:"nil"
The full project handle such as tuist-org/tuist. Used to identify your project when connecting to Tuist’s servers for caching, previews, and analytics.

​
url

​
url
String
default:"https://tuist.dev"
The base URL that points to the Tuist server. Use this to point to a self-hosted Tuist server if needed.

​
cache

​
cache
Cache
default:".cache()"
Configures Xcode cache behavior.

​
inspectOptions

​
inspectOptions
InspectOptions
default:".options()"
Options to use when running tuist inspect.

​
project

​
project
TuistProject
required
Configures the project Tuist will interact with. When no project is provided, Tuist defaults to the workspace or project in the current directory.

​
Cache configuration

let config = Config(
    cache: .cache(upload: true)
)

​
Cache options

​
upload
Bool
default:"true"
When true, the local proxy uploads artifacts to the remote cache. Set to false for read-only mode (downloads only, no uploads).

​
Project configuration

The project parameter accepts a TuistProject value that configures various project-level settings: 
let config = Config(
    project: .tuist(
        compatibleXcodeVersions: .list(["15.0", "15.1"]),
        swiftVersion: "6.0",
        plugins: [
            .git(url: "https://github.com/my-org/my-plugin", tag: "1.0.0")
        ],
        generationOptions: .options(
            resolveDependenciesWithSystemScm: false,
            disablePackageVersionLocking: false
        ),
        installOptions: .options(
            passthroughSwiftPackageManagerArguments: []
        )
    )
)

​
Compatible Xcode versions

​
compatibleXcodeVersions
CompatibleXcodeVersions
default:".all"
List of Xcode versions the project is compatible with. Options:
  • .all - Any Xcode version
  • .list([String]) - Specific versions
  • .min(String) - Minimum version
  • .exact(String) - Exact version only

​
Swift version

​
swiftVersion
Version?
default:"nil"
The version of Swift that will be used by Tuist. When nil, uses the Swift version from the selected Xcode.

​
Plugins

​
plugins
[PluginLocation]
default:"[]"
A list of plugins to extend Tuist functionality. Plugins can be loaded from:
  • Git repositories
  • Local paths
  • Swift Package Manager

​
Generation options

​
generationOptions
GenerationOptions
default:".options()"
Options to control project generation behavior:
  • resolveDependenciesWithSystemScm: Use system SCM for dependencies
  • disablePackageVersionLocking: Disable SPM package version locking
  • additionalPackageResolutionArguments: Extra arguments for package resolution

​
Install options

​
installOptions
InstallOptions
default:".options()"
Options for the tuist install command:
  • passthroughSwiftPackageManagerArguments: Arguments to pass through to Swift Package Manager

​
Examples

​
Minimal configuration

import ProjectDescription

let config = Config(
    fullHandle: "my-org/my-project"
)

​
With custom server URL

import ProjectDescription

let config = Config(
    fullHandle: "my-org/my-project",
    url: "https://tuist.mycompany.com"
)

​
Read-only cache

import ProjectDescription

let config = Config(
    fullHandle: "my-org/my-project",
    cache: .cache(upload: false)  // Download only, no uploads
)

​
With Xcode version constraints

import ProjectDescription

let config = Config(
    fullHandle: "my-org/my-project",
    project: .tuist(
        compatibleXcodeVersions: .list(["15.0", "15.1", "15.2"]),
        swiftVersion: "6.0"
    )
)

​
With plugins

import ProjectDescription

let config = Config(
    fullHandle: "my-org/my-project",
    project: .tuist(
        plugins: [
            .git(
                url: "https://github.com/my-org/tuist-plugin",
                tag: "1.0.0"
            ),
            .local(path: "./Plugins/MyPlugin")
        ]
    )
)

​
Full configuration

import ProjectDescription

let config = Config(
    fullHandle: "my-org/my-project",
    inspectOptions: .options(),
    cache: .cache(upload: true),
    url: "https://tuist.dev",
    project: .tuist(
        compatibleXcodeVersions: .min("15.0"),
        swiftVersion: "6.0",
        plugins: [
            .git(
                url: "https://github.com/tuist/tuist-plugin-lint",
                tag: "1.0.0"
            )
        ],
        generationOptions: .options(
            resolveDependenciesWithSystemScm: false,
            disablePackageVersionLocking: false,
            additionalPackageResolutionArguments: ["--verbose"]
        ),
        installOptions: .options(
            passthroughSwiftPackageManagerArguments: ["--allow-writing-to-package-directory"]
        )
    )
)

​
Best practices

Single config file

Keep one Tuist.swift at your repository root to ensure consistent behavior across all projects.

Version control

Commit Tuist.swift to version control so all team members share the same configuration.

Team caching

Set cache: .cache(upload: true) to enable cache sharing across your team.

Xcode constraints

Use compatibleXcodeVersions to ensure team members use compatible Xcode versions.