The Beginner’s Guide to Writing Sketch Plugins Part 1 — Getting Started
So you want to start writing Sketch plugins, but have no idea where to start? Well keep reading because this article is for you!
If you’re like me, trying to find basic concepts out there is not easy. There’s tons of examples of existing plugins, but it’s hard to know where to begin. So to help, I’ve compiled all the information I’ve found into one easy location.
This is definitely not an advanced guide to writing plugins, as I’m not a developer. I’m a UI/UX Designer that happens to code pretty decently (so I think). Real developers might cry openly when they see my code, but I think I code in a way that is understandable to beginners.
If you’re an engineer looking for more advanced examples, there’s a wealth of information here: http://james.ooo/sketch-plugin-development and at the official Sketch developer site: http://developer.sketchapp.com/
Why Write a Plugin?
Plugins are perfect for automating repetitive tasks, they make work and production much easier. Chances are there’s already a plugin for what you need to do, so be sure to search first before attempting to write your own, because most likely someone else has done it better. But if your process of creating UI is unique (like for me, designing UI for games in Unity) you’ll most likely need a custom solution.
Before you start writing a line of code, start by getting all your software and bookmarks set up.
- If you don’t already have one, download a text editor. (I use Atom, but there a lot of great text editors out there like Sublime or Textmate)
- Next, open your Console for debugging, and add it to your Dock, you’ll be using this a lot.
3. The Console is used by your machine for ALL debugging, so create Search filter
If you are using MacOS Sierra, use this filter in the Search input:
process:Sketch <press return>
library:Sketch <press return>
Then Save the filter as Sketch
If you are using an OS earlier than Sierra, create a new Sketch System Query Log filter by: File > New System Query Log
Copy these settings and press Ok.
You should now see a Sketch filter in the left hand column.
4. Bookmark your Sketch Plugins folder for quick access by adding it to your Favorites in your Finder window.
You’ll be accessing this folder a lot too, and having it hidden in your Library makes it a bit annoying to navigate to.
And now you’re ready to write your first plugin!
Creating a Plugin in 10 Easy Steps
Sketch plugins are basically folders with the .sketchplugin extension, which makes it easier to share with other users.
For this demo, we’ll make a basic script to get the name of a Page. You don’t need to know how to code to get this working, but it does help if you understand some basic concepts. In posts to come, I will be documenting the various scripts I’ve been using to get specific data from Sketch and customize it. But for this demo, I’ll just be using this one.
With that in mind, let’s get started!
- Start by creating a new folder in your Sketch Plugins folder and call it MyPlugin.sketchplugin
(Once you add the .sketchplugin extension, double clicking it will try to install the plugin instead of opening the folder. To open it, Right-Click the plugin and choose Show Package Contents)
2. Inside that folder, create a folder called Contents
3. Inside Contents, create a folder called Sketch
Your final plugin folder structure should look like this:
Inside the Sketch folder is where you’ll start to create your plugin, which at the minimum consists of 2 files, a manifest and a script.
The manifest describes the plugin and can add things like keyboard shortcuts or additional scripts, they are always named manifest.json
The script is where the actual plugin code will go and is referenced in the manifest. The names can be customized to however you like as long as they match in both files.
4. In your text editor, create a new file called manifest.json and save it to MyPlugin.sketchplugin > Contents > Sketch
5. Copy and paste this code into manifest.json, and save.
You should now see MyPlugin in your Sketch plugins menu. You can change the name of the plugin, or the shortcut and it will reflect in the Plugins menu in Sketch. For shortcuts, it’s important you choose one that isn’t already assigned to an existing application or plugin shortcut, or it won’t show up.
Now let’s create MyScript.js, which the manifest refers to and loads when selected. Make sure this name matches your manifest file!
6. Go back to your text editor and create a new file named MyScript.js and also save it into the MyPlugin.sketchplugin > Contents > Sketch folder
7. Copy and paste this code into the MyScript.js
I’ll better explain this script in some follow up posts along with additional snippets. But for now, the comments explain what each line does.
8. Go to Sketch and open a new file, if you don’t already have one open
9. From the Plugins menu, select MyPlugin > Get Page Names
10. Go to your console and at the bottom of the log you should see the page name.
10:54:42 PM Get Page Names (Sketch Plugin): Page 1
Try changing the page name in the Sketch file and re-running the plugin. The log should show the new name. Add an other page and rename it then run the plugin, the console will now show both page names.
And That’s It!
There’s obviously a lot more you can do with plugins, but this is really just to get you started. I’ve only been using Sketch for a few weeks and I’m already impressed with it’s customization and power. Hopefully this helps other people who have encountered the same issues I had getting started, as the Plugin community only gets better with more people contributing.