Migrating an Objective-C SDK to Swift: planning for StoreKit 2
When a platform framework moves to a new language-only API, the question is rarely whether to move. It is how to move without breaking existing users, multiplying packages, or turning the project into an open-ended rewrite. This guide explains one SDK team's decision, the requirements they set before touching code, and the testing setup that let them prove the public API had not drifted.
The trigger: a Swift-only StoreKit 2
At WWDC 2021 Apple announced StoreKit 2, supporting Swift and iOS 15 only. The SDK in question was already distributed through CocoaPods, Swift Package Manager and Carthage as a mixed-language framework, so supporting the new API alongside the older StoreKit, earlier iOS versions and Objective-C users would have required a complicated new structure.
Three paths were considered:
- Build a new SDK for StoreKit 2 only and keep the existing SDK for StoreKit 1 users.
- Split the framework into separate modules with a more complex dependency graph.
- Move fully to Swift and keep a single module for now.
The team chose the third path, accepting a large up-front investment for long-term simplicity. The deciding question was what the future SDK should look like, not just how to add one new API.
Why one language and one module
A single language simplifies every distribution channel. Swift Package Manager allows one language per package, so a mixed framework needs extra configuration that is easy to break. The SDK also had to work with Flutter, React Native, Cordova and Unity, and each additional language or module makes setup, testing, debugging and release harder.
Before the move there were two modules, Purchases in Objective-C and PurchasesCoreSwift in Swift, created because Swift Package Manager could not distribute one mixed package. New features often needed work in both, and references only flowed one way: Purchases could use PurchasesCoreSwift, not the reverse. Collapsing to one module removed the need to decide where each new class belongs, how it reaches its dependencies, and which language to write it in.
Staying mixed would have been worse for StoreKit 2. The newer API is Swift-only, while caching and networking were in Objective-C and the Objective-C module was the entry point. Reusing that code without migrating would have meant a new Swift layer calling Objective-C that itself depended on Swift, plus Swift Package Manager's one-language rule, producing three packages and three CocoaPods. That could work, but testing, building and distribution would all become more complex.
A simpler structure also helps people. New teammates learn one modern language instead of two, builds fight them less often, and the release pipeline is easier to follow. Hiring widens too, because more engineers know Swift than Objective-C and Apple presents Swift as the language to learn for iOS.
Requirements and a pre-move checklist
Use this checklist before starting a language migration:
- Write down the compatibility promise: keep the public API stable wherever possible.
- Freeze the internal API unless a change is unavoidable.
- Defer modernisation: move first, refactor later, so reviewers can compare old and new code directly.
- Map every file's dependencies before assigning work, so tasks can be parallelised safely.
- Build an API surface check that fails when public signatures change.
- Run the existing test suite as the behavioural baseline, and add tests for under-covered areas.
The reasoning was practical. Fewer moving parts means fewer new bugs, a consistent API lets StoreKit 2 work proceed in parallel, and a review rule emerges naturally: if migrated code looks very different from its Objective-C equivalent, flag it and discuss. New Swift syntax and language features were deliberately postponed until after the migration.
Mapping dependencies file by file
Work was organised publicly in GitHub so anyone could follow or contribute. Instead of grouping by feature, the team created one issue per file to be migrated. That quickly revealed a second need: dependencies. The framework had grown organically over four years without a major refactoring, so each class sat in a web of dependencies. Starting without a map would have devolved into chasing dependencies indefinitely.
Because Objective-C implementation files import everything they use, the team went file by file, creating an issue for each and listing its dependencies as checkboxes in the description. That map showed what could move in parallel and what had to wait, turning a tangled codebase into an ordered sequence of small tasks.
Compatibility checks: tests plus an APITester
Perfect compatibility was not achievable. Swift Error domains exported to Objective-C are auto-generated from the Swift module, so their shape could not be preserved exactly. The move also exposed nullability mistakes: some APIs sat inside non-null regions yet could return nil, and some parameters could accept nil despite their annotations. Those cases had to change, but fixing them removed entire classes of bugs that could otherwise have survived.
Two safety nets made the risk manageable. First, more than 700 Swift unit tests already covered both modules, giving confidence that behaviour matched the old code and a chance to add tests where coverage was thin. Second, a new APITester target was created before migration began: a minimal Objective-C command-line app depending on the framework, with one file per public object exercising every public API. It never needed to run; it only needed to build. If it built unchanged, the public API had not changed. It ran in continuous integration on every commit and doubled as documentation of breaking changes. A Swift APITester was added a few weeks later, and both ended up catching unintended changes, so they were kept as regular test targets.
What to take away
The pattern that worked was: state the goal plainly, separate migration from modernisation, break the work into dependency-ordered pieces, and verify equivalence with automated tests and an API surface check. That turned a large, seemingly intractable problem into a sequence of manageable steps and kept customer impact minimal. The harder surprises, including team friction, merge conflicts and external contributions, came during development itself, which is a reminder to budget for coordination, not just code.
Frequently asked questions
Why not ship a separate StoreKit 2 SDK or split the framework into modules?
A separate StoreKit 2 SDK would leave two SDKs to maintain. Modularising would add packages and distribution complexity. A single-language migration kept one module and one distribution path, at the cost of a large up-front effort.
What guardrails kept the migration from becoming a rewrite?
Keep the public API stable where possible, avoid internal API changes unless necessary, and defer code modernisation until after the move. That limits new bugs and keeps parallel StoreKit 2 work possible.
Why was backwards compatibility only mostly preserved?
Some changes could not be avoided, including auto-generated Swift Error domains exposed to Objective-C and nullability cases where an API could return or accept nil despite its annotations. Those surfaced latent bugs and removed whole classes of future errors.
What did the APITester target check?
A small app that exercises every public API without needing to run. If it still builds unchanged after a file moves, the public surface has not changed. Objective-C and Swift versions were added to continuous integration and later to the local test run.