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.

1. Ensure Github Actions are enabled for your repository.
2. Rename .github/workflows/test-pull-requests.yml.sample to .github/workflows/test-pull-requests.yml.
3. 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.

1. Run yarn package-tarball.
2. Note that a *.tgz tarball has been built to the repository root.
3. Use the Install from disk option in Sketch's Assistants menu to add the freshly built Assistant to a document.
4. 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.

1. Review the npm documentation to familiarize yourself about publishing packages, but read on for a quick guide.
2. Ensure you have an npm account and are logged-in to npm on the command line via npm login.
3. Update your Assistant code as needed, implement any rules you want to and ensure any tests are passing.
4. Ensure the name field in package.json has been set to a valid, unique npm package name.
5. Ensure the version field in package.json is updated to reflect the version you want to publish.
6. Run yarn build to prepare the Assistant for publishing.
7. Run npm publish.
8. 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.