Types
Sketch Assistants are defined by building up simple data structures that conform to the Sketch Assistant Types.
By making sure your Assistant strictly matches the types you ensure that your Assistant is compatible with Sketch. The best way to do this is to let the TypeScript compiler to do it for you!
If you created your Assistant project using our Sketch Assistant Template then you’re already setup for TypeScript, and editors like Visual Studio Code will provide rich type information and intellisense that will help you find your way.
🙋♀️ The best way to introduce yourself to Assistants is by following our Getting started guide, but continue reading if you’re ready for a deeper dive into the types.
AssistantPackage
The AssistantPackage
is the top-level type, and defines the expected default export from an Assistant JavaScript package. Fundamentally an AssistantPackage
is an async
function that returns an AssistantDefinition
.
(env: AssistantEnv) => Promise<AssistantDefinition>
The function is async
to give you an opportunity to perform asynchronous setup work before your Assistant rules are run, if necessary.
The AssistantEnv
argument contains information about the outer environment, including the current language locale which could be used to internationalize your Assistant.
💡 Note that it is also valid for
AssistantPackage
to be an array of functions, this is to support extending Assistants.
AssistantDefinition
AssistantDefinition
is a plain object collecting the rules and configuration together.
Property | Type | Description |
---|---|---|
name |
string |
Your Assistant package name, this should precisely match the name property in your package.json |
rules |
RuleDefinition[] |
An array of RuleDefinition objects |
config |
AssistantConfig |
An object where you can turn rules on and off, as well as configure them with option values if required |
💡 Additional Assistant metadata, like a human readable
title
anddescription
are defined in package.json not in source code. This is to avoid having to execute JavaScript in order to discover this sort of Assistant metadata. Check our Sketch Assistant Template for an example package.json file or follow our publishing guide for more information.
RuleDefinition
A RuleDefinition
is a plain object that fully defines a rule.
Property | Type | Description |
---|---|---|
rule |
RuleFunction |
Function that implements the rule logic |
name |
string |
Unique identifier for your rule, by convention prefixed with the AssistantDefinition name , e.g. my-assistant/my-rule |
title |
string orobject => string |
Human readable title for the rule, or alternatively a title as a function of the rule’s configuration (allows for option values to be interpolated into the string) |
description |
string orobject => string |
Human readable description for the rule, or alternatively a description as a function of the rule’s configuration (allows for option values to be interpolated into the string) |
getOptions? |
RuleOptionsCreator |
Optionally describe your rule’s configuration options with JSON Schema. By providing schema you enhance error messages for incorrectly configured options, and ready your Assistant for possible future work around Assistant creation GUIs. See the Core Assistant rules for examples |
debug? |
boolean |
Flag a rule for development use only |
runtime? |
AssistantRuntime |
Indicate whether your rule isn’t cross platform, and only works in Sketch or Node |
RuleFunction
A RuleFunction
is an async
function that performs the rule’s logic using a RuleContext
argument.
(context: RuleContext) => Promise<void>
💡 You should be able to implement your rule by using the objects and helpers coming in on the
context
argument, but it’s worth remembering that you can use npm modules in your rule functions too - as long as they don’t use Node or browser APIs that aren’t available in Sketch’s JavaScriptCore environment.
RuleContext
The RuleContext
object is passed as an argument to every RuleFunction
. It contains a representation of the Sketch document currently being processed as well as helper functions.
Property | Type | Description |
---|---|---|
utils |
RuleUtils |
Rule helpers |
file |
ProcessedSketchFile |
Representation of the current Sketch document |
assistant |
AssistantDefinition |
Parent Assistant |
env |
AssistantEnv |
Same object passed into the top-level AssistantPackage function |
RuleUtils
The RuleUtils
object contains helper functions that are scoped to the current rule.
Property | Type | Description |
---|---|---|
report |
(string, ...SketchFileObject[]) => void |
Report a problem to Sketch from the current rule. Optionally include one or more references to document objects where the issue resides |
objects |
IterableObjectCache |
An object containing iterators for each type of object found in a Sketch document. Enables efficient traversal of specific object types in rule functions - for example, looping all Artboards. Objects imported from libraries are excluded |
foreignObjects |
IterableObjectCache |
Identical to objects , except it only iterates objects imported into the Sketch document from libraries |
isObjectIgnored |
SketchFileObject => boolean |
Determine whether an object has been ignored in the Sketch UI. Generally this is handled for you, but if you’re seeing rule errors saying you’re trying to report an ignored object then you may need to use this function to make a manual check before calling report |
shouldExitEarly |
() => boolean |
If you’re seeing performance problems, especially while doing expensive work then call this function to determine whether your rule should break out of any loops and exit early |
getOption |
string => unknown |
Return the value of one of your rule’s options by name. If a value for the option is missing in the Assistant configuration then a rule error is thrown |
getImageMetadata |
string => Promise<ImageMetadata> |
Function that returns metadata about images in the current Sketch document |
getObjectParent |
SketchFileObject => unknown |
Returns an object’s parent in the document tree |
getObjectParents |
SketchFileObject => unknown[] |
Returns all of an object’s parents up to the root object in the document tree |
getObjectPointer |
SketchFileObject => string |
Returns the RFC 6901 JSON Pointer string for a document object |
evalPointer |
string => unknown |
Evaluates an RFC 6901 JSON Pointer in the context of the current Sketch document |