How to Build and Publish a Happy iOS Framework: From Basics to Best Practices

Using Frameworks

Before building a framework you must be a good user of existing ones. Early iOS developers struggled with manual .a static libraries and the fear of unresolved symbols.

What Is a Static Library

A static library (.a) is a collection of compiled object files bundled with header files; it is linked into the final app binary and cannot be loaded independently.

What Is a Dynamic Framework

Dynamic frameworks (.framework) are bundles that can contain resources and are loaded at runtime, offering better modularity and faster app launch.

Universal Framework

Before iOS 8 some third‑party .framework files were actually static libraries wrapped for convenience.

Library vs. Framework

Static libraries cannot include resources and must be duplicated for each target, while frameworks can embed assets and be shared across extensions, reducing duplication and improving load times.

Package and Dependency Management

The most common tool is CocoaPods , a Ruby‑based system that uses a Podspec to describe a framework’s source, version, and dependencies. Adding use_frameworks! in a Podfile forces CocoaPods to build dynamic frameworks.

# Podfile
platform :ios, '8.0'
use_frameworks!

target 'MyApp' do
  pod 'AFNetworking', '~> 2.6'
  pod 'ORStackView', '~> 3.0'
  pod 'SwiftyJSON', '~> 2.3'
end

Carthage is an alternative that only supports dynamic frameworks. It clones the repository, builds the framework, and requires the developer to manually add the binary to the project.

# Cartfile
github "ReactiveCocoa/ReactiveCocoa" ~> 1.8
github "onevcat/Kingfisher" ~> 1.8

Swift Package Manager (SwiftPM) is emerging; it organizes source code under a Sources folder and defines a Package.swift manifest.

// Package.swift
import PackageDescription
let package = Package(
    name: "MyKit",
    dependencies: [
        .Package(url: "https://github.com/onevcat/anotherPackage.git", majorVersion: 1)
    ]
)

Creating a Framework

In Xcode create a new Framework target, add source files, and build. Frameworks target other developers, so API design, resource bundling, and versioning are critical.

API Design

Follow the minimalism principle : expose only the public interfaces needed initially, then expand as usage grows. Use clear verb‑based method names (e.g., remove(at:) instead of ambiguous remove) and avoid noun‑verb overloads.

// Good
public func remove(at index: Index) -> Element { … }

// Bad
public func remove(_ i: Int) -> Element { … }

Testing

Write unit tests for all public APIs; use @testable imports to test internal logic when appropriate.

import XCTest
@testable import YourFramework

class FrameworkTests: XCTestCase { … }

Version Management

Adopt Semantic Versioning (MAJOR.MINOR.PATCH). MAJOR changes break API, MINOR adds features without breaking, PATCH fixes bugs. Keep version numbers in sync with Git tags and, for Swift frameworks, expose them via FOUNDATION_EXPORT constants.

Continuous Integration

Use CI services such as Travis CI, CircleCI, or GitHub Actions to run tests, lint podspecs, and automate releases. Tools like fastlane can script version bumps, tagging, and publishing to CocoaPods.

# Fastfile
lane :release do |options|
  version = options[:version]
  raise "Version missing" unless version
  ensure_git_branch
  ensure_git_status_clean
  scan
  increment_version_number(version_number: version)
  git_commit_all(message: "Bump version to #{version}")
  add_git_tag(tag: version)
  push_to_git_remote
  pod_push
end

Publishing the Framework

Publish on GitHub (or other code hosts) and submit a podspec to CocoaPods. Support multiple dependency managers (CocoaPods, Carthage, SwiftPM) to maximize adoption.

Conclusion

Creating a high‑quality iOS framework involves thoughtful API design, thorough testing, proper versioning, and automated CI/CD pipelines. By following these best practices developers can produce reusable, maintainable components that benefit the broader iOS community.