Skip to content
Javascript API for working with Sketch
JavaScript CSS HTML TypeScript Ruby
Branch: develop
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Update deps and housekeeping Sep 9, 2019
.github Update GitHub organisation name following rename Oct 25, 2019
.vscode update vscode settings Apr 15, 2019
Source Update GitHub organisation name following rename Oct 25, 2019
core-modules Merge branch 'develop' into f/process-is-event-emitter Aug 28, 2019
docs-website Remove old syntax highlight Oct 26, 2019
docs Update cli-run-plugin.md Oct 30, 2019
examples Update GitHub organisation name following rename Oct 25, 2019
reference-files Gen ref files for Sketch 59 Oct 16, 2019
scripts Update deps and housekeeping Sep 9, 2019
types Adding a typescript type for the supplying data function at an index.… Aug 10, 2018
.eslintrc.yml Update deps and housekeeping Sep 9, 2019
.gitignore Update dependencies Oct 25, 2019
.nvmrc Update deps and housekeeping Sep 9, 2019
.prettierignore add prettier option not to wrap prose Nov 28, 2017
CHANGELOG.json Tweak changelog Oct 7, 2019
CODE_OF_CONDUCT.md Update all sketchapp.com mentions to sketch.com May 15, 2019
LICENSE.md format LICENSE.md Nov 27, 2017
README.md Update GitHub organisation name following rename Oct 25, 2019
dangerfile.ts fix lint Nov 29, 2018
netlify.toml …and this will NOT rebuild the site Nov 7, 2019
package-lock.json Update dependencies Oct 25, 2019
package.json Update dependencies Oct 25, 2019
tsconfig.json Update deps and housekeeping Sep 9, 2019
webpack.config.js Remove case of API being built as submodule Jul 19, 2019
webpack.skpm.config.js fix running tests on jenkins Apr 12, 2019

README.md

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.

API layers

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

The website is hosted on Netlify at https://developer.sketch.com.

The website’s contents live in the docs folder, while code related to the website’s build process lives in the docs-website folder.

For further details read the docs-website README.

Acknowledgements

We would like to thank:

You can’t perform that action at this time.