Getting Swift Packages into Swift Playgrounds on iOS

As far as I can tell, there is currently (iOS 12.4.1) no official way to get Swift Packages (or any external library) into a Swift Playground on the iPad, so is very much a workaround, emphasis on the work.

Origin Story

Recently, I was travelling with just my iPad and had an idea for a new component for handling parallax effects in my SpriteKit games.

This idea came to me in a fever dream. I woke up at 5am with the entire component sketched out in my head and many of the implementation details already filled in. (Surprisingly for dream code, very little of it required editing later.)

I wanted to get working on it immediately, and I thought that the component was flexible enough to deserve a place in my ECS library. My library makes it easy to spin up a basic scene with moving characters.

Getting this library into a Playground, on the other hand, proved to be a lot more challenging.


In addition to the Swift Playgrounds app, you’ll need the following:

  • Working Copy (the free version is fine). This is a comprehensive git client that makes it easy to clone repositories and make edits. More importantly for our purposes, it also exposes the files in any repository it has cloned to the Files app. Nice!
  • A text editor (I use Textastic)
  • An app that allows you to navigate into the directory structure of a Playground and allows you to copy or move files (Textastic also works here)

Option 1: Copy and Paste

You can add and edit Swift source files to user modules within a Playground.

You can also import resources to use in Playground. These can include text files like, say, Swift source files.

What you can’t do is import these resources into user modules, which means you can’t import Swift source files in a way that the Playground will execute.

Using Working Copy, I cloned my repo which made it available in the Files app. I then set up a split screen with the Playground on one side and Textastic on the other.

I manually created new Swift files in the user module of the Playground, opened up the source file in Textastic, then copied and pasted the code from Textastic to the new user module file.

Needless to say, this got very old very fast. For one or two Swift files it’s workable but my component library has a couple of dozen.

Option 2: Moving the Files into the Playground

Swift Playgrounds are bundles with a set structure. In most apps on iOS, they’ll appear as single files. Fortunately, in Textastic, it’s possible to see them as a collection of files and directories and therefore drill down into the directory structure.

This makes it possible to move files deep into the Playground directory structure through the Textastic interface. Here’s how:

Create a new Playground in the Playgrounds app. Tap on the small file icon in the top left and you’ll see that it automatically creates a new UserModule with an empty Swift file for you. We’ll add the package files to this.

Close this file and make sure that it’s uploaded to iCloud. It’s a good idea to make sure it’s all in sync before messing with the structure outside of the Playgrounds app.

In Working Copy, clone the repo of the Swift Package you want to use.

Next we’ll have to copy the files from Working Copy to the playground using Textastic. Unfortunately, Textastic doesn’t have an easy way to bulk copy files, only move them.

You might not want to be moving files out of the Working Copy repo directory as you will be making changes to this repo. While it’s highly unlikely, to prevent any accidental pushing of empty directories where once they were full of library files, we’ll make a copy.

Open the Files app, selecting Working Copy as the source, then long pressing on the folder containing the source files in the package repo and tapping copy.

Then, anywhere else in iCloud Drive, long press and tap paste to make a copy of these files. This will allow you to move the files without affecting the repo in Working Copy.

Back in Textastic, select Open File or Folder then search in iCloud Drive for the Playgrounds folder. Select the Playground you just created. This will open the bundle in Textastic as a regular folder that you can drill down into.

Then open either the location of the folder you just copied, or the repo folder in the Working Copy source. Tap Edit, then select the files you want and tap Move.

Drill down into the Contents -> UserModules -> UserModule.playgroundmodule -> Sources directory and then tap Move

Returning to the Swift Playground, all of the files from the repo should now be available to you in your Swift Playground.

Caveats Because of Course There Are

The UserModules/Sources directory in the Swift Playground bundle does not support sub-directories, so unfortunately you can’t just copy the root directory of the source files in the repo and paste it in the Sources directory. You will have to drill down into each sub-directory of the repo and copy all the individual files so that it’s a single directory of files.

Also, as mentioned before, Textastic only allows a move operation so be careful that you don’t accidentally commit any changes in Working Copy.

This Is…Not Great.


It works, though. And it’s easier than copying and pasting.

Get all of my latest posts direct to your inbox! Pop in your email address here: