Totally understand your confusion (there are lots of new developers that share your confusion!).
A bit of context
The Actions api (https://developer.sketch.com/plugins/actions) is older and hence why many of the tutorials on the web refer to that. The Action API is different than the JS API. In particular the Action API is, "a way to let plugins react to events in the app” whereas the JS API is used for interacting with Sketch objects.
In the past, there was no JS API so in order to interact with Sketch objects you would need to use the Sketch Headers (https://github.com/abynim/Sketch-Headers) to access the underlying internal API. You can read a bit more about this here (https://developer.sketch.com/plugins/internal-api).
Nowadays, the JS API wraps the native Sketch model objects inside javascript objects so you don’t need to look at the headers. You can drop down to the native Sketch objects at any time however the JS API is fully supported by Bohemian between releases (ie they try not to change it, unlike the internal API which they can and do change whenever they need to).
In Practice
So now that we got that bit of context out of the way, how do you put this into practice? Well, you can use the JS API by its self. (Follow along in the script panel! Plugins > Run Script…)
JS API
To get the current document and the selected page with the JS API you can do this:
let sketch = require('sketch')
let document = sketch.getSelectedDocument()
let page = document.selectedPage
Be sure to log each of those objects and check out their structure.
Action API & Native Objects
You can also use the Action API. context
is available in the script panel as well.
console.log(context)
This will return a dictionary of useful objects. Probably the most useful of the bunch are document
and selection
.
let nativeDocument = context.document
console.log(nativeDocument)
// <MSDocument: 0x7fd0615f0a10>
You’ll see it returns this MSDocument
object. All native sketch objects start with MS (I remember reading why in the past by I forget). To know where currentPage()
is coming from you will need to look at those sketch headers that I mentioned earlier.

The method currentPage
on MSDocument
can be found here https://github.com/abynim/Sketch-Headers/blob/master/Headers/MSDocument.h#L56
So great now you have the currentPage
let nativeDocument = context.document
let nativePage = nativeDocument.currentPage()
console.log(nativePage)
// <MSPage: 0x7fd0615de890>
but now how do you interact with MSPage
? Well, you look through the Sketch headers again 🙃. This process is really opaque and the methods on each of the objects can change from release to release so I don’t recommend this.
Bridging between the JS API and Native Sketch Objects
The JS API provides a handy way for taking a native Sketch Object and converting it to a JS object. You can do so with this
let sketch = require('sketch')
let nativeDocument = context.document
let wrappedDocument = sketch.fromNative(nativeDocument)
console.log(wrappedDocument)
Now this won’t work with all Native Sketch objects but it will work for the most common ones (the ones that the JS API has wrapped).
You can also go the other direction and get at native objects with this
let sketch = require('sketch')
let document = sketch.getSelectedDocument()
let nativeDocument = document.sketchObject
console.log(nativeDocument)
This info and more can be found in the JS API documentation here: https://developer.sketch.com/reference/api/#sketch-components
Using the Action API with the JS API
I rely on the Action API to trigger bits of code depending on what the user is doing. One common action to listen for is selectionChanged
. You will need to register your plugin to “listen” for this action by setting it up in your plugin’s manifest.json
file. I won’t go into the setup details for that (you can learn more about it here https://developer.sketch.com/plugins/actions#how-do-i-register-my-plugin-to-listen-for-an-action) and in the end you will have some function in your JS file like this.
export function onSelectionChanged(context) {
// ### Extracting Context Information
// Whenever sketch calls a handler in one of our plugins, it passes in a single context argument.
// This dictionary is our connection with Sketch itself, and contains all the information that
// we need to work out which document was open, perform whatever task we want to on it, and so on.
//
// When we're being called in response to an action occurring, the context will contain
// an actionContext property with additional information about the action, so that's the first
// thing that we want to retrieve:
const action = context.actionContext
// The context information for each action will be different. For the SelectionChanged action,
// we are passed three interesting values: which document the selection has changed in,
// what the old selection was, what the new selection is (or will be).
// For our purposes, we can ignore the old selection, but we need the other two values.
// let's wrap the native document
const document = sketch.fromNative(action.document)
// and transform the NSArray that is `newSelection` into a proper array
const selection = toArray(action.newSelection)
This is code taken from one of the plugin examples (https://github.com/BohemianCoding/SketchAPI/blob/develop/examples/selection-changed/src/selection-changed.js#L20)
An alternative approach is to just ignore the context and just use the JS API. I tend to go this route whenever I don’t need anything specific from the context
let sketch = require('sketch')
export function onSelectionChanged() {
let document = sketch.getSelectedDocument()
// interact with the document at the time when this function is triggered
}
Tip:
To know what Action to listen for you can use the fantastic Sketch-dev-tools plugin (https://github.com/skpm/sketch-dev-tools)
Flip to the Actions tab and interact with sketch to see what Action is triggered when.

I realize its a bit of a long winded post about your issue but I hope that clarifies some things! If you are wanting to learn more about how to use the JS API I wrote an introduction here: https://medium.com/@kevingutowski/how-to-build-your-first-sketch-plugin-14c0e9e56bf0