Tuist Tutorial for Xcode

The almighty project file and its big brother, the workspace, are among the most significant pain points you’ll deal with in iOS development. Tuist is a tool that aims to make dealing with Xcode projects easier by taking the complexity out of thinking about your project structure. It embraces the Configuration by Convention philosophy and lets you focus on your project’s content rather than its organization.

In this Tuist tutorial, you’ll learn how to replace the traditional Xcode project workflow by using Tuist. You’ll start with an already functioning project, an app that displays top-rated movies, and update it to use Tuist. You’ll then take advantage of Tuist’s features to:

• Remove the project and workspace files. Instead, you’ll generate your project any time you need to.
• Add a unit test target.
• Handle the Swift Package Manager dependencies.
• Add new features that depend on the Tuist workflow.

Getting Started

Download the starter project by clicking the Download Materials button at the top or bottom of the tutorial. The starter project uses The Movie Database as a back end to display a list of top-rated movies.

Take a look through the project. You’ll see a standard setup with a network class that performs an API request with your credentials, then fetches and transforms the response before delivering it to a List component in the SwiftUI ContentView.

To use the starter project, you’ll need to sign up for an account to get an API key. Follow these steps to register and get your API key set up in the sample app:

1. Sign up for a free account at the TMDB website.
2. Go to the API Settings section.
3. Under the Request an API Key section, click where it says click here.
4. On the next screen, choose to register a Developer API key.
5. Assuming you’ve agreed to the terms of use, you’ll then need to enter some information about yourself and your app. It doesn’t matter what you enter here. For Developer API keys, you’ll get access to an API key immediately.
6. You’ll end up back in the API Settings section, which will now show an API key. Copy the value from API Key (v3 auth).
7. In the starter project, open Network.swift from the Project/MovieInfo/Source/Network group.
8. At the top of the file, replace the <YOUR_API_KEY_HERE> value of apiKey with your API key.
9. In the target settings for MovieInfo, replace -YOUR-BUNDLE-ID-HERE- with a bundle ID of your choice.

Finally, build and run. You’ll see a list of the 20 highest-rated movies:

Installing Tuist

Your next step is to install the Tuist tooling. Open Terminal and run the following command:

bash <(curl -Ls https://install.tuist.io)

You'll see:

==> Downloading tuistenv...
==> Unzipping tuistenv...
==> Installing tuistenv...
Password:
==> tuistenv installed. Try running 'tuist'
==> Check out the documentation at https://tuist.io/docs

This installs the tuist command.

Now that you've set everything up, it's time to dive into Tuist!

Getting Started With Tuist

Your first goal is to convert this project to use Tuist. From this point on, you won't rely on keeping the project and workspace files at the root of your project directory anymore. You'll shift your thinking; Tuist will only generate these files when you need them.

Understanding the Tuist Manifest File

The Tuist manifest is a file called Project.swift that tells Tuist how to create your Xcode project. You'll interact with Tuist from the command line, and you'll build your Tuist manifest in Xcode. Tuist generates an environment for you to work on your manifest file, then launches Xcode to give you code completion and everything you're used to in the Xcode environment.

Before you start, delete the existing project and workspace files. From here on out, you won't need to keep them around since you'll generate them when you need them!

Close the workspace in Xcode, then delete MovieInfo.xcodeproj and MovieInfo.xcworkspace.

Setting up the Project File

Next, create an empty Tuist manifest file. In Terminal, navigate to the root directory of the starter project and enter the following:

touch Project.swift

This will create an empty manifest. Next, enter this:

tuist edit

The first time you run the command, you might see some messages in the terminal about downloading and updating Tuist. After that, you'll see the following output:

Generating project Manifests
Opening Xcode to edit the project. Press CTRL + C once you are done editing

Xcode will open with a generated environment where you can begin editing the project file. Select Project.swift in Project navigator to start.

Next, add the following to the top of Project.swift:

import ProjectDescription

This will give you access to the Tuist project DSL. You'll use this to build out your project with some helpful code completion.

Defining Your Project

Your first step is to set up your main project. Add this code to Project.swift under import:

// 1
let project = Project(
  // 2
  name: "MovieInfo",
  // 3
  organizationName: "<YOUR_ORG_NAME_HERE>",
  // 4
  settings: nil,
  // 5
  targets: [])

Here's what's going on in the code above:

1. You create project, which represents your base project and workspace container. You can name it anything you want, but Tuist recommends project.
2. name represents the name of the project and workspace files.
3. organizationName appears in the copyright notice added at the top of each new file. Replace <YOUR_ORG_NAME_HERE> with your organization name.
4. settings allows you to specify some other project settings. You'll set this in a later section.
5. targets represents the list of targets associated with the project. You'll fill this in next.

Defining Your First Target

Add the following to the empty targets array:

// 1
Target(
  // 2
  name: "MovieInfo",
  // 3
  platform: .iOS,
  // 4
  product: .app,
  // 5
  bundleId: "<YOUR_BUNDLE_ID_HERE>",
  // 6
  infoPlist: "MovieInfo/Info.plist",
  // 7
  sources: ["MovieInfo/Source/**"],
  // 8
  resources: ["MovieInfo/Resources/**"],
  // 9
  dependencies: [],
  // 10
  settings: nil)

This does the following:

1. Defines a Target for the targets array.
2. Specifies the app's name.
3. Sets the platform to iOS.
4. Defines the output product as an app.
5. Sets the bundle ID of the target. Replace <YOUR_BUNDLE_ID_HERE> with your preferred bundle ID.
6. Locates Info.plist relative to Project.swift.
7. Uses a wildcard pattern to specify all source files in the Source directory. Any directories become Xcode groups after project generation.
8. Uses a wildcard pattern to specify all source files in the Resources directory. These directories also become Xcode groups after project generation.
9. Specifies that there are no dependencies, which are external frameworks that require linking. You'll add some later in the tutorial.
10. This is used to specify other settings to the target. You'll also add some later in the tutorial.

Your Project.swift is now ready to be used to generate your project.