Creating an iOS Framework with CookieCutter Swift

Thiago Lioy
Cocoa Academy
Published in
4 min readMar 10, 2017


Creating a framework in iOS is not something new to me. Throughout my career, I had the opportunity to build several of them. There are many different reasons why you would like to create a framework:

  • Create an abstraction that can be reused from project to project.
  • Share with the community something you built.
  • Split your project into modules.

Until today, everytime that I had to create a iOS framework i would find myself repeat the same template:

pod lib create *

Yep. That’s right cocoapods for the win!

A couple of days ago I got a friend suggestion about CookieCutter Swift. A template for creating iOS frameworks that not only would allow my project to support Cocoapods but Carthage and Swift Package Manager as well.

In this post, I will show how to create an iOS framework using CookieCutter and what are the benefits of doing so. The framework that I am going to create in this post can be found here. Check it’s Readme. Almost everything comes from the CookieCutter template, awesome!! Real production Readme from scratch, sweet!

Enough talk .. Show me the code !!

First let’s make sure everyone is on the same page, which means:

brew install carthage
brew install cookiecutter

* For future runs you can shorten the command to cookiecutter FrameworkTemplate. However, if you want to use the most recent template you should still run the full command above.

After running the command you will end up with a folder strucuture like this:

There are a bunch of folders and files:

  • Cartfile
  • Podspec
  • PackageSwift
  • Readme
  • Xcode Project
  • Sources/ and Tests/ directories
  • Among other things ..

The cool thing is if you are like me coming from "pod lib create" world, being able to use Carthage to import Nimble and Quick is a big enhancement, not more syntax and completion problems in your tests!

The way the podspec is configured using subspecs is also something worthy mention. Several pods out there would benefit a lot from this approach; many libraries do that with excellence, for instance, Moya. You guys can check their folder structure is very similar to this template.

Xcode Project

The Xcode project is pretty straightforward, especially in this example. Swifixture is a library that helps to load JSON from files. It also parses them using specific mapping frameworks defined as Subspecs. Right now it is currently only supporting ObjectMapper, but I’m(and hope others also) going to provide support to other libraries.

Things to keep an eye on !

Every time you need to specify a new dependency for your podspec, as I did for the ObjectMapper subspec. You are going to need to add it using Carthage. All you need to do is:

  • Add it to your Cartfile. Like this:
github “Hearst-DD/ObjectMapper” ~> 2.2
  • You will have to import this library to your xcodeProject. Otherwise, people installing your lib using Carthage as dependency manager will have problems. You can do that by clicking on the "+" button under "Linked Frameworks and Libraries".
  • Also, make sure to import the Carthage files on your test target using “Runpath Search Paths”. Otherwise, you will have problems running them.
  • The last thing you need to worry is how to test your framework without the need to push it to Github. Test locally can save you a lot of time and deserves another topic by itself, hang it tight.

Testing locally


In the project that will consume the Carthage lib edit the Cartfile. Instead of specifying a Github’s url, Carthage allows us to specify a git url with the path to your library folder. In doing so, we do not need to push any code to our GitHub repository to test it. Check locally and push when everything is ok!

git “file:///Users/Thiago.Lioy/dev/mobilelabs/tmp/Swifixture” “master”


Cocoapods also allow us to test locally our library before push. We just need to specify in the Podfile. We can do that by using the path argument:

pod 'Alamofire', :path => '~/Documents/Alamofire'

Final words ..

This CookieCutter swift framework template was a great enhancement for my iOS toolset, hope you guys have liked it. It is a much better approach than the old “pod lib create” kind of thing, and it can make your project compatible with Carthage and swiftPackage manager out of the box.

As always any thoughts, doubts or feedbacks are more than welcome. =)

Ps: If you like this post, share it on Twitter, recommend it on medium, or both =). Doing so helps me to reach more people. Thanks a lot.



Thiago Lioy
Cocoa Academy

iOS developer, design enthusiast, blogger, weekend cook, guitar player, traveler. Creator of iOS mag: