skip to content

As the lead moving a 300k-line iOS app's features into local Swift packages, where do you draw the package and target seams, and what does it cost?

level: principalimportance: should knowfreq 38%

answer

  1. one package or many
  2. package access stops at the package
  3. leaves first, features after
  4. a product per feature
  5. resources and public API are the bill

basics

~20 s

Start with one local package: shared leaf targets (design system, networking, vendor wrappers) and one target and library product per feature, depending only downward. The cost is public API, Bundle.module rewrites, manifest upkeep and many more modules to build.

solid answer

~50 s

I start with **one local package** holding many targets rather than many packages: one manifest, one `platforms` list, and the `package` access modifier (tools version 5.9 and later) shares helpers across targets without making them `public`. The seams follow the dependency direction: **leaf targets** first — design system, networking, a wrapper around each closed-source SDK — then one target and **library product per feature**, each depending on leaves, never on another feature; SwiftPM refuses cycles, so the direction is enforced. The app target stays the composition root. The bill: every type the app touches needs `public` API, moved assets and strings need `bundle: .module`, the manifest becomes a shared, contended file, and hundreds of tiny modules add build steps. I measure clean and incremental build times before and after, and split into separate packages only when a part needs its own release cadence.

code

swift · 20 lines
swift
// swift-tools-version: 6.1
import PackageDescription

let package = Package(
    name: "Features",
    platforms: [.iOS(.v17), .macOS(.v14)],
    products: [
        // One library product per feature the app links.
        .library(name: "Checkout", targets: ["Checkout"]),
        .library(name: "Profile", targets: ["Profile"]),
    ],
    targets: [
        // Shared leaves: features depend on them, never on each other.
        .target(name: "DesignSystem", resources: [.process("Resources")]),
        .target(name: "Networking"),
        .target(name: "Checkout", dependencies: ["DesignSystem", "Networking"]),
        .target(name: "Profile", dependencies: ["DesignSystem", "Networking"]),
        .testTarget(name: "CheckoutTests", dependencies: ["Checkout"]),
    ]
)

go deeper

for a junior

Know that a local package holds several targets, that each target is a module, and that the app links library products from it.

for a middle

Explain package access versus public, why features depend only on leaf targets, and how SwiftPM reports a dependency cycle.

for a senior

Plan the extraction order, catch the public-initializer, Bundle.module and undeclared-import problems early, and measure build times before and after.

for a principal

Own the trade-off: one package or many, which seams follow ownership and change rate, what the module count costs, and when a part graduates to its own versioned package.

## The decision a lead owns Moving a large app into **local Swift packages** is mostly a set of SwiftPM decisions: how many packages, which targets, which products the app links, and which rules keep the graph honest. There is no single right layout; there are costs to trade. (How to draw the app's architecture — layers, data flow, navigation — is covered with mobile system design; this is the package layout that serves it.) ## One package with many targets, or many packages | Question | One local package, many targets | Several local packages | |---|---|---| | Sharing helpers across modules | `package` declarations work across all targets | Only `public` crosses a package boundary | | Manifests to maintain | One, contended by every team | One per package | | Platform minimums | One `platforms` list | One per package, each at or below the app's | | Visibility of seams | All targets in one file | Clear ownership per folder | | Separate versioning later | Needs a split first | Easier to publish one package on its own | The `package` access level (SE-0386, tools version 5.9) is the deciding detail: a `package static let` in `DesignSystem` is visible to `Checkout` in the same package but not to the app or another package, which reports it as inaccessible due to its `package` protection level. A target declared with `packageAccess: false` is denied the other targets' `package` symbols. Many teams start with **one package** and split only where a part needs its own release cadence or owner. ## Where the seams go - **Leaves first.** Design system, networking, persistence helpers, analytics. They depend on nothing app-specific and unblock everything else. - **A wrapper per closed-source SDK.** A source target that depends on the binary target and exposes your API, so features never import the vendor's module. - **One target and one library product per feature.** The app links `Checkout` and `Profile`; internal helper targets are not exported as products. - **Dependencies point down.** Features depend on leaves, never on each other. SwiftPM stops a cycle with `cyclic dependency declaration found: Checkout -> DesignSystem -> Checkout`. - **The app target stays thin.** It composes features and owns app-level wiring. ## What it buys - **Compiler-enforced boundaries.** A feature can only use what it declares and what is `public` or `package`. - **Smaller rebuild scope.** Each target is a module; changing a feature recompiles it and its dependents, while changing a widely used leaf still ripples to everything above it. - **Testing without the app.** Targets that build for macOS, free of iOS-only frameworks, can be tested with `swift test` on the Mac, no simulator involved. ## What it costs 1. **Public API.** Types, initializers and methods the app uses must be `public`; synthesized memberwise initializers are not. Access-level rules are the Swift lesson's; the volume of annotation is your cost. 2. **Resource rewrites.** Every moved asset, color and string needs `bundle: .module`, because `Image`, `Color` and `Text` default to the main bundle. 3. **Linking choices.** PackageDescription recommends leaving a library product's type unset so SwiftPM picks static or dynamic linking; forcing `.dynamic` on many products adds frameworks to the app, while one static library linked into several images can be duplicated. 4. **Undeclared imports.** A target can compile an `import` of a module it reaches only through another product. That works until the intermediate edge is removed, so reviews check that every import matches a declared dependency. 5. **Module count.** Each target is another module to compile, emit and link. Hundreds of tiny targets cost build time and manifest churn; seams should follow ownership and change rate, not file count. ## Deciding the granularity The useful question for each candidate target is not "is this code separable?" but "does it change at a different rate, or belong to a different team, than its neighbours?". A checkout flow owned by one team and released every sprint is a good target; a folder of three extensions used everywhere is better folded into a leaf. The manifest is the map of these decisions, so treat it as architecture: changes to products and dependencies get the same review as public API. ## A migration order 1. Measure clean and incremental build times and test duration on the current app. 2. Create one local package; extract leaf targets and the vendor wrappers. 3. Move features one at a time, fixing `public` API and `bundle: .module` as each moves. 4. Gate every manifest change in review: new products, new dependencies, `platforms`. 5. Re-measure, and split into separate packages only where a team or a release cadence needs it.

  • When would you split the single local package into several packages?
    When a part needs its own owner, release cadence or reuse in another app: then a separate package, later perhaps published with versions, gives it a manifest and API of its own. The price is that `package` declarations stop working across that boundary, so shared helpers become `public` or move.
  • How do you stop one feature target from depending on another?
    Make dependency direction a review rule on `Package.swift`: features list only leaf targets. SwiftPM enforces part of it by refusing cycles, but a one-way edge between features is legal, and an undeclared import of a transitively reachable module can compile, so reviewers check imports against declared dependencies.
  • Should the vendor's binary SDK be a product the app links directly?
    Usually not. Put it behind a source wrapper target that depends on the binary target and exposes your own API. Features import the wrapper, the vendor's module name stays in one place, and replacing or stubbing the SDK touches one target.

  • Declarations marked package are visible to the app target that links the package.
  • Every file group should become its own package to maximize build parallelism.
  • SwiftPM rejects any import of a module that the target did not declare as a dependency.
  • Moving code into a package needs no resource changes because Xcode merges asset catalogs.
  • Forcing every library product to .dynamic is the recommended default for local packages.

Assumes swift-tools-version 5.9 or later: the package access modifier and the packageAccess target parameter arrived in 5.9.