Plugin Development - Any up-to-date resources available?

Share your knowledge Ask the community
1

I’m really lost on this one:

Months ago I started scripting my own little plugins for various repeating tasks I got. Following the API Documentation, I got the very basics up and running in no time. But oh boy, when I got to the “fancy” stuff, even Google and GitHub quickly ran out of answers or resources.

I dug deep into the structure of documents and layers and tried to reverse engineer my way through, but to the day I have found no reasonable method to deal with foreignObjects, foreignSwatches, foreignColors and their likes.

The very basics of retrieving the belonging swatches and names of colours in my document: unsolvable if not local.

So my question being: Are there any native workarounds tob expand the functionality of the incredibly limited js api?

Examples, hints, documentation, every snippet is welcome. The colour task is hunting me for weeks now and I’d love to put an end to it, and to others. Thanks in advance!

2

Hello and welcome to the forum :waving_hand:

First of all, please reconsider writing Sketch plugins in 2025. The whole plugin infrastructure is barely supported at this point, and Sketch folks made it clear that this won’t change anytime soon.

As someone who’s been building automation tools for Sketch practically full-time since 2016, the best advice I can give you is to spend your time and energy on something else, rather than fighting this never-ending uphill battle that is making a non-trivial Sketch plugin.

This advice comes from a place of huge love, not hate :yellow_heart:

Anyways, in order to deal with imported/foreign stuff you’d definitely need to drop to the native API layer.

Let’s say we have a Rectangle that references 2 color variables:

  • My Pink is a document-local variable used as a border color
  • Apple iOS UI / System Colors / systemGreen – Dark is a variable we’ve imported from the “Apple iOS UI” library, used as a fill color

Screenshot 2025-04-30 at 12.54.47
Screenshot 2025-04-30 at 12.54.47948×404 23.5 KB

Now, let’s start by taking this selected Rectangle and extracting raw native color objects from its fill and border:

const Document = require('sketch/dom').Document
const Swatch = require('sketch/dom').Swatch
const { toArray } = require('util');

const document = Document.getSelectedDocument()
const layer = document.selectedLayers.layers[0]

// These are native MSColor objects
const borderColor = layer.style.borders[0].sketchObject.color()
const fillColor = layer.style.fills[0].sketchObject.color()

The next step is to use find out if those native color objects have a reference to a swatch:

function swatchForMSColor(nativeColor) {
  const documentData = nativeColor.documentData()
  const swatchID = nativeColor.swatchID()
  if (!swatchID) { return null }
  
  return Swatch.from(documentData.swatchWithID(swatchID))
}

const borderColorSwatch = swatchForMSColor(borderColor)
const fillColorSwatch = swatchForMSColor(fillColor)

These swatches are some actual Sketch JS API objects so they print nicely and everything. The problem is that we don’t know which one is local and which one is imported from a library (and which library?). Let’s refactor swatchForMSColor() a bit and inject a few useful helper methods into the resulting swatch object:

Disclaimer: I’ve no idea how to write JavaScript when it comes to objects and classes. The code below works, but there’s probably a more idiomatic way to do it.

function swatchForMSColor(nativeColor) {
  const documentData = nativeColor.documentData()
  const swatchID = nativeColor.swatchID()
  if (!swatchID) { return null }
  
  let swatch = Swatch.from(documentData.swatchWithID(swatchID))
  
  // Returns an actual foreign swatch object if any
  swatch.foreignReference = function () {
    const nativeObject = this.sketchObject
    const allForeignSwatches = toArray(nativeObject.documentData().foreignSwatches()) || []
    return allForeignSwatches.find((s) => s.localSwatch().objectID().isEqualToString(nativeObject.objectID()))
  }
  // Returns `true` if this swatch comes from a library
  swatch.isImported = function() {
    return !!this.foreignReference();
  }
  // Returns a source library identifier for this swatch if one is available
  swatch.libraryID = function() {
    if (!this.isImported()) return null;
    return this.foreignReference().libraryID()
  }
  // Returns a source library name for this swatch if one is available
  swatch.libraryName = function() {
    if (!this.isImported()) return null;
    return this.foreignReference().sourceLibraryName()
  }

  return swatch
}

With that new code in place, let’s see which of those swatches is which:

console.log(`Is border color a variable? ${!!borderColorSwatch}`)
console.log(`    The variable name is "${borderColorSwatch.name}"`)
console.log(`Is border color a *library* variable? ${borderColorSwatch.isImported()}`)

// Is border color a variable? true
//     The variable name is "My Pink"
// Is border color a *library* variable? false

console.log(`Is fill color a variable? ${!!fillColorSwatch}`)
console.log(`Is fill color a *library* variable? ${fillColorSwatch.isImported()}`)
console.log(`Fill color variable "${fillColorSwatch.name}" comes from library "${fillColorSwatch.libraryName()}" (${fillColorSwatch.libraryID()})`) 

// Is fill color a variable? true
// Is fill color a *library* variable? true
// The color variable "System Colors/systemGreen - Dark" comes from library
//   "Apple iOS UI"  (DD59C2AC-DA86-465C-B5D7-FC1979E0DDB8)

Hope it helps!

3 Likes
3

this is sooo sad :frowning:

3 Likes
4

Whether it helps? Good lord, you basically did all the work for me, and yes, it will help and solve my task. Wow. :heart: Thank you!!!

I’ll never understand companies treating their development community this way, and usually, that behaviour makes them go out of business sooner or later. Let’s hope that’ll be different in this case.

So, a follow up question: is the native stuff documented somewhere? I’m not too lazy to look stuff up but really couldn’t find anything useful so far … :smiling_face_with_tear:

5

Well, the UI design world today is very different from what it was years ago when Sketch pioneered the field. Back then it was mostly power users who felt limited by contemporary design tools and wanted to do things differently: using vector graphics, thinking in terms of components, and automating their workflows – and it was power users again who drove Sketch sales and influenced its adoption by a broader design community.

Those power users still exist today, but they are no longer the driving force they used to be. So it makes sense for Sketch to shift focus and invest their limited resources towards things the broader design community would likely appreciate, which is everything besides plugins and integrations I guess?

Ah well, not really no. I guess you could get some insight into the Sketch internals by looking at Sketch JS API source code (which is built on top of native APIs), but for the most part you’d have to reverse-engineer Sketch binaries directly.

And of course I’d be happy to point you to the right direction if you have a specific request/question regarding the API :raising_hands:

1 Like
6

This thread saddens me. I remember reading some vague allusion to some bone being thrown to plug-in developers, but no news since.

Incidentally and anecdotally, I see a lot of conversation around the perceived lack of plugins and community resources for sketch compared to Figma. I think they need to do something

2 Likes
7

I just realized that since Sketch is making ground-breaking changes in the next update, it means most of the (still somewhat working) third-party plugins will be rendered completely broken.

This of course has happened numerous times before with major Sketch updates, and it was never a big deal. But this time it is a bug deal, because this time there’s no developer community left to step in and fix those vital plugins.

(the below passage is directed at Sketch folks, in the unlikely event they end up in this thread)

I see Sketch making attempts to contact some of the plugin developers and encourage them to update their plugins?

Screenshot 2025-05-03 at 11.36.29
Screenshot 2025-05-03 at 11.36.291572×792 74.8 KB

The thing is – and please take it as a healthy bit of criticism from someone so invested in Sketch that I still frequent this forum despite no longer being paid to work in/on the ecosystem –

Your wording here is tone-deaf at best, and insulting at worst:

Screenshot 2025-05-03 at 18.19.13
Screenshot 2025-05-03 at 18.19.131674×434 50.1 KB

If I recall correctly, you’ve made a concise decision to abandon third-party developers:

  1. by soft-deprecating the current plugin system without actually telling anyone it’s being deprecated
  2. by throwing a shade at the developer community because we couldn’t build anything non-trivial with the limited and stagnating JS API (which was already soft-deprecated by you at this point, and thus getting no updates, or really just a clear vision for its future) – so we had to rely on unsafe and flaky native APIs.
  3. not providing an API backwards compatibility shim in the upcoming Sketch update so that older plugins would remain operational (or maybe I just missed that, in which case please forgive my ignorance)

And now you basically say “hey please consider updating your plugins you haven’t been working on for years since you burned out of Sketch plugin ecosystem – because apparently our customers need your plugins to work, and they will complain to us about this, and it’s bad for business”.

I don’t know, it’s tacky. You could’ve just go to this forum (because you’ve shut down that one other place that was arguably a way better option for this kind of communications), find 2 or 3 people (me included) who frequently chime in plugin-related threads, and just ask nicely if we’d like to work on fixing some open-source (or even closed-source) plugins for funs and maybe a honorable mention somewhere. This would work on me personally.

7 Likes
8

@rodionovd We appreciate all your help and the time you’ve spent working on this. We understand your frustration and apologise for the current situation.

Our communication should be more clear. We are discussing this topic internally, and once we have more details, we’ll share a clearer and more detailed explanation of our plans for plugins in the future.

2 Likes
10

Hey again, your hints guided me all the way through my recent projects, but unfortunately I’m stuck again (thought that would happen earlier, though :wink: ) - do you (or anyone else here) possibly know:

  1. how to parse the structure of a symbol instance and override attributes?

I can get as far as exposing the overrides and manipulating them, still, I’d love to display the structure in a treelike form, the way it shows up in the layer manager - and THEN override what can be overridden…

Any hints would be highly appreciated. Thanks in andvance, CM

EDIT: I already do so for groups and other elements successfully, but it seems to be a whole different story with symbol instances…

11

Hello there :waving_hand:

Well, diving into symbol instances is a little bit complicated indeed. Essentially you want to “detach” an instance into a group, but not actually detach it :sweat_smile:

I’m away from my Mac until next week, but I’ve used this approach before and it works:

Beware tho that children layers of this new “detached copy” will have different IDs than the children of an original symbol — so matching overrides there could be problematic (as they are based on layer ids).

One thing I’ve done in the past to mitigate this is

  1. avoid detaching symbols recursively: only go one layer of symbol hierarchy at a time
  2. upon detaching a top-level symbol, iterate all of its children layer and re-assign layer ids to match this symbol master’s layers (they will be in the same order, so a simple loop will do)
  3. continue detaching any symbols that are children of the one you’ve just detached (ie go to step 1)

This way you’ll be able to preserve all layer ids intact in order to match them to overrides.

Alternatively, on the 2nd step, you may just grab the new layer ids and remember how they map to original ids.

(Sorry for the long post: I’d written a shorter one if I had more time etc :sweat_smile:)

12

Perfect, again.

Still, I seem to get lost with overrides. While with symbols it was “easy” to determine the colors and swatches, I just can’t figure out the path from each overrides data to the connected swatch from an external library, like in the attached example. any hints, again?

'Override 19:'
'{
      "type": "Override",
      "id": "7E63528C-5AC9-48B2-96B4-CAEDBFE11546_color:fill-0",
      "path": "7E63528C-5AC9-48B2-96B4-CAEDBFE11546",
      "property": "color:fill-0",
      "affectedLayer": {
            "type": "ShapePath",
            "id": "7E63528C-5AC9-48B2-96B4-CAEDBFE11546",
            "frame": {
                  "x": 3,
                  "y": 3,
                  "width": 24,
                  "height": 24
            },
            "name": "Oval",
            "hidden": false,
            "locked": false,
            "exportFormats": [],
            "transform": {
                  "rotation": 0,
                  "flippedHorizontally": false,
                  "flippedVertically": false
            },
            "style": {
                  "type": "Style",
                  "id": "26CF2785-F351-4179-8FA7-7F2978BDDAE0",
                  "opacity": 1,
                  "blendingMode": "Normal",
                  "borderOptions": {
                        "startArrowhead": "None",
                        "endArrowhead": "None",
                        "dashPattern": [],
                        "lineEnd": "But",
                        "lineJoin": "Miter"
                  },
                  "blur": {
                        "center": {
                              "x": 0.5,
                              "y": 0.5
                        },
                        "motionAngle": 0,
                        "radius": 10,
                        "enabled": false,
                        "blurType": "Gaussian"
                  },
                  "fills": [
                        {
                              "fillType": "Color",
                              "color": "#ff410cff",
                              "gradient": {
                                    "gradientType": "Linear",
                                    "from": {
                                          "x": 0.5,
                                          "y": 0
                                    },
                                    "to": {
                                          "x": 0.5,
                                          "y": 1
                                    },
                                    "aspectRatio": 0,
                                    "stops": [
                                          {
                                                "position": 0,
                                                "color": "#ffffffff"
                                          },
                                          {
                                                "position": 1,
                                                "color": "#000000ff"
                                          }
                                    ]
                              },
                              "pattern": {
                                    "patternType": "Fill",
                                    "image": null,
                                    "tileScale": 1
                              },
                              "enabled": true
                        }
                  ],
                  "borders": [],
                  "shadows": [],
                  "innerShadows": [],
                  "styleType": "Layer",
                  "fontAxes": null
            },
            "sharedStyleId": "A481DF8A-413F-49D8-9AAE-25D0AE6D4B3F[B85B9D07-979D-4950-AE7F-6B35D8F416C1]",
            "shapeType": "Oval",
            "points": [
                  {
                        "type": "CurvePoint",
                        "cornerRadius": 0,
                        "curveFrom": {
                              "x": 0.7761423749,
                              "y": 1
                        },
                        "curveTo": {
                              "x": 0.2238576251,
                              "y": 1
                        },
                        "point": {
                              "x": 0.5,
                              "y": 1
                        },
                        "pointType": "Mirrored"
                  },
                  {
                        "type": "CurvePoint",
                        "cornerRadius": 0,
                        "curveFrom": {
                              "x": 1,
                              "y": 0.2238576251
                        },
                        "curveTo": {
                              "x": 1,
                              "y": 0.7761423749
                        },
                        "point": {
                              "x": 1,
                              "y": 0.5
                        },
                        "pointType": "Mirrored"
                  },
                  {
                        "type": "CurvePoint",
                        "cornerRadius": 0,
                        "curveFrom": {
                              "x": 0.2238576251,
                              "y": 0
                        },
                        "curveTo": {
                              "x": 0.7761423749,
                              "y": 0
                        },
                        "point": {
                              "x": 0.5,
                              "y": 0
                        },
                        "pointType": "Mirrored"
                  },
                  {
                        "type": "CurvePoint",
                        "cornerRadius": 0,
                        "curveFrom": {
                              "x": 0,
                              "y": 0.7761423749
                        },
                        "curveTo": {
                              "x": 0,
                              "y": 0.2238576251
                        },
                        "point": {
                              "x": 0,
                              "y": 0.5
                        },
                        "pointType": "Mirrored"
                  }
            ],
            "closed": true
      },
      "symbolOverride": false,
      "value": "(r:1.000000 g:0.254902 b:0.047059 a:1.000000)",
      "isDefault": false,
      "editable": true,
      "selected": false
}'
'  Property: color:fill-0'
'  Path: 7E63528C-5AC9-48B2-96B4-CAEDBFE11546'
'  Value: "(r:1.000000 g:0.254902 b:0.047059 a:1.000000)"'