• Stars
    star
    842
  • Rank 54,118 (Top 2 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created over 8 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

The JavaScript plugin library embedded in Sketch

Sketch JavaScript API

JavaScript API for Sketch for writing scripts and creating plugins.

Sketch JavaScript API Architecture

Usage

For guides, concepts and regular updates on what's new in the latest version of Sketch, see the Plugin Developer Documentation.

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

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.

  1. Checkout this repository.
  2. Configure Sketch to use your local version of SketchAPI instead of the built-in.
    npm run api-location:write
  3. Ensure you've installed the dependencies with npm, and then build SketchAPI.
    npm install
    npm run build
  4. Start Sketch and your changes will be picked up.

โš ๏ธ Sketch must be restarted for API changes to take effect after running npm 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:

  1. Doubleclick to install the SketchIntegrationTests-$UUID.sketchplugin.
  2. Open Sketch version to test.
  3. 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:

More Repositories

1

svgo-compressor

A Plugin that compresses SVG assets using SVGO, right when you export them.
JavaScript
1,097
star
2

sketch-image-compressor

A Plugin for Sketch that compresses your bitmap assets, to keep filesize to a minimum.
JavaScript
335
star
3

sketch-document

Monorepo for Sketch document JSON Schemas and TypeScript types
TypeScript
174
star
4

BCCollectionView

A more versatile, faster and lighter replacement for NSCollectionView
Objective-C
166
star
5

fig2sketch

fig2sketch is a command line tool that converts `.fig` files into Sketch design documents (`.sketch`), which can then be opened with Sketch applications.
Python
113
star
6

print-export-sketchplugin

Exports a PDF for printing
Objective-C
86
star
7

unsplash-sketchplugin

Unsplash Data Provider plugin, for Sketch 52+
JavaScript
71
star
8

Coma

A code generator. Takes JSON templates describing a model, and turns them into Objective-C classes.
Objective-C
67
star
9

date-time-sketchplugin

Sketch data plugin generating random dates and times
JavaScript
47
star
10

sketch-assistants

Monorepo containing the official Sketch Assistants, along with utility functions and types for Sketch Assistant development.
TypeScript
44
star
11

sketch-file-format-ts

TypeScript types for the Sketch File Format
TypeScript
44
star
12

nicene

Additional Credo checks
Elixir
38
star
13

SketchTemplates

New document templates for Sketch
33
star
14

sketch-ipsum

A DataSupplier Plugin for Sketch, that fills your text layers with random Lorem Ipsum
JavaScript
28
star
15

sketch-assistant-template

Template repository for a starter Assistant project ๐Ÿ›Ž
TypeScript
25
star
16

library-replacer-sketchplugin

A Sketch plugin that allows you to replace a library in a Sketch file
JavaScript
20
star
17

sketch-reference-files

A store of automatically generated Sketch file JSON organised by document version and Sketch feature
JavaScript
20
star
18

plugins.examples.datasupplier

Example plugin which supplies data for Sketch to use
JavaScript
17
star
19

plugins.example.data-translate

A sample plugin that shows how to access a layer inside a Data plugin
JavaScript
14
star
20

color-variables-migrator

A Plugin to migrate colors, Layer and Text Styles to use the new Color Variables feature in Sketch 69
JavaScript
13
star
21

sketch-fusion

Sketch Fusion applies themes to Design System documents.
TypeScript
8
star
22

document-change-sketchplugin

Sample plugin showcasing how to handle document changes such as object addition, deletions and modifications.
JavaScript
8
star
23

vectorbrush

Objective-C
6
star
24

file-format-series-sketch-to-json

Sample code for our File Format series
TypeScript
6
star
25

layers-as-tile-pattern-sketchplugin

A Sketch plugin where you can use layers as a tile pattern to fill a shape
JavaScript
6
star
26

trolleybus

Local, application-level PubSub API for dispatching side effects
Elixir
5
star
27

get-sketch-logs

Shell script for collecting Sketch support logs and system information into a single ZIP archive that can be shared with the Sketch customer support team.
Shell
5
star
28

frontend-code-test

Repository for stuff related to the frontend code test.
4
star
29

GeometryKit

Objective-C
4
star
30

color-tokens-example

JavaScript
3
star
31

sketch-overrides-manager

Manage to enable/disable the new Sketch v94+ overrides in batch
JavaScript
3
star
32

developer.sketch.com

The Sketch Developer website
SCSS
2
star
33

file-format-series-json-to-sketch

Sample code for our File Format series
TypeScript
2
star
34

BCPopover

NSPopover substitute which in vertical mode allows for more control over placement
Objective-C
2
star
35

workspace-webhook-demo

Sample code that shows how to use the webhook feature in Sketch Workspaces
JavaScript
2
star
36

gql-lint

GraphQL linter
Go
2
star
37

sketch-71-symbol-resync

Fixes a missing Library ID issue in Sketch 71
JavaScript
2
star
38

material-icons-library

A proof of concept tool to generate Sketch files from other file formats
TypeScript
2
star
39

qa-info

Plugin for QA
JavaScript
1
star
40

paginator

Elixir
1
star
41

doctor-sketch-file

JavaScript
1
star
42

sketch-assistant-core-rules

Sketch Assistant containing the official core rules
TypeScript
1
star
43

cloud-replacer

A plugin to replace Cloud documents with local files
JavaScript
1
star
44

libwebp

Fork of https://chromium.googlesource.com/webm/libwebp.
C
1
star