Modular app sample project

[wltrup]

Hello everyone and @jberstler 👋

I've been experimenting with setting up modular apps and, in view of a question posted recently here on that very subject, I thought I'd share the results of my efforts.

The setup I ended up with works great, except for the occasional hiccup caused by Xcode getting confused by Swift packages. I find that resetting the package cache resolves the issues I've encountered. Other than that, it's smooth sailing most of the time.

The setup lets me have multiple executable targets (even of multiple platforms) all sharing the same package of modules, which the executables can "enter into" by judiciously choosing specific modules to add to the "Frameworks, Libraries, and Embedded Content" section of the executable's target. More on that in a bit.

I'm attaching a simple sample project that highlights the main ideas. I encourage everyone reading this to open it before continuing to read this post.

To create a modular project, start by following these steps:

1. In a directory of your choosing for the new project, create an empty directory called "Executables" (or whatever you want but this is how I've been doing it)
2. From within Xcode, create a Swift package called "Modules" so that its top directory is a sibling of "Executables"
3. From within Xcode, create a workspace and save it as a sibling of those two directories

At this point, you should have something like the following (ignoring the contents of "Executables" for now):

4. Open the workspace in Xcode and drag the empty "Executables" directory and the "Modules" package into the workspace, from the Finder
5. From within Xcode, create a new project for your executable and save it inside the "Executables" directory. In the sample project here, that executable project is an iOS app called "ModApp" but it could be any executable project you want.
6. Drag the executable's Xcode project file into the "Executables" directory in the workspace. Note that it's the project file itself, not its enclosing directory. In the figure below, I already had the executable added and that's why you already see it there. I only pretended to add it so I could take the screenshot.

This step is how you'd add more executable projects to the workspace. If you want, you can organize them by some criteria. For example, I have an extra directory there for "Preview Apps", which are small apps that present a specific portion of the main app's UI. I occasionally also have a directory for "Utility Apps", small apps that I might need to write to experiment with some idea before committing myself to it in the main app(s).

Now, so far, the executable is not connected in any way to the "Modules" package so the next step is to set that up.

7. You need to create a module in the "Modules" package called "AppFeature". Again, you can name it however you like but this is the convention I've settled on. I suggest opening the sample project in Xcode and taking a look at how the "AppFeature" module is declared in the package manifest ("Package.swift") and where and how it sits on disk. In the sample project, the "AppFeature" module is the app's entry point into the package.
8. Once you've created a minimal "AppFeature" module that compiles successfully (it can be very minimal at this stage), you can add it to the "Frameworks, Libraries, and Embedded Content" section of the executable's target. This is also how you should add live implementations of your dependencies. The executable needs only one entry point ("AppFeature") and all the live implementations. Everything else is managed by the package's manifest and how the modules in the package interact with one another.

And that's it. The new executable project is now ready. I generally do some house-cleaning on its source (see the sample project) and also set project settings as needed. For example, the sample project has the Swift 6 language mode and strict concurrency both enabled. By the way, I just realized that that means you'll need to have the Xcode 16 beta installed. If not, you should open the sample project in Xcode 15 and change the language mode back to Swift 5.10.

A couple of extra things I added to the sample project:

• the app responds to app lifecycle events by firing actions that the "AppFeature" responds to. There's an intermediate module, "AppDelegate", to handle those actions at the app level, rather than at the feature level. That way, you can better separate responsibilities so that the feature modules only handle what they must. The "AppDelegate" module gets a first shot at all those actions before the "AppFeature" does.
• the "AppDelegate" module also keeps track of the app's launch dates: the first, the most recent prior to the current launch and the current launch. These dates are available as shared properties. In the sample project, AppFeature declares @SharedReader properties for them so that its view can display those dates. Here's the result of running the sample project (in Xcode 16 beta):

And that's it. You can build and test individual modules in isolation and integrate them using the package manifest and the import mechanism. Once you've set up the executable target as I recommended above, you hardly ever have to touch it again.

I've been using this setup for quite a while now and it works very well (again, sans the occasional Xcode hiccup). However, I do have a few questions that @mbrandonw, @stephencelis , or someone else might be able to answer:

• However hard I tried, I couldn't get rid of warnings about KeyPath sendability

Cannot form key path that captures non-sendable type 'KeyPath<AppDelegate.Action.AllCasePaths, AnyCasePath<AppDelegate.Action, Void>>'; this is an error in the Swift 6 language mode

• How can I test all modules in one go without having to create a separate scheme for that and manually adding a module every time I create a new one?

I hope this post is useful to anyone and everyone struggling to get a modular app going.

Cheers!

ModularAppSample.zip

[wltrup]

A colleague asked me how I deal with assets for the different devices and platforms, so I created a second sample project that builds apps for iOS (both an iPhone app and an iPad app) and macOS, with different assets for each and some shared assets for all of them.

The key for this setup to work is to move all assets (from all targets) - except the app icon and accent color - to a separate module.

Each target must then load 2 modules: the AppFeature module (as before) and the assets module (Assets).

This setup also has the advantage that all modules can be tested in isolation, even if they reference assets that one would normally have in the target project. The target projects are really just very thin wrappers and all the important stuff happens in the modules.

The Assets module has some code to make it easier to determine which target platform or device is currently being used and to select the appropriate color or image:

import SwiftUI

public func color(_ string: String) -> Color? {
   Color(string, bundle: Bundle.module)
}

public func image(_ string: String) -> Image? {
   Image(string, bundle: Bundle.module)
}

public enum UserInterfaceIdiom {
   case carPlay
   case mac
   case pad
   case phone
   case tv
   case vision
   case watch
   case unspecified
   case unknownDefault
}

@MainActor
extension EnvironmentValues {
#if os(iOS)
   public var userInterfaceIdiom: UserInterfaceIdiom {
      switch UIDevice.current.userInterfaceIdiom {
         case .carPlay:
            return .carPlay
         case .mac:
            return .mac
         case .pad:
            return .pad
         case .phone:
            return .phone
         case .tv:
            return .tv
         case .vision:
            return .vision
         case .unspecified:
            return .unspecified
         default:
            return .unknownDefault
      }
   }
#elseif os(OSX)
   public var userInterfaceIdiom: UserInterfaceIdiom { .mac }
#elseif os(tvOS)
   public var userInterfaceIdiom: UserInterfaceIdiom { .tv }
#elseif os(watchOS)
   public var userInterfaceIdiom: UserInterfaceIdiom { .watch }
#endif
}

As a result, a feature's view can be written as

import ComposableArchitecture
import SwiftUI

extension AppFeature {

   public struct View: SwiftUI.View {

      @Bindable var store: StoreOf<AppFeature>
      @Environment(\.userInterfaceIdiom) var userInterfaceIdiom

      public init(store: StoreOf<AppFeature>) {
         self.store = store
      }

      public var body: some SwiftUI.View {
         switch userInterfaceIdiom {
            case .phone:
               PhoneView(store: store)
            case .pad:
               PadView(store: store)
            case .mac:
               MacView(store: store)
            default:
               Text("Unknown Device")
         }
      }

   }

}

where each target-specific view does the real work:

import ComposableArchitecture
import Assets
import SwiftUI

#if os(iOS)
public struct PhoneView: View {

   @Bindable var store: StoreOf<AppFeature>
   public init(store: StoreOf<AppFeature>) {
      self.store = store
   }

   public var body: some SwiftUI.View {
         // create the actual view for an iPhone target
      }
   }

}
#else
public struct PhoneView: View {
   let store: StoreOf<AppFeature>
   public init(store: StoreOf<AppFeature>) {
      self.store = store
   }
   public var body: some SwiftUI.View {
      EmptyView()
   }
}
#endif

The #else branch is needed because the PhoneView, PadView, and MacView types are always visible to all the targets. It's the easiest way to avoid having to create separate target-specific modules just for the views.

And here are the results. Please forgive the awful UI for the macOS app, since mac development isn't my forté and I didn't want to spend the time to make it pretty.

Note how the targets have different layouts. Also, the Apple logo is a common asset but the other images are unique to each target. Colors may also be shared or unique (they're all unique in this sample project, in those places where they're explicitly specified). Oddly, the macOS target ignores the accent color set in the target's assets catalog (green in this sample project) and uses what's set by the user in their computer's System Settings instead (graphite in my case).

In all cases, the code at the point of use is free of #if os(...) clutter. In fact, here's the implementation of the AppFeature view for the iPhone app:

public struct PhoneView: View {

   let store: StoreOf<AppFeature>
   public init(store: StoreOf<AppFeature>) {
      self.store = store
   }

   public var body: some SwiftUI.View {
      NavigationStack {
         VStack {
            
            LaunchDatesView(
               isFirstLaunch: store.isFirstLaunch,
               dateOfFirstLaunch: store.dateOfFirstLaunch,
               dateOfLastLaunch: store.dateOfLastLaunch,
               dateOfThisLaunch: store.dateOfThisLaunch
            )
            .frame(maxHeight: 500)
            .foregroundColor(color("text"))

            Spacer()

            HStack {
               Spacer()
               if let logoImage = image("logo") {
                  logoImage
                     .resizable()
                     .aspectRatio(contentMode: .fit)
                     .frame(maxWidth: 100)
               }
               Spacer()
               if let deviceImage = image("device") {
                  deviceImage
                     .resizable()
                     .aspectRatio(contentMode: .fit)
               }
               Spacer()
            }
            .frame(maxHeight: 150)

            Spacer()

         }
         .navigationTitle("AppFeature on iPhone")
         .navigationBarTitleDisplayMode(.inline)
         
      }
   }

}

ModularAppSample-2.zip

[OddMagnet]

Hey, sorry for being somewhat off-topic here (not enough experience with modularization to fully appreciate this post), but have you found a way to get rid of the warnings about KeyPath sendability?

[jshier]

You need to enable the "Infer Sendable for Methods and Key Path Literals" upcoming feature in Xcode, or switch to Swift 6 mode.

[OddMagnet]

I've already set the Language Version to Swift 6, is there anything else I'd need to do?
(I also tried the usual suspects, cleaning, deleting DerivedData, restarting, etc)