Assistants will benefit from web services that performs the following tasks:
- Facilitates one-click installs (required for launch)
- Sits in-between Sketch and the npm registry API, and provides Assistant package metadata (only required once we add support for Npm Assistants to Sketch, not required while we only support Url Assistants)
Read on more for more details.
Glossary
- Url Assistant An Assistant added to a Sketch document via a name and a fully qualified url to a hosted tarball. This sort of Assistant is technically unversioned, it just exists at a url.
- Npm Assistant An Assistant added to Sketch via a npm package name and semver. This sort of Assistant is versioned, and Sketch will be able to let a user know when the Assistant in their document can be updated etc.
One click installs
Using a web service here, instead of users crafting the sketch://
protocol deep-links themselves gains us the following advantages:
- One click install links can be added to websites that strip non-standard protocols from links (i.e. GitHub)
- We can find out the latest version of the package automatically, rather than a user having to keep their links up to date
- If we need to change something about the implementation in Sketch, or adjust the protocol we have a central place to do that, without invalidating links in use by 3rd parties
- Example of this will be when we transition from only supporting Url Assistants to supporting Npm Assistants we can just make that change in this web service and change the behaviour centrally
Already have a proof of concept that is being used in the wild at the moment, so should just be a case of reworking this.
Url Assistants behaviour
This is the behaviour of the current proof of concept.
- User clicks a link to the service, indicating the npm package name of the Assistant they want to add to their Sketch document
- Various options can be supplied (e.g. tag or latest version etc, Sketch variant for the deep link etc.)
- The service queries the npm API to resolve a fully qualified tgz url for that Assistant package
- The service redirects to the
sketch://
deep link protocol, and asks the Sketch to add it as a Url Assistant
Npm Assistant behaviour
This won't be required until we support Npm Assistants.
Path and options would change minimally between the two behaviours, so we could just switch it over when Npm Assistants are released.
- User clicks a link to the service, indicating the npm package name of the Assistant they want to add to their Sketch document
- Various options can be supplied (e.g. tag or latest version etc, Sketch variant for the deep link etc.)
- The service queries the npm API to determine which semver should be used
- The service redirects to the
sketch://
deep link protocol, and asks Sketch to add it as a Npm Assistant
Sketch Npm Proxy
This won't be required until we support Npm Assistants.
This could begin life as a single endpoint, where Sketch could ask for metadata about Npm packages, and get back information.
Using a web service here will insulate Sketch from any changes or rough edges in the npm API.
- List available versions for each Assistant
- Expose human readable metadata for each Assistant for display in Sketch UI
- List full tarball urls for each version
- List any tags (there'll always be at least a
latest
tag, for example)
So if Sketch posted the following JSON to the endpoint (i.e. one or more Assistant names)
[
"@sketch-hq/sketch-tidy-assistant"
]
It would get back something like
{
"@sketch-hq/sketch-tidy-assistant": {
"title": "Tidy Assistant",
"description": "Blah",
"icon": "https://www.domain.com/icon.png",
"tags": {
"latest": "5.0.1"
},
"versions": {
"5.0.1": "https://registry.npmjs.org/@sketch-hq/sketch-tidy-assistant/-/sketch-tidy-assistant-5.0.1.tgz",
"5.0.0": "https://registry.npmjs.org/@sketch-hq/sketch-tidy-assistant/-/sketch-tidy-assistant-5.0.0.tgz",
"4.1.0": "https://registry.npmjs.org/@sketch-hq/sketch-tidy-assistant/-/sketch-tidy-assistant-4.1.0.tgz",
...
}
},
...
}
Technology choices
- Are we happy with Vercel?
- It natively supports TypeScript, which is nice
- Are there other options? Netlify functions?
- Netlify functions seem a little more basic than Vercel (no edge caching, locked to US AWS region by default, no TypeScript support)
- Something more homegrown, and/or owned by our backend team?
- Scalability?
Domain
Perhaps something like assistants.sketch.com
?