Cem Kesemen

Hosting Private Sketch Libraries

I started a new job a few weeks ago.
I got a brand new Mac (Touch Bar is awesome), get to work with awesome colleagues (so much design talent), and have so many thing I can improve.

One of the improvements I could tackle right away was fixing the way we used the shared libraries.

The design teams exclusively work with Sketch, and we have a few internal libraries to make sure UIs are easy to create and consistent throughout different files. However, the easiest method to share them has been through the file sharing platform used internally, which made it necessary to put some warnings on the installation page:

"Symbol Editing" portion of the framework installation guide, warning users not to select the default option of "Open in Original Document" when double-clicking an item, since it would alter the library file for everyone.
Apparently, there has been an incident before. It was ugly.

“Why not use sketch.cloud, you ask… It has the option to create a downloadable library, it is free, and libraries shared from there won’t have the option to alter and break everyone’s designs by default.

Well, it is also blocked by default so some users cannot use it, locked to a single account that may not be owned by the company, and not in a controlled host the company can control.


Self hosting… sort of.

I was made aware that Sketch could update libraries from sources beside sketch.cloud when it prompted to update the iOS library created by Apple. If you dive deep into the documentation, there is also a small paragraph saying that you can host your own libraries and propagate changes using RSS, and shows an example file from sketch.cloud to explain how that works.

I immediately wanted to set up a proof-of-concept to see how good this would actually work. I had a very short time —two days at most, before a new sprint kicked off. So I needed to use what I knew.

First, a demo of the final result.

The Ingredients

What I had at hand were a few tools I had used before, and knew very well:

  • Airtable, to host a list of updated Sketch documents, and act as a database
  • Hugo, to generate the RSS XML, which Sketch would consume later
  • Netlify, to build and host the Hugo site
  • and finally Gitlab, to host the Hugo files which Netlify will use to generate the site.

Airtable: Where the Data Lives

Airtable is actually the most crucial part of this demo.

Sketch needs just 3 things from an XML file to see it as an updateable library: A date, a version number, and a file URL.
So I created a new spreadsheet with an auto-incrementing ID, an attachment field, and an auto-filled date field.

The Airtable grid with 4 fields; sparkVersion for version number as primary field and auto-incrementing numbers, an empty Release Notes field, an attachment field that has the files, and a date field that auto generates dates. There are 13 lines filled in the table.
You can play around with the table on Airtable.

To add files to this table, I needed a form, which is just another view in the Airtable spreadsheets. I created the form and gave it a password, so there would be some resemblance of security.

The form shown after the password is entered. The only field is a file upload one.

That was really it for the updating part. Now, we needed to get the data off of Airtable and into a format that Sketch understands.

Hugo: The Glue That Holds It Together

Hugo has grown to be an amazing site builder. I remember using WordPress as a framework for apps before, and then doing the same with Kirby1. And now I guess it’s Hugo’s turn.

There really wasn’t much to do to generate the XML. I created an index.rss.xml layout in layouts folder, in which I used getJSON to receive the list of updates on Airtable, using Airtable’s API.

I opted to sort2 the data while grabbing it with the API, instead of relying on the table sorting, as it did not work as intended and mentioned in the documentation.

After receiving the data, all that was left to do was just push results into certain fields in the template.

Gitlab: Hosting the Working Parts

I know, this is getting confusing. Bear with me.
We have Airtable that hosts the files and acts as a database for versioning, and we have Hugo that creates a file that can be read by Sketch from that table.

Now, because Hugo is not a framework that runs on a dynamic hosting, and cannot build pages at the time of the request, we need to build the page as we upload new designs to Airtable. We have a build system that is run by our hosting provider (explained in the next section), but for it to work, it needs a place to grab the source files. This is where a “git repo” comes in.

Either Github or Gitlab would do, but Gitlab provides free private repos, so that’s what I went with.

After completing the development and testing with Hugo on my Mac, once I was satisfied with the result, I git push‘ed the whole thing to a new repo on Gitlab.

Netlify: The Room Where It Happens

Netlify is the other crucial component here; although not really irreplaceable, it undertakes two very important tasks, and handles them gracefully.

It not only hosts the XML file and the page that links to it, but it also grabs the Hugo source from Gitlab and builds it to generate the up-to-date XML file.

Remember the form we used to upload the updated library?
When filled in and submitted, Airtable shows a link that takes the uploader to a page in the Netlify-hosted site.

This page has a button3 that links to a Netlify-provided webhook that basically tells it to tell grab the source from Gitlab, do it’s Hugo magic, and use the output as the new website.

Using the Library in Sketch

To add the library to Sketch, all that is needed is a link to sketch://add-library?url=<HTML encoded URL to XML file>.

Sure I could just use a plain blue underlined hyperlink on white page for demo purposes, but we designers tend to be a little dramatic, so of course I spent a couple of minutes copying a Bootstrap demo and making it look more like a landing page for the library.

The landing page for the library, has a prominent "Add Library to Sketch" button as a link in the middle of the page.

Clicking on the button gives a prompt to open Sketch.app.

And just like that, it’s added to our Sketch libraries!

Updating the Library Copy

When the owner of the library pushes and propagates an update, Sketch sees4 it and gives a notification.

When the update is downloaded, the top-right bubble indicates that some items used from the library are, in fact, changed. It also allows the user to pick and choose which of these to apply.

Did It Work?

I demoed the whole thing to a couple of designers and developers that were responsible of the library and documentation platform, and they managed to grab the logic of it and implement it in a couple of hours.

We now not only have a secure way of sharing our libraries internally, but we can also give controlled access of them to our vendors.

I was also able to show the power of Airtable and Hugo and Netlify to our team, and we are making use of all of those for creating new prototypes for our projects.

  1. Although with Kirby things are a bit different, because there’s a toolkit for simple apps building that Bastian provides. I still use this to create dynamic apps, some even use Airtable! ↩︎

  2. Airtable has a nifty little tool to help out with URL encoding for filtering and sorting the API requests. ↩︎

  3. The label for the button is “Propagate” to tell the user what the effect is, not the action. UX! ↩︎

  4. It checks for updates daily, or at every launch. ↩︎