Figure out how Spoons and third party JS functionality should be installed/distributed

[cmsj]

Introduction

This issue exists to discuss/explore our options for two things:

1. Distribution and Installation of Spoons
2. Installation of third party libraries

These two things are being considered at the same time because they are closely related.

---

Spoons

A non-goal here is to maintain an "official" repository of Spoons. It proved to be a painful chokepoint in Hammerspoon 1, that we should not repeat.

Distribution

Options:

1. Manual downloading of .spoon bundles
2. npm

Manual downloading is obviously a very easy thing to provide, and it can be augmented with supporting mechanisms within Hammerspoon. npm provides all of that mechanism already, at the cost of requiring external tooling.

Installation

If we choose manual downloading of .spoon bundles, they can be opened with Hammerspoon and automatically unpacked into ~/.config/hammerspoon2/Spoons/. They can then be loaded with Hammerspoon 2's current, naive require().

If we choose npm then the user will need to use npm and some kind of tooling to prepare the Spoon files in ~/.config/hammerspoon2/ somewhere. They can then be loaded as modules with the mechanism from either #6 or #145.

Third party libraries

If this is something we want, there is really no better option than npm and a bundler.

It is not entirely clear how common it will be for users to want to install third party JS libraries from npm - many of them will depend on either Node or Browser runtime functionality that Hammerspoon 2 doesn't offer, however, it does seem somewhat likely that amongst the vast number of npm modules, there are some relevant/useful options.

On the assumption that installing modules from npm is desirable, a good number of Hammerspoon 2 users will be installing npm and some kind of bundler, and will want either #6 or #145 to be merged. That being the case, there seems to be a stronger argument for distributing/installing Spoons via npm too.

Discussion

It would be very helpful to hear from a number of voices on this subject.

[cmsj]

#6 and #145 are related

[cmsj]

Paging @alkene5 @gwww @latenitefilms @asmagill for opinions, feel free to tag others :)

[gwww]

The AstroNvim community model might have some ideas that could be pulled from.

https://github.com/AstroNvim/astrocommunity

[asmagill]

I haven't used npm beyond following explicit instructions given for other projects I've tested or used, so I know basically nothing about it.

That said, I think we need to include support for it... I remember early discussions for Hammerspoon about LuaRocks and using various other third party lua projects -- there will be many questions if we don't.

...install third party JS libraries from npm - many of them will depend on either Node or Browser runtime functionality that Hammerspoon 2 doesn't offer...

Again, pardon my ignorance of node/npm, but is it in any way possible that we can integrate with or support these in any way? Is it a series of API calls we'd need to support, or functionality? What would we need to support to allow the use of Node and/or Browser?

Hammerspoon does have a full web server (single threaded, unfortunately, but still...) built in; I would assume we'd want Hammerspoon 2 to as well... I don't know if that helps the question of Browser support or not, but I thought I'd bring it up.

[alkene5]

Since installing third-party libraries already requires dealing with npm, I think it makes sense to use npm for distributing Spoons as well. Otherwise, we would have to maintain two separate installation/distribution mechanisms.

Regarding CJS vs ESM, CommonJS is indeed simpler, but ESM is the more modern approach. I'm not sure which one would be the better choice here.

However, one thing we could definitely do is provide an npm package like @hammerspoon/api or @types/hammerspoon, which would include the hammerspoon.d.ts type definitions. This would make developing Spoons much more convenient, especially for users using TypeScript.

If we could provide some kind of scaffolding tool, similar to npm create xxx, it would also help standardize the development conventions for Spoons.

[cmsj]

@asmagill npm (the package manager) would stay as an external (optional) tool for installing stuff. Node compatibility would be API we'd need to add to HS2 for third party JS libraries that depend on Node's API, to be able to run. The full Node API is huge and, to my mind, well outside the scope of HS2, but interestingly, there is a project working on a Swift implementation of Bun (yet another JS package manager and runtime) which does seem to have covered a significant amount of the Node API. We're not currently architected in such a way that we could consume their work as-is, but it could be at least a source for easier implementations: https://github.com/1amageek/swift-bun

@alkene5 I like the idea of publishing the .d.ts to npm, and I can look into npm create and see how that works, as a way to seed initial Spoons (in v1 we had API in hammerspoon itself to create a blank Spoon, but I'd be fine with that moving out to package.json or wherever it would be defined).

[gwww]

A couple of thoughts. I'm not strongly opinionated or knowledgeable on the JS/TS/node ecosystem. I know enough to be dangerous ;)

From a user experience point of view I'd like to:

• Use Typescript transparently meaning I write my config in Typescript and it somehow just works. I don't have to build - maybe there's a hook in hs.reload to run the build (based on my toolset) then load?
• I can add "packages" easily and equally as easily remove them. npm seems like the obvious first idea to pursue.
• I can discover packages - some kind of registry (tags on npm packages??)

CJS vs. ESM - I'd vote for ESM since it is more modern and this as this is a brand new app picking modern standards feels like the right way to go. But, I appreciate simplicity and if implementing ESM creates great complexity, then do something else.

Last, maybe for 1.0 you do none of this. Get 1.0 out there, get some experience, and when the audience grows some real usage ideas will come forward.