# SketchAPI: the JavaScript layer inside Sketch, and how to rebuild it locally

> SketchAPI is the JavaScript and CocoaScript library that ships inside the Sketch Mac app, and the repository also carries the build machinery that lets a plugin developer point Sketch at their own local build. The design detail worth understanding is that the API is not loaded at runtime from disk, it is compiled into the app, which is why a local build requires a restart.

**sketch-hq/SketchAPI** — The JavaScript plugin library embedded in Sketch

- Repository: https://github.com/sketch-hq/SketchAPI
- Website: https://developer.sketch.com/reference/api
- Stars: 855 · Forks: 131
- Language: JavaScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/sketch-hq-sketchapi

## What the repository is

SketchAPI is the JavaScript API for Sketch, for writing scripts and creating plugins. The README is precise about what it is not: the Sketch JavaScript API is bundled with the Sketch Mac app and must be imported before it can be used. That single fact shapes everything about the project. There is no package to install and no runtime module to load from a registry, because the API ships inside the application and a plugin author imports it from the host runtime. The reference documentation lives at developer.sketch.com/reference/api, the plugin developer documentation at developer.sketch.com/plugins, and the repository issues are used for bug reports and API feature requests. The homepage of the project is the API reference, and the default branch is develop rather than main.

## The example shows the object model

The README example is meant to be pasted into the Plugins and then Run Script panel, and it shows the shape of the API in about thirty lines.

```js
// 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,
})
```

The pattern is worth noting. A document and a page are obtained from a global accessor, and everything else is a class instantiated with an options object whose parent is the layer it belongs to. A group is created with a frame, a name and a selected flag, and then a shape is added to it in the same way. Selection is queried through selectedLayers, which exposes isEmpty and is iterable, so the API reads as a scene graph rather than as a set of function calls.

## How the API gets into the app

The API is written in JavaScript and 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, and both are written to the build output folder when the build script is run.

```sh
npm install
./build.sh
```

The Xcode integration is the part that explains the developer workflow. The Build SketchAPI Xcode run script declares Modules/SketchAPI/build as its output, and the main Sketch target then uses that same build folder as the input for its Install SketchAPI run script. This relies on the SketchAPI build deleting and recreating the build folder whenever the JavaScript sources are rebuilt. The practical consequence is that a real source change in one of the JavaScript files triggers both the build phase and the install phase, while unchanged incremental builds skip both, which is what keeps a rebuild fast.

## Pointing Sketch at your own build

To use a local copy of the API with your installation of Sketch, you configure Sketch to use your local version instead of the built-in one.

```sh
npm run api-location:write
```

Then you install the dependencies and build.

```sh
npm install
npm run build
```

Start Sketch and your changes are picked up. Two warnings follow. Sketch must be restarted for API changes to take effect after running npm run build, and you must remove the custom location configuration to make your installation of Sketch use the version of the API included with the app. The removal step is npm run api-location:delete. Under the hood both scripts write or delete a preference, with the write setting a SketchAPILocation key in the sketch3 preferences domain to the build directory under your working path. The second warning is the one that bites: a plugin shipped while the custom location is set will depend on a development setup that your users do not have.

## The npm scripts and the editor tasks

The scripts are listed in a table in the README, and they map onto the workflow. npm run build builds SketchAPI into the build folder, npm run test runs the integration tests or a single suite, npm run lint lints the source code, and npm run format-check checks the format with Prettier. The api-location pair we have already covered. The package manifest also shows the underlying pieces: the build script is a shell script in the Scripts directory, the test build is a webpack invocation with an identifier and a spec passed through as environment values, and there is a postinstall step that installs the core-modules dependencies separately, which is the mechanism behind the core modules that ship with the app. For Visual Studio Code users there is a tasks.json with shortcuts such as Build and Lint, Test, Test Single Suite, and Test Custom Sketch, the last of which runs the integration tests against a selected Sketch variant such as Sketch Beta.

## Integration tests that run inside the real app

The SketchAPI builds on top of macOS and internal Sketch APIs via CocoaScript, and to make sure the API works for a specific Sketch version or build, the repository includes test 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. The test runner launches Sketch itself and collects results back, and the script takes an optional suite name so you can run one suite exclusively.

```sh
./test.sh SymbolInstance
```

That command builds SketchAPI and the tests, prepares the host plugin, sets up the environment, launches Sketch and runs the suite in it. The README also recommends installing the psutil Python module so the test runner can terminate Sketch automatically on completion, and otherwise every new test run leaves a new instance of the app hanging around. The manual path is documented too, with npm run test:build taking an identifier, and the run_tests.py invocation taking the plugin path, an output file path that the plugin writes and the script watches, and optionally a Sketch installation path and a timeout.

## The repository layout and the toolchain

The top-level listing shows where things live. There is a Source directory for the API itself, a core-modules directory for the modules shipped with the app, and a SketchAPIWrapper directory. The build is driven by webpack with three configurations, one for the API, one for the plugin package and one for the tests. There is an Xcode project, a Scripts directory with the shell scripts the npm scripts call, a docs directory, an examples directory, and a run_tests.py script at the root. The examples are worth a look because they are small: there is a hello-world, a selection-changed example, an svgo-export example, a text-utilities example and a resources folder. The toolchain is current for a project of this age, with webpack 5, Babel 7, ESLint 7 and Prettier 2 as the linting and formatting layer, and the build prerequisites are Node 22 or newer plus Visual Studio Code as the recommended editor.

## Where SketchAPI is the wrong choice

Four limits apply. It is macOS only, since the whole thing runs on CocoaScript inside a Mac app and the tests launch that app, so there is no way to use it from another platform. It is not a published package, because the API is bundled into the application, so a script that does require it outside Sketch will not resolve. The local-build workflow has a sharp edge, since a rebuild needs a Sketch restart and forgetting to reset the custom location leaves your installation pointing at a path that only exists on your machine. And the release tags in the repository are opaque identifiers rather than version numbers, all dated 2020-04-30, so there is no usable version history in the tag list even though the application itself ships the API, which means the practical source of truth for what changed is the changelog and the app's own release notes rather than the repository.

## Conclusion

Use SketchAPI when you are writing Sketch plugins and want to work against a local build of the API rather than the one bundled with your installed app, because the api-location scripts repoint Sketch at your compiled output in a couple of commands. Do not treat it as a standalone JavaScript library you can require from Node, since it depends on the Sketch host and on internal macOS APIs. Verify first that you have Node 22 or newer and a Mac, that you can rebuild the API after a change and restart Sketch, since a rebuild without a restart leaves the old API in memory, and that you run npm run api-location:delete before shipping a plugin, otherwise your plugin will depend on a development setup that other users do not have.

## FAQ

### What is SketchAPI?

It is the JavaScript API for Sketch, used for writing scripts and creating plugins. The API is bundled with the Sketch Mac app and must be imported before it can be used, so it is not a package you install from a registry.

### How do I make Sketch use my local build of the API?

Run npm run api-location:write to point Sketch at your build folder, install the dependencies with npm, then run npm run build and start Sketch. When you are finished, run npm run api-location:delete so your installation goes back to the API bundled with the app.

### How are the integration tests run?

The test files are compiled into a single test plugin using webpack and run by the run_tests.py script or from the Sketch application menu. The test.sh script builds SketchAPI and the tests, prepares the host plugin, launches Sketch and reports the results, and it optionally takes a suite name such as SymbolInstance to run one suite exclusively.

### What are the requirements for building SketchAPI?

Node 22 or newer and Visual Studio Code as the recommended editor, plus macOS, since the API is written in JavaScript and CocoaScript and the tests launch the Sketch app itself. Installing the psutil Python module lets the test runner terminate Sketch when a run finishes.

### What licence is SketchAPI released under?

MIT, with the LICENSE.md file at the repository root and the same value recorded in the package metadata. The API reference is published at developer.sketch.com/reference/api and the plugin developer documentation at developer.sketch.com/plugins.

## Sources

- [License: MIT](https://github.com/sketch-hq/SketchAPI/blob/develop/LICENSE)
- [Project website](https://developer.sketch.com/reference/api)
- [README](https://github.com/sketch-hq/SketchAPI/blob/develop/README.md)
- [Releases](https://github.com/sketch-hq/SketchAPI/releases)
- [sketch-hq/SketchAPI on GitHub](https://github.com/sketch-hq/SketchAPI)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sketch-hq-sketchapi