Manifests

Understanding Project.swift, Workspace.swift, and Config.swift manifest files

Tuist uses Swift-based manifest files to describe your projects, workspaces, and configuration. This guide explains each manifest type and how to use them effectively.

Manifest Types

Tuist supports three main manifest files:

Project.swift

Defines a single Xcode project with targets, schemes, and settings

Workspace.swift

Groups multiple projects into an Xcode workspace

Tuist.swift

Global configuration and shared settings (formerly Config.swift)

Project.swift

The Project.swift manifest defines an Xcode project and its targets.

Basic Structure

Minimal Example

import ProjectDescription

let project = Project(
    name: "MyApp",
    targets: [
        .target(
            name: "MyApp",
            destinations: .iOS,
            product: .app,
            bundleId: "com.example.myapp",
            sources: ["Sources/**"],
            resources: ["Resources/**"]
        )
    ]
)

import ProjectDescription

let project = Project(
    name: "MyApp",
    organizationName: "My Company",
    options: .options(
        automaticSchemesOptions: .disabled,
        textSettings: .textSettings(
            usesTabs: false,
            indentWidth: 4,
            tabWidth: 4
        )
    ),
    packages: [
        .remote(
            url: "https://github.com/Alamofire/Alamofire",
            requirement: .upToNextMajor(from: "5.8.0")
        )
    ],
    settings: .settings(
        configurations: [
            .debug(name: "Debug"),
            .release(name: "Release")
        ]
    ),
    targets: [
        .target(
            name: "MyApp",
            destinations: [.iPhone, .iPad],
            product: .app,
            bundleId: "com.example.myapp",
            deploymentTargets: .iOS("15.0"),
            infoPlist: .extendingDefault(with: [
                "UILaunchScreen": [:],
                "CFBundleDisplayName": "My App"
            ]),
            sources: ["MyApp/Sources/**"],
            resources: ["MyApp/Resources/**"],
            scripts: [
                .pre(
                    script: "swiftlint",
                    name: "SwiftLint"
                )
            ],
            dependencies: [
                .target(name: "MyAppKit"),
                .external(name: "Alamofire")
            ],
            settings: .settings(
                base: [
                    "DEVELOPMENT_TEAM": "ABCDEF1234"
                ]
            )
        ),
        .target(
            name: "MyAppKit",
            destinations: .iOS,
            product: .framework,
            bundleId: "com.example.myapp.kit",
            sources: ["MyAppKit/Sources/**"]
        ),
        .target(
            name: "MyAppTests",
            destinations: .iOS,
            product: .unitTests,
            bundleId: "com.example.myapp.tests",
            sources: ["MyApp/Tests/**"],
            dependencies: [
                .target(name: "MyApp")
            ]
        )
    ],
    schemes: [
        .scheme(
            name: "MyApp-Dev",
            shared: true,
            buildAction: .buildAction(targets: ["MyApp"]),
            testAction: .targets(["MyAppTests"]),
            runAction: .runAction(
                executable: "MyApp",
                arguments: .arguments(
                    environmentVariables: [
                        "API_URL": "https://dev.api.example.com"
                    ]
                )
            )
        )
    ],
    additionalFiles: [
        "README.md",
        ".swiftlint.yml"
    ]
)

Key Components

Targets

Targets define buildable components:

.target(
    name: "FeatureProfile",
    destinations: .iOS,
    product: .framework,
    bundleId: "com.example.profile",
    deploymentTargets: .iOS("15.0"),
    sources: ["Profile/Sources/**"],
    resources: ["Profile/Resources/**"],
    dependencies: [
        .target(name: "Core"),
        .external(name: "Kingfisher")
    ]
)

Product types:

• .app - Application
• .framework - Dynamic framework
• .staticFramework - Static framework
• .staticLibrary - Static library
• .unitTests - Unit test bundle
• .uiTests - UI test bundle
• .appExtension - App extension
• .watch2App - watchOS app

Dependencies

Link targets and external packages:

dependencies: [
    // Internal target
    .target(name: "CoreKit"),
    
    // Another project
    .project(
        target: "Networking",
        path: "../Networking"
    ),
    
    // Swift Package
    .external(name: "Alamofire"),
    
    // XCFramework
    .xcframework(path: "Vendor/Analytics.xcframework"),
    
    // SDK framework
    .sdk(name: "StoreKit", type: .framework)
]

Sources & Resources

Define source files and resources:

// Glob patterns for sources
sources: [
    "Sources/**/*.swift",
    "Sources/**/*.m",
    "Sources/**/*.h"
]

// Resources with specific handling
resources: [
    // Standard resources
    "Resources/**",
    
    // Folder references (blue folders)
    .folderReference(path: "Assets"),
    
    // Privacy manifest
    .process("PrivacyInfo.xcprivacy"),
    
    // Copy without processing
    .copy("data.json")
]

Tuist automatically excludes test files and supports .lproj for localization

Build Settings

Configure build settings at project or target level:

settings: .settings(
    base: [
        "SWIFT_VERSION": "5.9",
        "IPHONEOS_DEPLOYMENT_TARGET": "15.0"
    ],
    configurations: [
        .debug(
            name: "Debug",
            settings: [
                "ENABLE_TESTABILITY": "YES",
                "SWIFT_OPTIMIZATION_LEVEL": "-Onone"
            ]
        ),
        .release(
            name: "Release",
            settings: [
                "SWIFT_OPTIMIZATION_LEVEL": "-O"
            ]
        )
    ]
)

Schemes

Custom build, test, and run configurations:

.scheme(
    name: "MyApp-Staging",
    shared: true,
    buildAction: .buildAction(
        targets: ["MyApp", "MyAppKit"],
        preActions: [
            .executionAction(
                scriptText: "echo 'Starting build...'",
                target: "MyApp"
            )
        ]
    ),
    testAction: .targets(
        ["MyAppTests"],
        options: .options(
            coverage: true,
            language: "en"
        )
    ),
    runAction: .runAction(
        executable: "MyApp",
        arguments: .arguments(
            environmentVariables: [
                "API_URL": .environmentVariable(
                    value: "https://staging.api.example.com",
                    isEnabled: true
                )
            ],
            launchArguments: [
                .launchArgument(name: "-debug", isEnabled: true)
            ]
        )
    ),
    profileAction: .profileAction(executable: "MyApp"),
    analyzeAction: .analyzeAction(configuration: "Debug"),
    archiveAction: .archiveAction(configuration: "Release")
)

Advanced Features

Target Scripts

Add custom build phases:

scripts: [
    // Pre-build script
    .pre(
        script: """
        if which swiftlint >/dev/null; then
            swiftlint
        else
            echo "warning: SwiftLint not installed"
        fi
        """,
        name: "SwiftLint",
        basedOnDependencyAnalysis: false
    ),
    
    // Post-build script
    .post(
        path: "Scripts/upload-symbols.sh",
        name: "Upload Debug Symbols",
        inputPaths: ["$DWARF_DSYM_FOLDER_PATH"],
        outputPaths: []
    )
]

Foreign Builds

Wrap non-Xcode build systems (KMP, Rust, etc.):

.foreignBuild(
    name: "SharedKMP",
    destinations: .iOS,
    script: """
    eval "$($HOME/.local/bin/mise activate bash --shims)"
    cd $SRCROOT/SharedKMP
    gradle assembleSharedKMPReleaseXCFramework
    """,
    inputs: [
        .folder("SharedKMP/src"),
        .file("SharedKMP/build.gradle.kts")
    ],
    output: .xcframework(
        path: "SharedKMP/build/XCFrameworks/release/SharedKMP.xcframework",
        linking: .dynamic
    )
)

Resource Synthesizers

Generate code for resources:

resourceSynthesizers: [
    .strings(),
    .assets(),
    .fonts(),
    .plists(),
    .custom(
        name: "JSONAssets",
        parser: .json,
        extensions: ["json"]
    )
]

Access generated code:

// Strings
let title = MyAppStrings.profileTitle

// Assets
let icon = MyAppAssets.profileIcon.image

// Fonts
let font = MyAppFonts.custom(name: "CustomFont", size: 14)

Workspace.swift

The Workspace.swift manifest groups multiple projects into an Xcode workspace.

Basic Workspace

import ProjectDescription

let workspace = Workspace(
    name: "MyWorkspace",
    projects: [
        "App",
        "Framework",
        "Packages/**"
    ]
)

import ProjectDescription

let workspace = Workspace(
    name: "MyWorkspace",
    projects: [
        "App",
        "Features/**",
        "Core"
    ],
    schemes: [
        .scheme(
            name: "AllTargets",
            shared: true,
            buildAction: .buildAction(
                targets: [
                    .project(path: "App", target: "App"),
                    .project(path: "Core", target: "Core")
                ]
            )
        )
    ],
    fileHeaderTemplate: .file("Templates/FileHeader.txt"),
    additionalFiles: [
        "README.md",
        "Documentation/**"
    ],
    generationOptions: .options(
        autogeneratedWorkspaceSchemes: .disabled
    )
)

When to Use Workspaces

Use Workspace.swift when you need to:

• Group multiple independent projects
• Share schemes across projects
• Organize a large codebase into modules
• Include documentation or non-project files

If you only have one Project.swift, Tuist automatically generates a workspace - you don’t need Workspace.swift

Tuist.swift (Config)

The Tuist.swift manifest (formerly Config.swift) provides global configuration that applies to all projects in your workspace.

Basic Config

import ProjectDescription

let tuist = Tuist(
    project: .tuist(
        generationOptions: .options(
            enableCaching: true
        )
    )
)

import ProjectDescription

let tuist = Tuist(
    fullHandle: "myorg/myproject",
    inspectOptions: .options(
        cacheOutputType: .json
    ),
    cache: .cache(
        upload: true
    ),
    url: "https://tuist.dev",
    project: .tuist(
        compatibleXcodeVersions: .list(["15.0", "15.1"]),
        swiftVersion: .init("5.9"),
        plugins: [
            .git(url: "https://github.com/myorg/tuist-plugin", tag: "1.0.0")
        ],
        generationOptions: .options(
            enableCaching: true,
            optionalAuthentication: false,
            disableSandbox: false,
            xcodeProjectName: "MyProject",
            additionalPackageResolutionArguments: [
                "--replace-scm-with-registry"
            ]
        ),
        installOptions: .options(
            passthroughSwiftPackageManagerArguments: [
                "--verbose"
            ]
        )
    )
)

Configuration Options

Generation

Control how projects are generated:

generationOptions: .options(
    // Enable Tuist Cloud caching
    enableCaching: true,
    
    // Custom Xcode project name
    xcodeProjectName: "MyApp",
    
    // Allow manifest execution without auth
    optionalAuthentication: true,
    
    // Disable sandboxing (dev only)
    disableSandbox: false,
    
    // Additional SPM arguments
    additionalPackageResolutionArguments: [
        "--replace-scm-with-registry"
    ]
)

Cache

Configure binary caching:

cache: .cache(
    // Enable cache uploads (disable for CI read-only)
    upload: true
)

Plugins

Extend Tuist with plugins:

plugins: [
    // Git-based plugin
    .git(
        url: "https://github.com/tuist/tuist-plugin-swiftlint",
        tag: "1.0.0"
    ),
    
    // Local plugin
    .local(path: "../MyTuistPlugin")
]

Compatibility

Enforce Xcode and Swift versions:

compatibleXcodeVersions: .list([
    "15.0",
    "15.1",
    "15.2"
]),

swiftVersion: .init("5.9")

Or use ranges:

compatibleXcodeVersions: .range(
    from: "15.0",
    to: "16.0"
)

Project Helpers

Create reusable manifest helpers in Tuist/ProjectDescriptionHelpers/:

Tuist/ProjectDescriptionHelpers/Target+Templates.swift

import ProjectDescription

public extension Target {
    static func feature(
        name: String,
        dependencies: [TargetDependency] = []
    ) -> Target {
        return .target(
            name: name,
            destinations: .iOS,
            product: .framework,
            bundleId: "com.example.\(name.lowercased())",
            deploymentTargets: .iOS("15.0"),
            sources: ["\(name)/Sources/**"],
            resources: ["\(name)/Resources/**"],
            dependencies: dependencies + [.target(name: "Core")]
        )
    }
    
    static func featureTests(for feature: String) -> Target {
        return .target(
            name: "\(feature)Tests",
            destinations: .iOS,
            product: .unitTests,
            bundleId: "com.example.\(feature.lowercased()).tests",
            sources: ["\(feature)/Tests/**"],
            dependencies: [
                .target(name: feature)
            ]
        )
    }
}

import ProjectDescription
import ProjectDescriptionHelpers

let project = Project(
    name: "MyApp",
    targets: [
        .feature(name: "Profile"),
        .featureTests(for: "Profile"),
        
        .feature(name: "Settings"),
        .featureTests(for: "Settings")
    ]
)

Best Practices

One Project Per Module

Split large apps into focused projects:

/MyApp
├── App/Project.swift           # Main app
├── Features/
│   ├── Profile/Project.swift   # Profile feature
│   └── Settings/Project.swift  # Settings feature
└── Core/Project.swift          # Shared utilities

Use Type-Safe Helpers

Leverage Swift’s type system:

enum BundleIdentifiers {
    static let app = "com.example.app"
    static let framework = "com.example.framework"
}

.target(
    bundleId: BundleIdentifiers.app
)

Environment Variables

Use environment variables for sensitive data:

settings: .settings(
    base: [
        "DEVELOPMENT_TEAM": Environment.developmentTeam.getString(default: "")
    ]
)

.env

TUIST_DEVELOPMENT_TEAM=ABCDEF1234

Next Steps

Generated Projects

Learn how manifests become Xcode projects

Workspaces

Organize multi-project workspaces

Architecture

Understand Tuist’s architecture

API Reference

Complete manifest API documentation