Setting Up Your Xcode Project for The Composable Architecture

Dave at his laptop

In the second part of our comprehensive guide on The Composable Architecture (TCA) for Swift, we look at the practical implementation

Setting up your Xcode project for The Composable Architecture (TCA) is a crucial step that lays the groundwork for building robust and maintainable iOS applications. In this section, we'll guide you through configuring dependencies, organising project structure, and integrating necessary frameworks or libraries to get started with TCA effectively.

To begin, let's create a new Xcode project or adapt an existing one to incorporate TCA.

Open Xcode and select "Create a new Xcode project" from the welcome screen or go to File > New > Project. Choose a template that suits your project requirements, such as SwiftUI App or UIKit App, and follow the prompts to create the project.

Once your project is created, the next step is to add the TCA library, which provides the foundational components for implementing TCA in your iOS app. You can add Composable Architecture to your project using Swift Package Manager (SPM) or CocoaPods.

If you're using SPM, navigate to your Xcode project, select the project file in the Project navigator, and navigate to the Swift Packages tab. Click the "+" button and enter the URL for the Composable Architecture repository:


Select the version you want to use and click "Next" to add the dependency to your project.

If you prefer using CocoaPods, add the following line to your Podfile:

pod 'ComposableArchitecture'

Then, run pod install in your project directory to install the dependency.

With the dependencies added, it's time to organise your project structure for TCA. You can create separate directories for different application components, such as Models, Views, ViewModels, Stores, and Actions. This modular approach promotes code organisation and maintainability, making it easier to navigate and work with your project as it grows.

Here's an example directory structure for an SCA-based iOS app:

markdownCopy code
- MyApp
 - Models
 - AppState.swift
 - Action.swift
 - Reducer.swift
- Views
 - ContentView.swift
- Stores
 - AppStore.swift
- Supporting Files
 - Info.plist

In this structure, Models contain definitions for the application state, actions, and reducers. Views contain SwiftUI views that render UI components based on the application state. Stores contain the central store responsible for managing state and handling actions. Supporting files include configuration files such as Info.plist.

By following these steps to set up your Xcode project for The Composable Architecture, you'll be well-prepared to implement TCA in your iOS app.

Defining State, Actions, and Reducers: The Key components of TCA

In The Composable Architecture (TCA), defining state, actions, and reducers forms the cornerstone of building a scalable and maintainable iOS application. These three key components work in tandem to facilitate predictable data flow and effectively encapsulate application logic. Let's delve into each component to understand its roles, relationships, and best practices for implementation.

  • State serves as the single source of truth for the entire application. It represents the current state of your application's data and UI, encapsulating all the information needed to render the UI and respond to user interactions. State is typically defined as a struct that conforms to the Equatable protocol to facilitate state comparison and the UI view update cycle.

struct State: Equatable {
  var counter: Int
  var isLoading: Bool
  // Additional properties representing application state

In the example above, State defines the state of our application, including a counter value and a boolean flag indicating whether data is currently being loaded.

  • Actions represent user interactions or events that trigger state changes in the application. Actions are simple value types that capture the intent of the user and carry any necessary data payloads. Each action corresponds to a specific user interaction or event, such as tapping a button, entering text into a text field, or receiving data from a network request.

enum Action {
  case increment
  case decrement
  case setLoading(Bool)
  // Additional actions representing user interactions

In this example, Action defines actions for incrementing and decrementing the counter, as well as setting the loading state

  • Reducers are pure functions responsible for transforming the application's current state in response to actions. They take the current state and an action as input and return a new state representing the updated state of the application. Reducers are composable and can be combined to handle multiple actions and state transformations in a modular and predictable manner.

var body: some Reducer<State, Action> { 
  Reduce { state, action in
    switch action {
    case .increment:
      state.counter += 1
      return .none
    case .decrement:
      state.counter -= 1
      return .none
    case .setLoading(let isLoading):
      state.isLoading = isLoading
      return .none
    // Handle additional actions and state transformations

In the body example above, we define a reducer that handles actions for incrementing, decrementing the counter, and setting the loading state.

By defining state, actions, and reducers, developers can establish a clear and structured architecture for their iOS applications, promoting modularity, testability, and maintainability.

Integrating these components into your iOS app, enables you to build scalable and robust applications with The Composable Architecture.

Effects -You will notice in the reducer we are returning .none when handling each of our actions. This introduces that final component to TCA; side effects,, also known as effects. Effects refer to any operation that occurs outside the pure functional realm of state transformations within reducers. This can include asynchronous tasks such as making network requests, accessing device sensors or interacting with external services like databases or APIs. In TCA the final act of a reducer evolving the current state of the app is to return an Effect type which encapsulates the asynchronous operations and feeds their data back into the system.

TCA provides 3 main effects, run which wraps the asynchronous unit of work and can emit any number of additional actions, send immediately emits an action, and none is an effect that completes immediately if there is no additional work to be done.

Click here to read about how to manage state changes with TCA.

Looking for something else?

Search over 400 blog posts from our team

Want to hear more?

Subscribe to our monthly digest of blogs to stay in the loop and come with us on our journey to make things better!