How to build a Sketch plugin withTypescript and React [Part 1]
At Overlay, we started 2 years ago building a Sketch Plugin to help designers t export their symbols into prod-ready React/Vue.js components. I write this article to help people create Sketch plugins and to share our technical expertise on this subject.
First, Sketch plugins are very good tools to extend Sketch functionalities. Sketch has thousand plugins built by the community. For example, at Overlay our Sketch plugin allows designers to check the components consistency with their project guidelines (color, typography), extract data from Sketch (symbols data, assets, text style, etc…) and detect design defaults.
Tutorial objective
This tutorial aims at creating a basic but complete Sketch plugin with React and Typescript, from scratch. I want to give you an overview of what can be achieved with Sketch Plugins: create web-feeling interfaces, trigger Sketch native functionalities from a web view, trigger web view app functionalities from Sketch native events.
To keep things challenging, we are going to build a linter plugin: PixelPerfect ! PixelPerfect users will be able to select a Sketch Symbol and check if there are imperfect pixels in its layers.
If the plugin detects imperfect pixel, the user can fix all imperfections in one click through the plugin.
The tutorial will be split in three parts, that will be published successively:
- [Part 1] Some theory and get started your first plugin with React
- [Part 2 ] Communication between React and Sketch
- [Part 3] First deployment and how to automate them
Architecture
Let’s start with designing the plugin architecture, there are two approaches for building a Sketch plugins :
The native approach, where all the application code is stored in the user’s computer. This is the case for all plugins built without web-views (Zeplin, Craft) and plugins built with a web view where app files are hosted in local (see this tutorial) and displayed by Safari (opened by Sketch).
The web approach, where only a few code parts are stored in the user’s computer. In this case, we stored code responsible for web view handling and Sketch/Plugin communication. The rest of the application (interface and logic ) is stored on a server as a classic web client-side application.
Obviously, the second approach looks more complicated, so why choose this one ?
- Web approach don’t requires Objective-C competences (which are rare) so “common” web developers can create a plugin.
- With the web approach, you can ensure that all your users always have the plugin’s last version running (the one deployed on the server). This helps you a lot to iterate faster on your product. With the native approach you are dependent to the version installed in the user computer. That can leads you to new hard tech challenges like API versioning or retro compatibility changes.
- From a user point of view, the web approach is more user friendly, you don’t have to update your plugin manually as the browser will take care about it.
Nevertheless, be careful with this approach. If you want to get the full potential you must avoid writing business logic in the native part of your application as this part can be painful for your user to update (manual update).
At Overlay, we chose the web approach because :
- We want to iterate on the plugin every week.
- We don’t know Objective-C but we have strong knowledges on web development.
- We want to connect to several designer tools (Figma, AdobeXD, etc…) and we want to easily reuse our plugin interface.
Ready to start ? Let’s go !
Get started
We will build the native part with SKPM and the web part with React but you can do this with all JS frameworks (I haven’t tested with Backbone…#RIP).
Prerequisites:
First, create an empty directory project
mkdir pixel-perfectCreate inside this directory a Sketch plugin with web view with SKPM
cd pixel-perfect && npx skpm create pixel-perfect --template=skpm/with-webview && mv pixel-perfect pixel-perfect-nativeThen let’s start the Sketch watcher
cd pixel-perfect-native && npm run watchNow the native part of your Sketch plugin must be running, you must see this in Sketch
Now let’s build the plugin’s web part. First create the React app with create react app inside the pixel-perfect folder
npx create-react-app pixel-perfect-web --template typescriptThen let’s start the Webpack server
cd pixel-perfect-web && npm run startNow you must see this in your browser at http://localhost:3000
Ok now let’s connect the React app to the Sketch plugin, to do so, edit my-command.js
Now open/close the plugin, you must see the web approach’s Hello world 🎉
Development environment
Now, let’s have a look at the development environment we just built. First, we have the native part in the pixel-perfect-native/src folder. When we run npm run build command, SKPM launches a Webpack server to build the Sketch plugin in this location pixel-perfect-native/pixel-perfect-sketch/sketchplugin. SKPM watcher works well but it demands to open manually the new built plugin on each change which is painful. I recommend adding a Makefile in the project root pixel-perfect with this command.
With this Makefile in one command make build you can build and open the new plugin.
The web part is located in pixel-perfect-web/src folder. When we run npm run start command, React script launches a Webpack server and builds the web app files. Every changes in the web part will be hot reloaded in the browser and in the Sketch plugin, that will be super useful to continue the plugin !
It can be pretty hard to debug the native part. I recommend to install and use SketchDevTools to print data. For the web part you can use your favorite browser dev-tools or Safari dev-tools directly inside the plugin web-view. To know more about debugging follow this Sketch tutorial.
Add a Shortcut to open up the plugin
Clicking is painful for users and for developers. Instead of asking to the user to click each time on the plugin command, we will add a shortcut to toggle the plugin interface, what about ^+shift+P ? To do so let’s update the manifest.json native file with the shortcut line
"commands": [
{
"name": "my-command",
"identifier": "pixel-perfect.my-command-identifier",
"script": "./my-command.js",
"shortcut": "ctrl shift p",
"handlers": {
"run": "onRun",
"actions": {
"Shutdown": "onShutdown"
}
}
}
],Now we can rebuild the plugin and test it in Sketch :)
Add a Reactive interface to the Sketch plugin
Now we will design the main screen plugin, it will show if the plugin has found some imperfections. Let’s change the App.tsx.
Then we need to change the App.css
Now we can see our new beautiful interface 🖼
Now let’s add a state hasImperfection to handle the component status. We use a ternary expression to conditionally render the clean button or the success message.
We use React hook useState, if you are not familiar with it, you can learn about it here or you can achieve the same result with the setState method. Now you must see this after clicking on the button
You are done, Pixel Perfect is up !
Code source available on this GitHub repository: https://github.com/Overlay-tech/pixel-perfect-tutorial
Conclusion
I hope I have convinced you of the capabilities of React to create a Sketch Plugin with very little effort. To sum things up:
- SKPM and Create React App can create a dummy plugin in one command line.
- The Web approach allow to iterate really fast on your code base
- Using a web-view plus React for building an interactive interface is very straight forward.
However, Pixel Perfect is not yet a complete Sketch Plugin, in the next article we will :
- Pass the component information from Sketch to React to know if the symbols has inconsistencies.
- Connect the ‘Clean my symbol’ button to Sketch native action to clean the component.
If you want to know more about Overlay go here, it’s free to try:
We build a series of technical articles to explain how Overlay engineering team designs, builds and operates our systems and we will continue to post tech content every month, if you are interested in tech problems, follow Overlay blog.
