Sketch JavaScript API
JavaScript API for Sketch for writing scripts and creating plugins.
Usage
For guides, concepts and regular updates on what's new in the latest version of Sketch, see the Plugin Developer Documentation.
โน๏ธ API Reference๐ Issues for bug reports and API feature requests
Example
Try the following script within the Plugins โบ Run Scriptโฆ panel.
// The Sketch JavaScript API is bundled with the Sketch Mac app
// and must be imported before it can be used.
const sketch = require('sketch')
const { Group, Shape, Rectangle } = sketch
// Get the current Document and Page
const doc = sketch.getSelectedDocument()
const page = doc.selectedPage
// Create and select a new Group within the current Page
var group = new Group({
parent: page,
frame: new Rectangle(0, 0, 100, 100),
name: 'Test',
selected: true,
})
// Add a new Rectangle Shape Layer to newly created Group
var rect = new Shape({
parent: group,
frame: new Rectangle(10, 10, 80, 80),
})
// Get and log the current selection
var sel = doc.selectedLayers
console.log(sel.isEmpty)
sel.forEach(function (elem) {
console.log(elem.name)
})
Development
Prerequisits
- Have Node installed
- Visual Studio Code (recommended)
Overview
The Sketch API is written in JavaScript/CocoaScript and gets bundled as part of the build process using webpack.
In addition to the API, this project also defines core modules to be included in Sketch as part of the official release process. Both are written to the build
output folder when the build script is run:
./build.sh
Scripts
The following npm scripts are available for development of the API.
Script | Description |
---|---|
npm run build |
Build SketchAPI into the build folder |
npm run test:build |
Build integration test plugin |
npm run lint |
Lint the source code |
npm run format-check |
Check the format with Prettier |
npm run api-location:write |
Tell Sketch to use your local SketchAPI |
npm run api-location:delete |
Undo npm run api-location:write |
Build and run
Follow the steps below to use a local copy of the API with your installation of Sketch.
Note, any plugins you have installed or code you invoke in Sketch's Plugins โบ Run Scriptโฆ sheet will use your local copy of the API.
- Checkout this repository.
- Configure Sketch to use your local version of
SketchAPI
instead of the built-in.npm run api-location:write
- Ensure you've installed the dependencies with npm, and then build SketchAPI.
npm install npm run build
- Start Sketch and your changes will be picked up.
โ ๏ธ Sketch must be restarted for API changes to take effect after runningnpm run build
.
โ ๏ธ You must remove the custom location configuration to make your installation of Sketch use the version of the API included with the app.npm run api-location:delete
Testing
The SketchAPI builds on top of macOS and internal Sketch APIs via CocoaScript. To ensure the API works for a specific Sketch version or build, this repository includes *.test.js
files containing integration tests.
These integration tests are compiled into a single test plugin using Webpack and can run by the run_tests.py
Python script, or from the Sketch application menu.
Build test plugin
To build the plugin separately, e.g. to install and run it manually, run the following command.
npm install # if you haven't installed dependencies already
npm run test:build --identifier=IDENTIFIER
To build the plugin including only one spec file, e.g. run tests from one spec only, run this command:
npm run test:build --identifier=IDENTIFIER
Use different IDENTIFIER
values if you are testing different versions of Sketch or want to run integration tests concurrently on the same machine.
Note: The Sketch JavaScript API does not need to be rebuilt. The integration tests use the API bundled within Sketch or the custom API location specified in the user defaults.
Run test plugin
To run the integration test plugin from the command-line, you must provide the path to the plugin and a file path to be used by the plugin to write the test results and can be watched by the Python script for changes.
python run_tests.py -p /path/to/SketchIntegrationTests-$UUID.sketchplugin -o FILE_PATH [-s SKETCH_PATH] [-t TIMEOUT]
Optionally, specify the Sketch installation to be used for the tests. If none is provided the default installation path /Applications/Sketch.app
is going to be used.
Note: Tests can be run concurrently but only for different Sketch installations. Only one test run per Sketch installation location is supported because the Sketch process is terminated at the end of the test run based on its path on disk.
Tests can also be run manually from within Sketch:
- Doubleclick to install the
SketchIntegrationTests-$UUID.sketchplugin
. - Open Sketch version to test.
- Select Test Sketch API from the application menu in Plugins โบ Sketch Integration Tests (
$UUID
)
The test results are written to the specified output file or, if no dedicated path is provided, to a temporary file. Use macOS' Console.app to view Sketch's logs containing information on the file location and test progress in general.
Acknowledgements
We would like to thank:
- Logan Collins for Mocha, which powers Cocoascript.
- Gus Mueller for Cocoascript, which powers our plugin engine.
- Andrey Shakhmin, for his inspiration during the Hamburg Hackathon, where he showed us a clean way to use node modules inside Sketch.
- The Sketch plugin community everywhere, for such awesome work.