How to collaborate on a project with Xcode Storyboards?
For a project I am developing for iOS, I want to collaborate with some freelancers. For collaborating on ‘pure’ code I want to use GitHub. But a big portion of the work, will be on the Storyboards and the connection with the code. What is good practice here? How do I share the Xcode project with them, so they can work on some elements (branches maybe), somewhat similar to the GitHub method? Or is there a good alternative?
Anybody got any advice in this matter? Help is much appreciated!
1 Answer 1
As one of the comments pointed out, Storyboards are just XML files. That means git can easily upload them to Github. As to your initial question, you have to be careful not to modify the same views as your freelancer did, for if you do so, it will give you a merge conflict. What will happen then is that GitHub will modify the storyboards XML file inserting the <<<<<<< HEAD / >>>>>>> commit Id tags to show you where you have both changed something. This will then mess up the graphical storyboard and likely lead to Xcode no longer being able to open the Storyboard. This will throw the following error:
«Main.storyboard»could not be opened. The operation couldn’t be completed. (com.apple.InterfaceBuilder error -1.)
To avoid that, simply edit other views, or always pull before starting to edit anything in the Storyboard. And even when using branches, when you’ll try to merge you’ll run into the same problem. However, it’s noteworthy that you could just be working on different branches and the manually apply all the changes to one storyboard. This is tedious, but it works.
Deploy Storybook
Throughout this tutorial, we built components on our local development machine. At some point, we’ll need to share our work to get team feedback. Let’s deploy Storybook online to help teammates review UI implementation.
Exporting as a static app
To deploy Storybook, we first need to export it as a static web app. This functionality is already built-in to Storybook and pre-configured.
Running yarn build-storybook will output a static Storybook in the storybook-static directory, which can then be deployed to any static site hosting service.
Publish Storybook
This tutorial uses Chromatic, a free publishing service made by the Storybook maintainers. It allows us to deploy and host our Storybook safely and securely in the cloud.
Set up a repository in GitHub
Before we begin, our local code needs to sync with a remote version control service. When we set up our project in the Get started chapter, we already initialized a local repository. At this stage, we already have a set of commits that we can push to a remote one.
Go to GitHub and create a new repository for our project here. Name the repo “taskbox”, same as our local project.
In the new repo, grab the origin URL of the repo and add it to your git project with this command:
Finally, push our local repo to the remote repo on GitHub with:
Get Chromatic
Add the package as a development dependency.
Once the package is installed, log in to Chromatic with your GitHub account (Chromatic will only ask for lightweight permissions), then we’ll create a new project called «taskbox» and sync it with the GitHub repository we’ve set up.
Click Choose GitHub repo under collaborators and select your repo.
Copy the unique project-token that was generated for your project. Then execute it by issuing the following in the command line to build and deploy our Storybook. Make sure to replace project-token with your project token.
When finished, you’ll get a link https://random-uuid.chromatic.com to your published Storybook. Share the link with your team to get feedback.
Hooray! We published Storybook with one command, but manually running a command every time we want to get feedback on UI implementation is repetitive. Ideally, we’d publish the latest version of components whenever we push code. We’ll need to continuously deploy Storybook.
Continuous deployment with Chromatic
Now that we’ve hosted our project in a GitHub repository, we can use a continuous integration (CI) service to deploy our Storybook automatically. GitHub Actions is a free CI service that’s built into GitHub that makes automatic publishing easy.
Add a GitHub Action to deploy Storybook
In the root folder of our project, create a new directory called .github , then create another workflows directory inside of it.
Create a new file called chromatic.yml like the one below.
�� For brevity purposes GitHub secrets weren’t mentioned. Secrets are secure environment variables provided by GitHub so that you don’t need to hard code the project-token .
Commit the action
In the command line, issue the following command to add the changes that you’ve made:
Then commit them by issuing:
Finally, push them to the remote repository with:
Once you’ve set up the GitHub action, your Storybook will be deployed to Chromatic whenever you push code. You can find all the published Storybooks on your project’s build screen in Chromatic.
Click the latest build. It should be the one at the top.
Then, click the View Storybook button to see the latest version of your Storybook.
Use the link and share it with your team members. It’s helpful as a part of the standard app development process or simply to show off work ��.
How to publish Storybook to Github Pages
In this post, I’m going to share about how to deploy Storybook to Gihub pages via Github Actions.
Assume that you already have Storybook installed. If not, please follow this guideline. It really depends on the framework you’re using.
After installation, the package.json must contain a command build-storybook . This command will be used to generate production build / static files of Storybook
Create gh-pages branch
There are many ways to setup Github Pages such as:
- Use existing branch and target root folder or /docs folder
- Create a new branch gh-pages and target root folder or /docs folder
I prefer (2) using root folder in this case because for (1) you needs to track static files of Storybook in Github which I feel unnecessary.
Ensure you have created the gh-pages branch via Github UI or CLI.
Then from Github Repository Settings, set the source to target gh-pages and select root folder. You’ll also see the Github Pages URL on this page.
Create Storybook Github Action workflow
Now create a new file .github/workflows/storybook.yml , and define Github Actions below
Publish Storybook
Push any change to main branch to trigger Storybook deployment
If everything is OK, Storybook will be published to Github Pages at the given URL on Settings page.
Deploy Storybook to GitHub Pages
You have your Storybook project ready, and hosted at GitHub, great! Now you want to publish it so that everyone can view it online. Let’s see how we can leverage GitHub’s built-in features to host the static web app and automate the deployment process.
Enable GitHub Pages
First, we have to create a docs folder at the root of our repository which will be used to host the published Storybook files.
Then we have to enable the GitHub Pages hosting feature and configure it to serve the static files from the docs folder in our repository. Navigate to your GitHub repository settings and find the GitHub Pages section. Select the main branch, then the docs folder and, click Save.
Note: GitHub Pages needs our repository’s visibility to be set to Public.
Set up the Storybook build script
Before we can deploy our Storybook project to GitHub Pages, we must first edit the build-storybook script entry inside our package.json file. This command will generate our project files. Open the package.json file and edit the «build-storybook» entry as follows:
Exit fullscreen mode
This will tell Storybook to put the statically generated files into a docs-build folder. We don’t actually need to create a docs-build folder in our repo as it will only be used temporarily for the deployment.
Note: If you have any static assets that you want Storybook to include in your build, you can do so with the -s switch followed by the static assets folder path. For example:
Exit fullscreen mode
Set up the GitHub Actions workflow script
Github Actions is a fully integrated software development lifecycle workflow feature that enables us to create custom CI/CD processes directly integrated with our GitHub repository.
It’s not in the scope of this post to go into detail about how GitHub workflow scripts work, there’s great documentation available and plenty of tutorials around the net.
We’re going to use GitHub Actions to automatically build and deploy our Storybook files. The action will trigger every time someone pushes a new commit into our main branch of our repository that contains changes made to our stories and src/components folders.
We’ll first create a YAML file to define our workflow configuration. Create a storybook.yml file inside your repository in the following path
/.github/workflows/
Fortunately, there are many ready-made actions by the community, we are going to use the GitHub Pages Deploy Action action example script, slightly finetuned to suit our needs.
Put the following code into the /.github/workflows/storybook.yml file we created earlier.
storybook.yml
Exit fullscreen mode
The key things to note here are:
- We are triggering the workflow only when files change inside the stories and src/components folders. You can customize the script accordingly if your stories and/or source files reside in another folder. Alternatively, you can trigger the workflow on every push by setting the on section to:
Exit fullscreen mode
- We’ve set the FOLDER Key to docs-build which is the folder we defined into our package.json «build-storybook» command.
- We’ve added the TARGET_FOLDER Key and set it to docs , which is the folder that our Storybook project is served from.
Next, commit the storybook.yml file along with the package.json into your repository and push it to GitHub.
Publish files
The final step is to make a change in our Storybook stories files then push a commit into our repository in order to trigger the storybook.yml workflow. We can monitor the workflow progress by going into the Actions tab on the GitHub website.
If everything went well, the workflow should complete successfully, and a new commit with the published Storybook files inside the docs folder will be created and pushed in our repository.