README.md

@carbon/sketch

Table of Contents

• Developing
  • Where to start
• References
• Tips & Tricks

Getting started (developing)

When working with this package, you will need to follow a couple of steps to get started. It's important that you have Sketch installed on your system before attempting any of these steps.

1. Run cd packages/sketch to go into the package folder
2. Run yarn build to build out the initial plugin
3. Run yarn skpm:link to link the plugin to your Sketch plugin folder

Afterwards, you can continue development by running yarn develop.

Overview

Building sketch plugins

The output of @carbon/sketch is a plugin at packages/sketch/carbon-elements.sketchplugin. This artifact is generated by running yarn build. Under the hood, we make use of a tool called skpm that allows us to write our Sketch plugins using modern JavaScript language features and modules.

When using skpm, we add a field named skpm to our package.json so that it knows details about our plugin, most notably the name of the plugin and a reference to a manifest.json file. This file lists out the capabilities of the sketch plugin under the commands field, and also defines the menu structure th at should appear for this plugin under the Plugins menu in Sketch.

Under the commands field, we list out commands and define a path to a script and name the handler that should be called when running the command. In other words, if we have a file like:

// commands/greeting.js
import sketch from 'sketch';

export function greeting() {
  sketch.UI.message('Hello world!');
}

Then in our manifest.json we would create an entry under commands like:

{
  "commands": [
    {
      "name": "The name of the command"
      "identifier": "the.command.identifier",
      "script": "commands/greeting.",
      "handler": "greeting"
    }
  ]
}

Note: We chose the greeting handler because that was what was exported in export function greeting() {}.

We later use the identifier field in our menu to reference the command.

Project structure

packages/sketch
├── package.json
└── src
    ├── commands       # Implementation of commands in `manifest.json`
    ├── manifest.json  # Define capabilities of Sketch plugin
    ├── sharedStyles   # Methods for syncing shared layer and text styles
    └── tools          # Tools for interacting with the Sketch DOM and styles

Reference

• API Reference for the sketch module
• Sketch-Headers to determine methods on internal objects
• Plugin bundle guide for structuring a plugin and its menus

Tips & Tricks

• Use yarn skpm log -f to tail logs from the Sketch plugin. Useful if you want to debug using console.log layer is removed