Writing a Basic Sketch Plug-In
Plug-ins often have a large impact on how users interact with software. When an application supports plug-ins, it enables third-party developers to add new features and extend the application’s existing functionality, which can often enhance a user’s workflow, increase productivity, and simply create a better experience overall.
Sketch, a digital design tool, provides developers with the infrastructure to customize the way its users interact with its platform. With its external API, Sketch allows for third-party plug-ins that can be used to re-arrange layers, create new shapes, and much more. Note: Sketch is not free (a paid license is required), but they offer a free, 30-day trial for first-time users.
In this post, we’ll go through the process of creating a basic Sketch plug-in. At the end of this walk-through, this plug-in will reverse the order of selected, consecutive layers.
To create our plug-in, we’ll be using Sketch Plugin Manager (skpm). For a detailed set-up guide, check out their readme.
For our purposes, we’ll need Node.js (version 6 or higher). Once Node.js is installed, we’ll run two commands in the command line to get up and running.
The first, npm install -g skpm, installs Sketch Plugin Manager. Once that is installed, we can run skpm create reverse-layers, which generates the base project. (Note: In this walk-through, the plug-in is going to be named “reverse-layers,” but when creating other plug-ins, reverse-layers in the above command can be replaced with any name).
Inside of the newly-created project, there is a src folder containing two files: a manifest.json file, which stores meta-data about the plug-in, and my-command.js, which contains the logic for the plug-in.
In manifest.json, notice the commands property. This property is an array that lists all of the actions that the plug-in can perform. (These show up in the menu bar under “Plugins” when in Sketch.) By default, it generates a single command with a name (“my-command” by default), identifier, and script. Inside of this object, we’re going to add a fourth property named shortcut. This will give users the option to initiate the action via a keyboard shortcut, rather than selecting it from the menu bar.
Inside of the existing command, add "shortcut": "ctrl alt r". Note: This shortcut is not currently used elsewhere in Sketch. If we were to use something like, for example, “cmd q”, we’d run into issues, as that shortcut is already reserved to quit an application in macOS.
For the rest of the code portion of this walk-through, we’ll be editing my-command.js. As mentioned previously, this is the file that holds the logic for the plug-in. By default, this file imports sketch and exports a single function that displays a message to the user.
Inside of the single function in this file, we can remove the line that displays the default message. (Although, this is a really nice built-in message feature, which can be used to show success/error messages to the user.)
To reiterate, the goal of this plug-in is to provide the user with a shortcut to reverse their selected layers. Sketch’s API makes the user’s selected layers easily accessible in just two lines of code.
Inside of the empty function, add the following two lines:
const document = sketch.getSelectedDocument();
const selectedLayers = document.selectedLayers.layers;According to Sketch’s API documentation, getSelectedDocument returns the currently-selected document, which houses the selected layers. On the document object, there’s a selectedLayers property, which is actually a Selection object, rather than an array of layers. However, the layers are accessible on this object.
Now that we have an array of the selected layers, we can begin to manipulate each layer’s index property (which drives its order in Sketch’s left pane). We want to reverse the indexes on the array of selected layers. One simple strategy to accomplish this is to build up the list of current indexes in order and read the list backwards, setting the index of each layer as we go.
First, we’ll want to declare an empty array that will hold our indexes. This can go inside of the same method, directly below the lines that we declared and initialized selectedLayers.
var indexArray = new Array;Then, we can loop through the selectedLayers object to populate our index array. Note that we need to call the fromNative function that Sketch provides to be able to access the index property from the layer.
selectedLayers.forEach((nativeLayer) => {
var layer = sketch.fromNative(nativeLayer);
indexArray.push(layer.index);
});Finally, we will loop through the selectedLayers once more to change each layer’s index. We will do this by updating our layers in order but reading from the list of indexes in reverse order.
For example: if we had LayerA, LayerB, and LayerC, and our index array was [1, 2, 3], we’d set LayerA to have an index of 3, LayerB to 2, and LayerC to 1.
Fortunately, JavaScript’s pop() method will provide us with the last element of the array, while also removing it from the array.
selectedLayers.forEach((nativeLayer) => {
var layer = sketch.fromNative(nativeLayer);
layer.index = indexArray.pop();
});And that wraps up our JavaScript file. We’re now ready to build our plug-in and test it out.
There’s one last step we need to take before going into Sketch to test it out, and that’s building it. In a terminal window, inside of the plug-in’s project folder, run npm run build. This command will build the project, so that the next time we add it to Sketch, it’ll use the most-recent versions of the files we just updated.
Now that we’ve finished writing our custom plug-in, we can test it out.
In Sketch, create a few layers, select all of them, and use the shortcut we specified earlier (“ctrl alt r”). You should notice that they reverse their order in the left pane (and subsequently on the board).
To see a complete example of this plug-in, check out this sample project on GitHub.
If you create your own custom plug-in and think others could benefit from it, consider publishing it to Sketch’s library of third-party plug-ins.
