ContextQMD
Back to Tuist

Previews {#previews}

server/priv/docs/en/guides/features/previews.md

4.191.810.9 KB
Original Source

Previews {#previews}

[!WARNING] Requirements

  • A <.localized_link href="/guides/server/accounts-and-projects">Tuist account and project</.localized_link>

Tuist Previews let you generate and share app previews so teammates can test builds without rebuilding locally.

When building an app, you may want to share it with others to get feedback. Traditionally, this is something that teams do by building, signing, and pushing their apps to platforms like Apple's TestFlight. However, this process can be cumbersome and slow, especially when you're just looking for quick feedback from a colleague or a friend.

To make this process more streamlined, Tuist provides a way to generate and share previews of your apps with anyone.

[!WARNING] Device Builds Need To Be Signed

When building for device, it is currently your responsibility to ensure the app is signed correctly. We plan to streamline this in the future.

::: code-group

bash
tuist generate App
tuist xcodebuild build -scheme App -workspace App.xcworkspace -configuration Debug -sdk iphonesimulator # Build the app for the simulator
tuist xcodebuild build -scheme App -workspace App.xcworkspace -configuration Debug -destination 'generic/platform=iOS' # Build the app for the device
tuist share App
bash
tuist generate App
tuist xcodebuild build -scheme App -workspace App.xcworkspace -configuration Release -sdk iphonesimulator # Build the app for the simulator
tuist xcodebuild build -scheme App -workspace App.xcworkspace -configuration Release -destination 'generic/platform=iOS' # Build the app for the device
tuist share App --configuration Release
bash
tuist xcodebuild build -scheme App -project App.xcodeproj -configuration Debug # Build the app for the simulator
tuist xcodebuild build -scheme App -project App.xcodeproj -configuration Debug -destination 'generic/platform=iOS' # Build the app for the device
tuist share App --configuration Debug --platforms iOS
tuist share App.ipa # Share an existing .ipa file
bash
tuist xcodebuild build -scheme App -project App.xcodeproj -configuration Release # Build the app for the simulator
tuist xcodebuild build -scheme App -project App.xcodeproj -configuration Release -destination 'generic/platform=iOS' # Build the app for the device
tuist share App --configuration Release --platforms iOS
tuist share App.ipa # Share an existing .ipa file
<!-- -->

:::

The command will generate a link that you can share with anyone to run the app – either on a simulator or an actual device. All they'll need to do is to run the command below:

bash
tuist run {url}
tuist run --device "My iPhone" {url} # Run the app on a specific device

When sharing an .ipa file, you can download the app directly from the mobile device using the Preview link. The links to .ipa previews are by default private, meaning the recipient needs to authenticate with their Tuist account to download the app. You can change this to public in the project settings if you want to share the app with anyone.

tuist run also enables you to run a latest preview based on a specifier such as latest, branch name, or a specific commit hash:

bash
tuist run App@latest # Runs latest App preview associated with the project's default branch
tuist run App@my-feature-branch # Runs latest App preview associated with a given branch
tuist run App@00dde7f56b1b8795a26b8085a781fb3715e834be # Runs latest App preview associated with a given git commit sha

[!WARNING] Unique Build Numbers In Ci

Ensure the CFBundleVersion (build version) is unique by leveraging a CI run number that most CI providers expose. For example, in GitHub Actions you can set the CFBundleVersion to the <code v-pre>${{ github.run_number }}</code> variable.

Uploading a preview with the same binary (build) and the same CFBundleVersion will fail.

Tracks {#tracks}

Tracks allow you to organize your previews into named groups. For example, you might have a beta track for internal testers and a nightly track for automated builds. Tracks are lazily created — simply specify a track name when sharing, and it will be created automatically if it doesn't exist.

To share a preview on a specific track, use the --track option:

bash
tuist share App --track beta
tuist share App --track nightly

This is useful for:

  • Organizing previews: Group previews by purpose (e.g., beta, nightly, internal)
  • In-app updates: The Tuist SDK uses tracks to determine which updates to notify users about
  • Filtering: Easily find and manage previews by track in the Tuist dashboard

[!WARNING] Previews' Visibility

Only people with access to the organization the project belongs to can access the previews. We plan to add support for expiring links.

Tuist macOS app {#tuist-macos-app}

<div style="display: flex; flex-direction: column; align-items: center;"> 
<h1>Tuist</h1>
<a href="https://tuist.dev/download" style="text-decoration: none;">Download</a>
</div>

To make running Tuist Previews even easier, we developed a Tuist macOS menu bar app. Instead of running Previews via the Tuist CLI, you can download the macOS app. You can also install the app by running brew install --cask tuist/tuist/tuist.

When you now click on "Run" in the Preview page, the macOS app will automatically launch it on your currently selected device.

[!WARNING] Requirements

You need to have Xcode locally installed and be on macOS 14 or later.

Tuist iOS app {#tuist-ios-app}

<div style="display: flex; flex-direction: column; align-items: center;"> 
<h1 style="padding-top: 2px;">Tuist</h1>

<a href="https://apps.apple.com/us/app/tuist/id6748460335" target="_blank" style="padding-top: 10px;">
    
</a>
</div>

Similarly to the macOS app, the Tuist iOS apps streamlines accessing and running your previews.

Pull/merge request comments {#pullmerge-request-comments}

[!WARNING] Integration With Git Platform Required

To get automatic pull/merge request comments, integrate your <.localized_link href="/guides/server/accounts-and-projects">remote project</.localized_link> with a <.localized_link href="/guides/server/authentication">Git platform</.localized_link>.

Testing new functionality should be a part of any code review. But having to build an app locally adds unnecessary friction, often leading to developers skipping testing functionality on their device at all. But what if each pull request contained a link to the build that would automatically run the app on a device you selected in the Tuist macOS app?

Once your Tuist project is connected with your Git platform such as GitHub, add a <.localized_link href="/cli/share">tuist share MyApp</.localized_link> to your CI workflow. Tuist will then post a Preview link directly in your pull requests:

In-app update notifications {#in-app-update-notifications}

The Tuist SDK enables your app to detect when a newer preview version is available and notify users. This is useful for keeping testers on the latest build.

The SDK checks for updates within the same preview track. When you share a preview with an explicit track using --track, the SDK will look for updates on that track. If no track is specified, the git branch is used as the track — so a preview built from the main branch will only notify about newer previews also built from main.

Installation {#sdk-installation}

Add Tuist SDK as a Swift Package dependency:

swift
.package(url: "https://github.com/tuist/sdk", .upToNextMajor(from: "0.1.0"))

Monitor for updates {#sdk-monitor-updates}

Use monitorPreviewUpdates to periodically check for new preview versions:

swift
import TuistSDK

struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .task {
                    TuistSDK(
                        fullHandle: "myorg/myapp",
                        apiKey: "your-api-key"
                    )
                    .monitorPreviewUpdates()
                }
        }
    }
}

Single update check {#sdk-single-check}

For manual update checking:

swift
let sdk = TuistSDK(
    fullHandle: "myorg/myapp",
    apiKey: "your-api-key"
)

if let preview = try await sdk.checkForUpdate() {
    print("New version available: \(preview.version ?? "unknown")")
}

Stopping update monitoring {#sdk-stop-monitoring}

monitorPreviewUpdates returns a Task that can be cancelled:

swift
let task = sdk.monitorPreviewUpdates { preview in
    // Handle update
}

// Later, to stop monitoring:
task.cancel()

[!NOTE] Update checking is automatically disabled on simulators and App Store builds.

README badge {#readme-badge}

To make Tuist Previews more visible in your repository, you can add a badge to your README file that points to the latest Tuist Preview:

To add the badge to your README, use the following markdown and replace the account and project handles with your own:

[![Tuist Preview](https://tuist.dev/{account-handle}/{project-handle}/previews/latest/badge.svg)](https://tuist.dev/{account-handle}/{project-handle}/previews/latest)

If your project contains multiple apps with different bundle identifiers, you can specify which app's preview to link to by adding a bundle-id query parameter:

[![Tuist Preview](https://tuist.dev/{account-handle}/{project-handle}/previews/latest/badge.svg)](https://tuist.dev/{account-handle}/{project-handle}/previews/latest?bundle-id=com.example.app)

Automations {#automations}

You can use the --json flag to get a JSON output from the tuist share command:

tuist share --json

The JSON output is useful to create custom automations, such as posting a Slack message using your CI provider. The JSON contains a url key with the full preview link and a qrCodeURL key with the URL to the QR code image to make it easier to download previews from a real device. An example of a JSON output is below:

json
{
  "id": 1234567890,
  "url": "https://cloud.tuist.io/preview/1234567890",
  "qrCodeURL": "https://cloud.tuist.io/preview/1234567890/qr-code.svg"
}