Tuist Tutorial for Xcode
- Getting Started
- Installing Tuist
- Getting Started With Tuist
- Understanding the Tuist Manifest File
- Setting up the Project File
- Defining Your Project
- Defining Your First Target
- Generating Your First Project
- Introducing Focus Mode
- Adding Support for Settings Files
- Setting up External Dependencies
- Moving Files Into Place
- Generating the Framework From Tuist
- Linking the Framework in MovieInfo
- Generating and Updating the Codebase
- Adding a Unit Test Target
- Adding Poster Images
- Adding a Swift Package
- Implementing Poster Images in the List
- Where to Go From Here?
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.
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
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:
- Sign up for a free account at the TMDB website.
- Go to the API Settings section.
- Under the Request an API Key section, click where it says click here.
- On the next screen, choose to register a Developer API key.
- 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).
- In the starter project, open Network.swift from the Project/MovieInfo/Source/Network group.
- At the top of the file, replace the <YOUR_API_KEY_HERE> value of
apiKeywith your API key.
- 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:
Your next step is to install the Tuist tooling. Open Terminal and run the following command:
bash <(curl -Ls https://install.tuist.io)
==> Downloading tuistenv... ==> Unzipping tuistenv... ==> Installing tuistenv... Password: ==> tuistenv installed. Try running 'tuist' ==> Check out the documentation at https://tuist.io/docs
This installs the
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:
This will create an empty manifest. Next, enter this:
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:
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
// 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:
- You create
project, which represents your base project and workspace container. You can name it anything you want, but Tuist recommends
namerepresents the name of the project and workspace files.
organizationNameappears in the copyright notice added at the top of each new file. Replace <YOUR_ORG_NAME_HERE> with your organization name.
settingsallows you to specify some other project settings. You'll set this in a later section.
targetsrepresents the list of targets associated with the project. You'll fill this in next.
Defining Your First Target
Add the following to the empty
// 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:
- Defines a
- Specifies the app's name.
- Sets the platform to iOS.
- Defines the output product as an app.
- Sets the bundle ID of the target. Replace <YOUR_BUNDLE_ID_HERE> with your preferred bundle ID.
- Locates Info.plist relative to Project.swift.
- Uses a wildcard pattern to specify all source files in the Source directory. Any directories become Xcode groups after project generation.
- Uses a wildcard pattern to specify all source files in the Resources directory. These directories also become Xcode groups after project generation.
- Specifies that there are no dependencies, which are external frameworks that require linking. You'll add some later in the tutorial.
- This is used to specify other settings to the target. You'll also add some later in the tutorial.
Target. Tuist generates sensible defaults for these, and you don't need to customize them, in this case. However, for more complex projects, there are several useful options worth checking out. For example, you can define run script and build phases, customize build schemes, link to Xcode template files to customize file generation and much more. Check out the Project.swift docs for much more info.
Your Project.swift is now ready to be used to generate your project.