Manifest

The manifest is a JSON file that provides information about a plugin such as author, description, icon and where to get the latest update from. It also tells Sketch how to run the plugin and how it integrates into the Plugins menu.

Tip: Validate your manifest.json using the JSON Schema.

Example manifest

The example manifest.json file below is for a plugin called Select Shapes, and defines three commands – All, Circles and Rectangles. These commands would be accessible from the Plugins › Select Shapes menu in Sketch.

{
  "name": "Select Shapes",
  "description": "Quickly select all or just specific shape types",
  "author": "Bob Ross",
  "homepage": "https://github.com/example/select-shapes",
  "version": "1.0",
  "identifier": "com.example.sketch.plugin.select-shapes",
  "appcast": "https://example.com/select-shapes-plugin-appcast.xml",
  "compatibleVersion": "52.1",
  "commands": [
    {
      "name": "All",
      "identifier": "all",
      "shortcut": "ctrl shift a",
      "script": "shared.js",
      "handler": "selectAll"
    },
    {
      "name": "Circles",
      "identifier": "circles",
      "script": "circles.js"
    },
    {
      "name": "Rectangles",
      "identifier": "rectangles",
      "script": "rectangles.js"
    }
  ],
  "menu": {
    "items": ["all", "circles", "rectangles"]
  }
}

Members

`appcast`

A URL to the plugin’s updating JSON file containing information about the the most recent plugin version, including a URL to download the most recent update. Sketch automatically checks this file for updates and notifies the user when there’s an update available.

`author`

Provides the name of the plugin author.

`authorEmail`

Specifies how to contact the plugin author by email. This is optional.

`bundleVersion`

Specifies the version of the plugin bundle’s metadata structure and file layout. This is optional, and defaults to 1. No other versions are currently supported.

`compatibleVersion`

Defines the minimum version of Sketch required to run the plugin. This string must be using semantic versioning. Please note that this is not used by Sketch to determine compatibility, and you should use it for your own reference only.

"compatibleVersion": "52.1"

`commands`

An array of objects defining all commands provided by the plugin.

For example, the example command definition below says that the selectAll JS function in script.js should be called when the Select all command is invoked from Sketch.

"commands": [
  {
    "name": "Select all",
    "identifier": "select-all",
    "shortcut": "ctrl shift a",
    "script": "select-all.js",
    "handler": "selectAll"
  }
]

// select-all.js
function selectAll() {
  // ... plugin code to select all
}

Command field	Description
`identifier`	Defines a unique identifier of the command within the plugin bundle.
`name`	Provides the name of the command which is used within the Plugins menu.
`shortcut`	Provides a default keyboard shortcut for the command, e.g. `ctrl shift t`. See table below for a reference of possible values.
`script`	Specifies the relative path within the plugin bundle’s `Sketch` folder to the script implementing the command.
`handler`	Specifies the name of function to be called with the command. The function should be declared at the top level of the script, and accepts a single `context` parameter which contains information such as the current document and selection. If this field is omitted the plugin will default to using a handler named `onRun`. Alternatively, if you’re using the `skpm` tool you may `export` the function instead of declaring it, or omit this field and declare the handler with `export default`
`handlers`	If more fine-grain control is required use the `handlers` field instead of `handler`, see below for in-depth documentation

Shortcut Values

Command shortcuts can be set using any combination of the following keys, plus any regular character.

Please note shortcuts must contain at least one modifier key, Command, Option, Control or Shift. Values matching predefined Sketch shortcuts, e.g. cmd s will be ignored.

Make sure to test your shortcuts with different international keyboard layouts. Certain characters can require users to press modifier keys. For example a shortcut like shift / would not work with a Spanish keyboard layout. Whereas a forward slash / has a dedicated key on a US keyboard, it requires pressing shift 7 on a Spanish keyboard.

Key	Value
Command (⌘)	`cmd`
Option (⌥)	`alt`
Control (⌃)	`ctrl`
Shift (⇧)	`shift`
Backspace (⌫)	`⌫` or `\u0008`
Tab (⇥)	`⇥` or `\u0009`
Return (↩)	`↩` or `\u000d` or `\u000a`
Escape (⎋)	`⎋` or `\u001b`
Left (←)	`←` or `\u001c`
Right (→)	`→` or `\u001d`
Up (↑)	`↑` or `\u001e`
Down (↓)	`↓` or `\u001f`
Space	`\u0020`
Delete (⌦)	`⌦` or `\u007f`
Home (↖)	`↖` or `\u2196`
End (↘)	`↘` or `\u2198`
Page Up (⇞)	`⇞` or `\u21de`
Page Down (⇟)	`⇟` or `\u21df`

`handlers`

An object used to fully specify a command’s setup › run › tearDown lifecycle, as well as work with Actions. When specified the handler field is ignored.

The handlers object has five fields:

run The function that should be called when the command is run (this is conceptually the same as defining handler)
setUp The function to call before the command is called (not to be confused with the Startup action)
tearDown The function to call after the command has finished to run (not to be confused with the Shutdown action)
onDocumentChanged See the Document changes page
actions See the Actions page for an in-depth guide

For example, the following commands definition maps the SelectionChanged.finish action to the onSelectionChanged JS function,

{
  "commands": [
    {
      "name": "Selection changed",
      "identifier": "selection-changed",
      "script": "./selection-changed.js",
      "handlers": {
        "actions": {
          "SelectionChanged.finish": "onSelectionChanged"
        }
      }
    }
  ]
}

The function in selection-changed.js would be written as,

// selection-changed.js
function onSelection(context) {
  var doc = context.document
  var selection = context.selection
}

Functions referenced in the handlers object are defined in the same way as the handler function, i.e. declared at the top level of the script in a vanilla plugin, or using ES6 module export syntax with skpm.

`description`

Provides a general description of what the plugin does.

`disableCocoaScriptPreprocessor`

CocoaScript by default supports @import and bracket syntax, i.e. [obj hello: world]. If disabled by setting disableCocoaScriptPreprocessor to true this is no longer supported.

Note: To use ES6 syntax and build systems like skpm this must be set to true.

This value is optional, default false, set to true when using skpm.

`homepage`

Specifies a website address where users can find more information or provide feedback for the plugin. This is optional.

`icon`

The path to the plugin icon used within Sketch, e.g. within preferences. The icon must be provided as a PNG file at a resolution of 128x128px and located directly or in a subfolder within Contents/Resources of the plugin bundle.

`identifier`

Defines a unique identifier for the plugin. This value is a string using reverse-domain syntax.

"identifier": "com.example.sketch.plugin.select-shapes"

`maxCompatibleVersion`

Defines the maximum version of Sketch supported by the plugin. This string is optional and must be using semantic versioning if provided. Please note that this is not used by Sketch to determine compatibility, and you should use it for your own reference only.

"maxCompatibleVersion": "54"

`name`

Provides a human-readable name for the plugin when displayed to the user, e.g. within the Plugins menu or the list of installed plugins in the Sketch preferences.

`scope`

Specifies if the plugin can be run without an open Sketch document.

document: default, disables the plugin’s menu items when no document is open
application: enables the plugin menu and allow to run the plugin without an open document

"scope": "application"

`suppliesData`

Specifies if the plugin is a data supplier. If set to true a visual indicator is displayed with the plugin within the preference pane showing the list of all installed plugins.

`version`

The version of the plugin using semantic versioning. This is the version that will be compared against the versionID set in the updating JSON file. If the version here is below the one in the updating JSON file then an update is available.

"version": "1.0.1"

`menu`

Provides information about the menu layout of the plugin. Sketch initializes the menu when loading the plugin.

{
  "menu": {
    "title": "Select Shapes",
    "items": [
      "selectAll",
      "-",
      {
        "title": "Select…",
        "items": ["circles", "rectangles"]
      }
    ]
  }
}

Member	Description
`isRoot`	Specifies that menu items are created directly within the Plugins menu in Sketch. By default Sketch creates a submenu for the plugin. This value is not supported for submenus.
`items`	An array of menu items, supported values are command identifier, `"-"` separator and an object defining a submenu
`title`	Provides the human readable title used for the menu item. The value is ignored if the menu item also has `isRoot` set to `true`.