Norem Ipsum
πββοΈ This repository contains a sample Sketch Assistant.
Skills needed
- JavaScript and TypeScript
- npm
- Git
Tools
These tools are required to work on the Assistant locally.
- Node 12
- Yarn
- Visual Studio Code (recommended)
Testing the Assistant
The Sketch Mac app isn't required to test the Assistant and run the Jest tests. So a TDD approach using Sketch files as fixtures represents the fastest route to running your Assistant and checking that it's working as expected.
The tests can be run in watch mode for live feedback as you work.
yarn test --watch
Testing using Github Actions
If you want to run the tests automatically whenever a pull request is opened then enable the included "Test Pull Requests" Github Action.
- Ensure Github Actions are enabled for your repository.
- Rename
.github/workflows/test-pull-requests.yml.sample
to.github/workflows/test-pull-requests.yml
. - Open a pull request, and the test status should be reported.
Building a local development Assistant
The next quickest way to get the Assistant running is to build it locally and add it directly to a Sketch document.
- Run
yarn package-tarball
. - Note that a
*.tgz
tarball has been built to the repository root. - Use the Install from disk option in Sketch's Assistants menu to add the freshly built Assistant to a document.
- Sketch will check the disk location for updates to the tarball, so you can continue to re-build the Assistant to the same location and see live updates in Sketch
β οΈ Assistants must be published to be used across multiple devices or within a team. Sketch documents with local Assistants added to them are not portable because the Assistant is referenced using a file path.
Publish the Assistant
In order for others to use your Assistant via the Install from URL option in Sketch its *.tgz
tarball package needs to be hosted publically on the web.
Following is a guide describing how to publish an Assistant to npm.
- Review the npm documentation to familiarize yourself about publishing packages, but read on for a quick guide.
- Ensure you have an npm account and are logged-in to npm on the command line via
npm login
. - Update your Assistant code as needed, implement any rules you want to and ensure any tests are passing.
- Ensure the
name
field in package.json has been set to a valid, unique npm package name. - Ensure the
version
field in package.json is updated to reflect the version you want to publish. - Run
yarn build
to prepare the Assistant for publishing. - Run
npm publish
. - After publishing is complete run
npm info <your-package-name>
, and take note of the distribution tarball url ending*.tgz
. Copy and pasting this into the Install from URL dialogue box in Sketch will result in a shareable Sketch document with your Assistant added and ready-to-go.