Sketch API

This is a JavaScript API for Sketch. The intention is to make something which is:

idiomatic JavaScript
an easily understandable subset of the full internals of Sketch
fully supported by Bohemian between releases (ie. we try not to change it, unlike our internal API which we can and do change whenever we need to)
still allows you to drop down to our internal API when absolutely necessary

This API is a very core layer which interfaces with Sketch itself. It's intentionally simple, and we want to keep it that way. If you feel like adding some high-level code to it, it’s probably better to add it to a community-maintained library that can be used on top of the API, and keep it separate from the core API effort.

Comments and suggestions for this API are welcome - file an issue to discuss it or send them to developer@sketch.com.

Installation

The API comes bundled inside Sketch, so no installation is required. You access it by requiring the sketch package:

var sketch = require('sketch')

Usage

The full documentation is available on [https://developer.sketch.com/reference/api].

Here's a very simple example script:

// access the Sketch API
var sketch = require('sketch')

// get the current Document and Page
var document = sketch.getSelectedDocument()
var page = document.selectedPage

var Group = sketch.Group
var Shape = sketch.Shape
var Rectangle = sketch.Rectangle

// create a new Group belonging to the current Page
var group = new Group({
  parent: page,
  frame: new Rectangle(0, 0, 100, 100),
  name: 'Test',
  selected: true,
})
// create a new rectangle Shape belonging to the previously created Group
var rect = new Shape({
  parent: group,
  frame: new Rectangle(10, 10, 80, 80),
})

// get the current selection
var selection = document.selectedLayers

console.log(selection.isEmpty)
selection.forEach(function(item) {
  console.log(item.name)
})

// deselect all the layers
selection.clear()
console.log(selection.isEmpty)

// select the rectangle we created
rect.selected = true
console.log(selection.isEmpty)

// ask the user for a string
sketch.UI.getInputFromUser(
  'Test',
  {
    type: 'String',
    initialValue: 'default',
  },
  (err, outputString) => {
    if (err) {
      return
    }
    // store the string in the settings
    // it will be remembered even when Sketch closes
    sketch.Settings.setSettingForKey('setting-to-remember', outputString)
    console.log(sketch.Settings.settingForKey('setting-to-remember'))

    sketch.UI.getInputFromUser(
      'Test',
      {
        type: 'Selection',
        possibleValues: ['Sketch', 'Paper'],
      },
      (err, outputSelection) => {
        if (err) {
          return
        }
        sketch.UI.message('Hello mum!')
        sketch.UI.alert('Title', outputSelection)
      }
    )
  }
)

For more examples, we recommend checking out the examples section of the developer website.

Happy coding!

Development

The API is organized as a series of files defining JavaScript classes, and written with ES6 syntax.

However, the version that is embedded in Sketch is a single minified and transpiled library file called SketchAPI.js.

If you want to build this library file locally, you need to have Node.js installed, and then run the following in the project's root folder:

npm install

Once that's ready, you can run:

npm start

to compile the library. By default, it will be saved to ./build/SketchAPI.js.

For your convenience, you can use

npm run watch

and a script will watch for any change in the Source folder, and build the .js file when anything has changed.

To test your changes, you need to get Sketch to use the version of SketchAPI.js you just built, instead of the one embedded inside it.

To do this you can run:

defaults write com.bohemiancoding.sketch3 SketchAPILocation "/path/to/your/SketchAPI_repo/build"

Sketch will then load the external .js files instead of the bundled version.

Testing

To run the tests, you can use

npm run test
npm run test:watch

If you want to run the tests with a specific version of Sketch, you can use

SKETCH_PATH=/path/to/sketch.app npm run test

If you want to run the tests with a the current regular version of Sketch, you can use

npm run test:no-variant
npm run test:no-variant:watch

Website (https://developer.sketch.com)

The website’s contents live in the docs folder while the code lives in the docs-website folder.

If you want to edit the website content sections, switch to the branch your changes belong to (usually it'll be either develop or release/XXX) and do your changes there, in the docs. Once your changes are ready, you run the website locally with npm run docs:start from the branch you made your changes in.

More information are available in the README of the respective folders.

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.

nadavkaner / SketchAPI