Tuist.swift (Config)

Global configuration manifest for Tuist projects

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.

Related

• Project.swift reference
• Workspace.swift reference
• Cache command