DOCSEARCHbyAlgolia
Submit Docs

Sketch JavaScript API

repository·develop·Indexed 21 days ago

https://github.com/sketch-hq/sketchapi

A JavaScript API for the Sketch Mac application used to write scripts and create plugins using JavaScript and CocoaScript. The API allows for document manipulation via modules like Group, Shape, and Rectangle, and supports plugin development using skpm for building, watching, and running projects. It includes examples for adding menu commands, bundling resources, listening for SelectionChanged actions, and automating SVG exports via SVGO.

Tokens
5.7K
Snippets
22
Records
31
Agent score
74%

What's inside sketch-api

  1. Bundle resource files with a Sketch Plugin

    develop

    To include external files (like images, JSON, or other assets) in your Sketch plugin, place them in an assets folder and configure the skpm.assets field in your package.json. This tells skpm to bundle these files into the plugin package so they can be accessed from your code at runtime.

    // package.json snippet
{
  "skpm.assets": ["assets"]
}

  2. Techniques demonstrated in Text Utilities

    develop

    The Text Utilities plugin serves as a reference for several common Sketch plugin development patterns:

    • Iterating over selected layers: Accessing and looping through the user's current selection.
    • Text layer inspection: Iterating over the position of each line within a text layer.
    • Layer creation: Programmatically creating new layers in a Sketch document.
    • Multi-command plugins: Defining multiple distinct commands within a single plugin structure.

    Note: This plugin is built using skpm.

  4. Setup the SVGO Export plugin example

    develop

    To use the SVGO Export example, which demonstrates how to compress SVG assets using SVGO by hooking into the ExportSlices action, follow these steps to download, install, and build the project:

    1. Download and enter the directory:
      curl https://codeload.github.com/sketch-hq/SketchAPI/tar.gz/develop | tar -xz --strip=2 SketchAPI-develop/examples/svgo-export
cd svgo-export
    2. Install dependencies:
      npm install
    3. Build the project:
      npm run build
    curl https://codeload.github.com/sketch-hq/SketchAPI/tar.gz/develop | tar -xz --strip=2 SketchAPI-develop/examples/svgo-export
cd svgo-export
npm install
npm run build

  5. Run development commands for SVGO Export

    develop

    Once the dependencies are installed, you can use the following npm scripts to manage the development lifecycle of the plugin:

    • Build the project: npm run build
    • Watch for changes: npm run watch (automatically rebuilds when files change)
    • Run plugin on every build: npm run start (runs the plugin every time a build is triggered)
    npm run build
npm run watch
npm run start

  6. Set up and run the Resources example plugin

    develop

    To run the Resources example, download the specific example directory, install dependencies, and use the provided npm scripts to build or run the plugin.

    Installation

    # Download and enter the directory
curl https://codeload.github.com/sketch-hq/SketchAPI/tar.gz/develop | tar -xz --strip=2 SketchAPI-develop/examples/resources
cd resources

# Install dependencies
npm install

    Development Commands

    • Build the plugin: npm run build
    • Watch for changes: npm run watch (automatically rebuilds on file changes)
    • Build and run: npm run start (runs the plugin every time it is built)
    npm install
npm run build
npm run watch
npm run start

  7. Develop and run Sketch plugins with npm scripts

    develop

    When developing plugins using skpm, you can use the following npm scripts to manage the build and execution lifecycle:

    • npm run build: Compiles the plugin.
    • npm run watch: Watches for file changes and rebuilds automatically.
    • npm run start: Builds the plugin and runs it every time a build occurs.
    npm run build
npm run watch
npm run start

  8. Setup the Hello World plugin example

    develop

    To run the Hello World example, download the specific example directory, install its dependencies, and build the project. This example demonstrates how to add a menu command to the Plugins menu in Sketch.

    1. Download and enter the directory:
    curl https://codeload.github.com/sketch-hq/SketchAPI/tar.gz/develop | tar -xz --strip=2 SketchAPI-develop/examples/hello-world
cd hello-world
    1. Install dependencies:
    npm install
    1. Build the project:
    npm run build
    curl https://codeload.github.com/sketch-hq/SketchAPI/tar.gz/develop | tar -xz --strip=2 SketchAPI-develop/examples/hello-world
cd hello-world
npm install
npm run build

  9. Use the Sketch JavaScript API in scripts

    develop

    The Sketch JavaScript API is bundled with the Sketch Mac app. To use it, you must require('sketch') before calling any API methods. You can run scripts directly within Sketch via the Plugins › Run Script… panel.

    Commonly used modules include Group, Shape, and Rectangle for manipulating the document structure.

    // 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)
})

  10. Explore Sketch Plugin development examples

    develop

    The sketchapi repository contains several example plugins designed to demonstrate common development tasks. Use these examples to learn how to implement specific features:

    • Hello World: Learn how to add a custom command to the Plugins menu and execute code when that command is selected.
    • Resources: Learn how to bundle external resource files within your plugin and access them programmatically.
    • Selection Changed: Learn how to listen for the SelectionChanged action to trigger logic whenever a user modifies their selection in Sketch.
    • SVGO export: Learn how to hook into the ExportSlices action to automate post-export tasks, such as compressing SVG assets using SVGO.
    • Text Utilities: Learn how to manipulate and annotate text layers (e.g., showing baselines and bounding boxes) for debugging purposes.

  11. Install and run the Text Utilities example

    develop

    To use the Text Utilities example, download the specific example directory, install its dependencies, and use the provided npm scripts to build or run the plugin.

    Setup Steps

    1. Download and extract the example folder:
      curl https://codeload.github.com/sketch-hq/SketchAPI/tar.gz/develop | tar -xz --strip=2 SketchAPI-develop/examples/text-utilities
cd text-utilities
    2. Install dependencies:
      npm install

    Running the Plugin

    • Build the project: npm run build
    • Watch for changes: npm run watch (automatically rebuilds on file changes)
    • Build and run automatically: npm run start (runs the plugin every time it is built)
    curl https://codeload.github.com/sketch-hq/SketchAPI/tar.gz/develop | tar -xz --strip=2 SketchAPI-develop/examples/text-utilities
cd text-utilities
npm install
npm run build

  12. Install and run the Selection Changed example plugin

    develop

    To run this example plugin, download the source, install dependencies, and build the project. This example is built using skpm.

    1. Download the example:
    curl https://codeload.github.com/sketch-hq/SketchAPI/tar.gz/develop | tar -xz --strip=2 SketchAPI-develop/examples/selection-changed
cd selection-changed
    1. Install dependencies:
    npm install
    1. Build the project:
    npm run build
    1. Run in watch mode (for development):
    npm run watch
    curl https://codeload.github.com/sketch-hq/SketchAPI/tar.gz/develop | tar -xz --strip=2 SketchAPI-develop/examples/selection-changed
cd selection-changed
npm install
npm run build