Publish Assistants

We’re retiring the Assistants feature later in 2023 — but you can still use it with older versions of Sketch, or with the Command Line Interface. Find out more

Publish your Assistant so it can be downloaded automatically whenever a document using it is opened with Sketch. Opt in to be included on the Sketch Assistant directory.

We recommend publishing to npm as this makes your Assistant package easily accessible to others and requires only some addition metadata to get listed on the Assistant directly. However, self-hosting your Assistant is also an option.

Publish to npm

Below is a list of steps to publish your Assistant to npm. For more information on publishing JavaScript packages see the documentation.

Note: You’ll need a free npm account to publish to the npm registry.

  1. Ensure you are logged-in to npm on the command line via npm login.
  2. Update your Assistant code as needed, implement any rules you want to and ensure any tests are passing.
  3. Ensure the name field in package.json has been set to a valid, unique npm package name.
  4. Ensure the version field in package.json is updated to reflect the version you want to publish.
  5. Run the build process for your Assistant.
  6. Run npm publish. Your Assistant package should now be live 🎉

To confirm the package has been published successfully, request the metadata running the following command:

npm info <your-package-name>

Add your npm Assistant to a Sketch document by copy and pasting the tarball value from the above output and adding it to a Sketch document via the ⚙️ › Add from URL… option within the Manage Assistants… sheet for your document.

A Sketch document configured with a published Assistant is truly portable - other users will be prompted to install the exact same Assistant package when they open the document.

Self-hosting

There is no strict requirement that your Assistant is published to npm. As long as your Assistant package is hosted somewhere on the web, accessible to your intended audience, it can be added to Sketch documents and shared.

Running the following command in an Assistant generated with our Sketch Assistant Template repository creates a .tgz archive in the current working directory.

npm run package-tarball

Once the resulting .tgz archive is uploaded, add the Assistant to a Sketch document via the ⚙️ › Add from URL… option within the Manage Assistants… sheet for your document.

Update published Assistants

Sketch does not check if there are newer versions of your published Assistant, so it won’t automatically prompt users to update Assistants added to documents.

If there’s a newer version of an Assistant available, and you want to update a document to take advantage of it you’ll need to re-add the Assistant to that document. Either via the ⚙️ › Add from Archive… option within the Manage Assistants… sheet for your document, or add the Assistant again from sketch.com.

Sketch Assistant directory

Including your Assistant in the directory makes it more discoverable for Sketch users and is directly accessible through the Find Assistants… menu item in Sketch.

  1. One-click Add to Sketch button to add an Assistant to the current document
  2. Assistants are organised by pre-defined categories
  3. Detail page generated from the Assistant’s README.md documentation

Checklist

Use the following checklist to get your Assistant included in the Sketch Assistant directory.

Include correct metadata in package.json

  • Version number, must be 1.0.0 or greater
  • Relative path pointing to a built, single-file bundle of your Assistant, e.g. dist/sketch.js

  • Values for display title, description and icon in sketch-assistant.

    "sketch-assistant": {
  "title": "Naming Conventions",
  "description": "Naming conventions used by the Sketch design team",
  "icon": "https://user-images.githubusercontent.com/1078571/81808046-0a6e2b00-9517-11ea-9b6c-1c6fa9a377ba.png"
}

  • Link to the Assistant documentation in homepage. This can be your own website or the Assistants directory detail using the following URL format:

    https://sketch.com/extensions/assistants/{assistant-package-name}`

    See Tidy for reference

  • Author object, containing at least a name string. It is recommended to include an email address for support.
  • Keywords sketch assistant and public to opt in to be indexed by the Assistant directory, see full list

Prepare documentation in README.md

  • Do not include Add to Sketch links or buttons
  • Document rule and configuration choices

Publish to npm

  • Publish to npm as described above
  • Confirm the Assistant appears in the search results for the sketch-assistant and public keywords. Please note, it can take a while until it is included in the results.

README.md best practices

The README.md Markdown contents are used to generate the Assistant’s directory detail page.

  • Do not start with the title or description used in package.json, start with a summary of the rules the Assistant contains and why.
  • Do not include the Assistant icon.
  • Document what each rule does.
  • Provide examples of do’s and don’ts, with images if helpful.

  • Use HTML fragment identifiers for each rule following the {assistant-package-name}/{rule-name} convention. This is used by Sketch to link to detailed rule documentation, e.g. any Assistant using the groups-max-layers rule.

    <h1 id="@sketch-hq/sketch-core-assistant/groups-max-layers">Groups should contain no more than 10 layers</h1>

Pre-defined categories

To make it easier to find the right Assistant, the directory uses a set of predefined categories. Consider assigning your Assistant one or more of the below category keywords. The first of these keywords specified in the array will be used as your Assistant’s primary category.

  • guidelines
  • organization
  • accessibility
  • ios
  • mac
  • windows
  • web
  • android