Creating, Versioning, and Publishing a Sketch Plugin for N00bs (Like Me)

Recently I built and published Disconnector, a Sketch plugin which lets you quickly undo all the blood, sweat, and tears that your design systems team puts into building symbol libraries. 😉

But as a design systems designer myself, I’ve found it helpful to have this to break apart something I’m working on or see how other designers built a complex symbol. It’s also been useful when importing another designers screen to a project file and I don’t want their local symbols to clutter my symbol page.

While I was building the plugin I ran into a lot of issues and gaps in information on how to do it. A lot of these gaps were probably because I’m a designer, not a developer, but they were nevertheless important if I wanted to successfully publish my plugin. This article aims to fill in some of those gaps in the internet and clearly outline the process for creating, building, and publishing a plugin.

I won’t be covering much of how I built the actual plugin because that’s mostly just basic javascript and some well-documented Sketch api calls. Most of my issues were with getting set up, versioning my plugin, and getting my plugin out into the world.

Getting Started

Sketch makes it pretty easy to get started building a plugin. Just follow the directions here.

If you’re using git, go to your terminal and typeskpm create new-plugin-name --git

Creating a new plugin with skpm

And there you have it! A new plugin with all the files you don’t want to worry about, so you can get right to the good stuff: your ideas!

If you like to see all the files in your directory, you can either see them in the terminal, or do defaults write com.apple.finder AppleShowAllFiles YESin the terminal to see them. Hide them again with the same command, but change YES to NO.

Versioning

This is a good point to get your git version control going. Our new-plugin-name plugin is already a local repository because we told skpm to set it up that way, but if we want to publish it to the web it’s a good idea to set it up in Github. I also really like setting it up with Sketchpacks, a plugin manager for designers. Let’s get both of those set up now.

Setting up Github

Creating a new Github repository

To get started, log into Github and create a new repository.

• Enter your plugin name
• In order for people to download your plugin after you publish it, it does need to be public. If you want to you can make it private for now and change it later, but I’ve just made mine public from the beginning.
• Skpm already initialized our repo with a README.md file, so choose no.

Connecting the online repo with your local computer repo

On the next screen, make sure you have HTTPS and copy the url in the box.

Now go back to your terminal and type the following:

git add .
git commit -m “First commit”
git remote add origin <the url you copied from github>
git push -u origin master

Now everything should be in your Github!

Setting up Sketchpacks

Next, let’s go configure Sketchpacks Relay. Click Configure, log into Github, and select your repo.

That’s pretty much it. Now we go build our plugin!

Build Your Plugin

You’ll notice in our folder there’s our .sketchplugin file. This is the actual plugin that Sketch installs. It’s actually a package that contains other files (opened by right-clicking and selecting “Show Package Contents”), including a manifest.json and my-command.js file.

It’s best not to mess with these files as they are just a build from skpm. The files we want to change are in the src folder.

While I’m developing a plugin I really like for the .sketchplugin to automatically build. We can do this by typing npm run watch.

Now when we save our plugin files npm will automatically build our .sketchplugin file.

Your Plugin Commands

All your plugin code (the reason you’re trying to build a plugin in the first place) goes inside the my-command.js file. This is the meat of your plugin and can be whatever you’d like it to be.

You can rename the file, just make sure to also change it in your manifest.json file.

The Sketch Manifest File

The manifest file is essentially a metadata file that Sketch and Sketchpacks use to:

• Identify your plugin
• Know how you want your plugin to show up in the Sketch window
• Track versions and identify whether your plugin needs an update
• Attach keyboard shortcuts to your plugin
• And many others

You can start the version at whatever you want it to be, but keep in mind that Sketchpacks requires you to keep a standard versioning protocol (i.e. “major.minor.patch” numbering). Note that you’ll have to update this manually when we start publishing. Even though github will update its’ version number for your plugin, Sketchpacks (and then Sketch) reads the version number from this manifest file.

I still don’t quite understand how the identifier works or what it needs to be, but it seems like you can make it whatever you’d like it to be as long as it’s unique from your other plugins? I still need to research this more.

The script in the commands object should be the filename of your my-command.js file. This is especially important if you have multiple commands in your plugin.

The Package.json file

The package.json file is an npm package file that tells npm how to handle your whole plugin folder. It’s similar to the manifest.json file that Sketch uses, but it’s just for npm. We’re not going to change a lot here, but we’re going to tell npm our git repo information so that it’s easier to publish.

Let’s go back to Github and grab our repo url

Then open up your package.json file and add:

“repository”: {
    “type”: “git”,
    “url”: “https://github.com/njcrowther/new-plugin-name.git"
},

There’s one more thing we need to do to let skpm do the heavy lifting when we publish.

Go back to Github and go to your personal Settings

Then go to Developer Settings.

Choose Personal Access Token and create a new one. Give it a name and select all the repo boxes. Then click Generate Token.

Make sure you copy the access token!

SKPM Login

Now we need to let npm login to our repo so that it can automatically publish going forward. Go back to the terminal and type

skpm login <your token>

Publishing your plugin

Now it’s time for us to publish our plugin and share our great idea with the world!

In the terminal type skpm publish major. You can choose whether to add it to the registry or not. I’m choosing not to.

And it’s published!

On Github you’ll notice that everything was build and pushed to Github.

It takes a few minutes, but you should then notice on Sketchpacks that your plugin is listed there for the world to download and use!

Conclusion

And that’s it! In less than a couple hours you can have at least the delivery method of your plugin set up and running, so all you have to do is program the Sketch Magic!

I hope this article has been useful so you can spend less time scouring the web for obscure terminal commands and more time building something useful!

I’m an Associate Designer at Walmart Labs in Bentonville AR. Connect with me on Twitter or take a look at my portfolio at www.nathancrowther.design