Improve docu about install hallmark (was: Installing for non-npm persons is wired)

[buhtz]

I am not familiar with npm. So this behavior might be regular but needs explanation in the install section. I tried to install hallmark. I installed npm (9.2.0) from Debian stable. Then I did:

$ npm i https://github.com/vweevers/hallmark

I refuse to use the npm repository for security reasons.

Now I have one new folder (node_modules) and two files (package-lock.json and package.json) direct in my current working folder.

Why? From my perspective it is in acceptable that a packagemanager/installer do create files in the current working dir. I never expected that. And npm uninstall did not remove that extra files and folders.

And even after installing the hallmark command is not available in my PATH. Don't know how to execute it. What is it what "npm" does when not installing it?

So how do I install hallmark without polluting my working directory?

[vweevers]

I refuse to use the npm repository for security reasons.

FWIW, that means you're putting trust in me (and my environment) because the GitHub repository is mutable, while npm package versions are not. So the security benefit is questionable.

Now I have one new folder (node_modules) and two files (package-lock.json and package.json) direct in my current working folder.

That's how npm works, like most package managers. Direct dependencies of your app are recorded in a manifest like package.json and the full tree of transitive dependencies is recorded in a lockfile like package-lock.json - which BTW has security benefits (in the category of supply chain attacks) because you can reinstall the exact same set of dependencies without inadvertently pulling in new and unknown transitive dependencies.

And even after installing the hallmark command is not available in my PATH. Don't know how to execute it. What is it what "npm" does when not installing it?

I'll stop here, because general questions about npm belong more on StackOverflow.

[buhtz]

FWIW, that means you're putting trust in me (and my environment) because the GitHub repository is mutable, while npm package versions are not. So the security benefit is questionable.

Questionable, yes. But depending on my knowledge (know you a bit but nothing about npm and its background) I feel more secure installing from upstream when the package is not available in my GNU/Linux distros repo.

That's how npm works, ... [...] I'll stop here, because general questions about npm belong more on StackOverflow.

This issue is not a question but a bug report and IMHO an opportunity to improve your documentation. You can not expect that your user are from the npm universe. Just give them the commands to execute to make your application run and don't force them to read 3rd party manuals and sources. Your users want to use "hallmark" and not npm/nodejs/xyz.

[vweevers]

You can not expect that your user are from the npm universe.

I can, and I do. If I offer alternative ways to install hallmark then I need to maintain more code and write more documentation. I choose not to. The npm package manager is highly convenient and widely used for Node.js and JavaScript projects. Does it have downsides? Sure, but this is not the place to discuss that.

[buhtz]

I offer alternative ways to install hallmark

We have a misunderstanding. I do not expect to offer an alternative way. Just improve the docu about how to install "hallmark" using "npm" for people not familiar with the npm-universe.