Using Multiple Storyboards in iOS Development

I recently started working on an iOS project with two other senior developers here at Atomic Object. When it came time to set up our project in xCode 5, a practical issue was raised: how can we best work on the app in parallel, using the Interface Builder with storyboards?

Storyboards are described by XML files, which is great because it allows a user to look at the properties of the view controllers, views, etc. in code and make changes. We’ve also had success with our designers adding and changing assets directly in interface builder via storyboards. What isn’t so great is dealing with merging changes when multiple developers are editing the same storyboard. In this blog post, I will describe how we addressed the storyboard merging problem and give some simple tips for how to avoid the problem in the future.

What Not To Do

Hand-Coded UIs

In the post “Why Can’t We Merge Storyboards,” Brian Hynds covers some of the issues that developers face when trying to merge changes to a storyboard. The solution he suggests is to hand-code all the UI elements. However:

  • That’s tedious and inefficient.
  • It increases the amount of tests that need to be written to cover all the hand-coded elements.
  • It makes it harder for a new developer to join the team and get up to speed.

And, really, Apple has given us this powerful tool for setting up our views, UI, and app flow, so let’s see if we can use it without a lot of unnecessary file merging pain.

Pass the Banana

Another approach is to only allow one developer at a time to change the storyboard. Atomic’s own Ken Fox has worked on teams that had a physical object (let’s say it’s a banana) in the office, and only the developer with the object could change the single storyboard file. Changes had to be integrated before the object was passed and someone else could work on it. That works, but it’s inefficient, and if the developer with the banana is sick or out of the office, the others can get blocked.

The Logical Alternative: Multiple Storyboards

A great way to mitigate merging issues is to break the project up into multiple storyboards. A project’s UI and views can usually be broken up logically — for example, an app will often have view corresponding with login/signup, settings, the main view(s) the user will interact with, etc. Each feature can be captured as a separate storyboard in xCode via File -> New -> iOS User Interface -> Storyboard.

The view controllers corresponding to a given feature in your app can then be added to the corresponding storyboard. If your development process is broken down by stories and tasks, tasks can be assigned in such a way that only single developer is responsible for modifying a given storyboard.

Now we have a bunch of bananas, and ideally they don’t need to be passed around. The problem is, xCode 5 doesn’t have a built-in way to easily define segues between storyboards. The solution to this problem is RBStoryboardLink.

Managing Multiple Storyboards in xCode with RBStoryboardLink

Rob Brown’s RBStoryboardLink (available as a cocoapod) gives us a simple and effective way to connect storyboards together intuitively. The “How to Use” section describes it clearly, but I did have some confusion about how to segue to a specific scene within a storyboard. The documentation states: sceneIdentifier (Optional) The identifier of the view controller to transition to. If left blank, this will push the first view controller. What this is referring to is the View Controller’s Storyboard ID, if it isn’t set to match the sceneIdentifier, an error will be thrown. The Storyboard ID can be set in the View Controller’s Identity Inspector.

Here is a simple example of a RBStoryboardLink view controller that will handle the transition to the YellowStoryboard.storyboard’s YellowViewController2 scene:


To make this work, we set the Storyboard ID of the target view controller:



Most merging nightmares can be avoided (or at least mitigated) by categorizing an iOS app’s view controllers in logical, easy to manage features and placing them in well-named storyboards. If possible, a single developer should be assigned the tasks associated with manipulating a feature’s storyboard file. Use RBStoryboardLink to easily link the storyboards together with whatever segues you wish.

  • Chris Carr says:

    Why not just use XIBs? Is having ViewControllers and Segues (transitions) in Interface Builder that important?

    • John Fisher John Fisher says:

      One reason is our process incorporates a designer- storyboards are a lot more natural for her to interact with.

  • If possible, a single developer should be assigned the tasks associated with manipulating a feature’s storyboard file. Use RB Storyboard Link to easily link the storyboards together with whatever segues you wish.Thanks for sharing all that great information..

  • Joel G. says:

    Thaks for the tip :D

  • Sha says:

    How about if your controller is a tab bar controller and every tab goes into different storyboards?

    • John Fisher John Fisher says:

      Hi Sha,
      My colleague Ken Fox wrote a nice follow-up to this post about a solution we developed in-house at Atomic Object for doing storyboard transitions, see it here:

      Without knowing the details of your situation, I think Ken’s solution should work for you- just set up the custom segues pointing to the other storyboards and perform them as needed (when the user switches tabs).

  • Troy Carlson says:

    For anyone attempting to link storyboards in Xcode 7+ this is now supported natively.

    Cheers from Grand Rapids!

  • Great article, thanks for sharing! On our area we must always look for new tools as they seem to appear on a daily basis and help so much on our job!
    Congrats on the blog!

  • Thanks for the article. We follow Pass the Banana approach in IOS development and i think because we have a small team this approach is most suitable to our company.

  • Mikey Peter says:

    I agree i think i will follow your mention strategy a single developer should be assigned the tasks associated with manipulating a feature’s storyboard file to avoid nightmare in my chat mobile app development.

  • Comments are closed.