Dynamic configuration {#dynamic-configuration}

There are certain scenarios where you might need to dynamically configure your project at generation time. For example, you might want to change the name of the app, the bundle identifier, or the deployment target based on the environment where the project is being generated. Tuist supports that via environment variables, which can be accessed from the manifest files.

Configuration through environment variables {#configuration-through-environment-variables}

Tuist allows passing configuration through environment variables that can be accessed from the manifest files. For example:

TUIST_APP_NAME=MyApp tuist generate

If you want to pass multiple environment variables just separate them with a space. For example:

TUIST_APP_NAME=MyApp TUIST_APP_LOCALE=pl tuist generate

Reading the environment variables from manifests {#reading-the-environment-variables-from-manifests}

Variables can be accessed using the Environment type. Any variables following the convention TUIST_XXX defined in the environment or passed to Tuist when running commands will be accessible using the Environment type. The following example shows how we access the TUIST_APP_NAME variable:

func appName() -> String {
    if case let .string(environmentAppName) = Environment.appName {
        return environmentAppName
    } else {
        return "MyApp"
    }
}

Accessing variables returns an instance of type Environment.Value? which can take any of the following values:

You can also retrieve the string or boolean Environment variable using either of the helper methods defined below, these methods require a default value to be passed to ensure the user gets consistent results each time. This avoids the need to define the function appName() defined above.

::: code-group

Environment.appName.getString(default: "TuistServer")

Environment.isCI.getBoolean(default: false)

:::

Forwarding additional environment variables to manifests {#forwarding-additional-environment-variables-to-manifests}

By default, only variables prefixed with TUIST_, plus CI and DEVELOPER_DIR, are forwarded to the subprocess that evaluates Project.swift, Workspace.swift, Package.swift, and the project description helpers. This keeps generation deterministic and prevents unrelated shell or CI variables from invalidating the manifest cache.

When a manifest needs to read variables that are not under your control (for example, a third-party Package.swift that already reads OPENSWIFTUI_LIBRARY_TYPE), declare them in Tuist.swift via manifestEnvironment on the generation options. Each entry is either a literal name or a name ending in * for prefix matching:

import ProjectDescription

let tuist = Tuist(
    project: .tuist(
        generationOptions: .options(
            manifestEnvironment: [
                "OPENSWIFTUI_*",
                "MY_VAR",
            ]
        )
    )
)

Listed variables participate in the manifest cache hash, so changes to their values invalidate the cache as expected. Variables not listed remain hidden from manifest evaluation.