docs: git repos require a package.json

[getify]

The docs for npm install <git remote url> don't explicitly say that a git repository requires a package.json file in it. They say "package" a bunch, and I guess it should be obvious that this means a package.json would be required. But it wasn't. I lost several hours today trying to figure out why such an install was failing.

It now seems more obvious, given that the error message was:

ENOENT: no such file or directory, open '/path/to/.npm/_cacache/tmp/git-cloneXXXXXXXb14Fk/package.json'

But again, it didn't click for me that this meant a package.json was required. Give the file system error (ENOENT), I thought there was some sort of file system permissions problem happening, or even perhaps a network issue getting files. I tweeted about it and thankfully someone offhandedly mentioned that such repo installs require a package.json.

OK, got it, now that makes more sense. But I think the docs could make this more explicit. And I think that error message could also have been more explicit. Instead of treating it like a general file system error (ENOENT), it could just say "Required package.json was missing." or something. That would have saved me several hours of wrong troubleshooting.

---

All that said, I specifically wanted to ask if there's some way (perhaps with an additional flag on the install command) to install such packages? Is it really a hard requirement that a package.json file be provided?

Would it be possible to substitute a minimal auto-generated package.json if it's not found in the repo?

There are many github repos out there which have the files you need already checked into the repo, and no builds or dependency installs required. So for those repositories, they have no inherent need for a package.json in their own project. But if they don't add one, then consumers like me can't use it via npm.

Here's the repo I was trying and failing to install via npm install git+git@github.com:davidshimjs/qrcodejs.git. As you can see in that repo, it has the file I need, qrcode.min.js in it.

And in this case, I don't need to use it in node, so I don't actually need a package.json to use it. I only need it in node_modules so that a bundler/build process can grab that file. But if package.json is really needed there, perhaps npm could just generate a little minimal stub package.json in that case, something like:

{
   "auto_generated": true,
   "source": "github.com:davidshimjs/qrcodejs.git",
   "name": "qrcodejs",
   "version": "0.0.20240324190100"
}

Maybe a command like npm install git+git@github.com:davidshimjs/qrcodejs.git --auto-package-json could opt into this additional auto-generation?

Moreover, it'd also be nice if there was a way to list such a repository URL in a dependencies list of a project, such as:

{
   "dependencies": {
      "qrcode-js": "git+git@github.com:davidshimjs/qrcodejs.git"
   },
   "dependenciesMeta": {
      "qrcode-js": {
         "auto-package-json": true
      }
   }
}

[wraithgar]

Yes the docs should be updated. There isn't likely to be any way to do this without a package.json. That assumption is pretty deeply baked into a lot of npm, and that package.json needs to have a name and version in it. Also, auto-generating would require a TON of guessing, which is something we are trying to move away from in npm. Guessing what the user wanted will never be as useful as making them be explicit.

Also, in the future please use the issue template. It was only by accident that I saw this issue. Normally this would slip through the cracks because it is missing the tags and info that our issue template adds.

[getify]

in the future please use the issue template

Apologies.

I skipped the template because it wasn't clear to me that "Bug/Issue" was the right place for discussion and/or feature request. Is that the template I should have used in such a case? If not, perhaps a dedicated template for feature requests or discussions would be helpful.

There isn't likely to be any way to do this without a package.json

Sure, that is totally reasonable. Node requires it, too. There needs to be one, no question. But where it comes from is the nuance of the rest of this message/thread.

auto-generating would require a TON of guessing

Hmm, not to be argumentative, but I don't see this as much guessing in this case. You know what name to use because it's the name of the git repo they cloned. And if repo name isn't unique enough, surely "[github username]-[github repo name]" (like "davidshimjs-qrcodejs" above) would be, right?

And my code snippet above suggested 0.0.[iso8601-numeric-timestamp] as version number, like 0.0.20240324190100 above, with the timestamp being the moment it was installed.

If name and version are the only required fields, is that really too much "guessing" in this narrow context?

I certainly understand NOT guessing any other meta data, and the general aversion to guessing. But I felt this was a pretty narrow case to warrant me making the suggestion.

Guessing what the user wanted will never be as useful as making them be explicit.

In general, sure.

The exception to this is packages like the one I linked, which sadly don't have a package.json (so they can't be explicit), haven't been touched in almost a decade (and are likely to never get touched again, given the lack of issues triage), but are popular enough that literally a dozen other people have self published their own packages that do nothing but fork that repo and add a package.json file just to publish.

Surely that's silly that npm is cluttered with people creating worthlessly-forked packages of a commonly used library, just to work-around lack of a package.json.

In the case where we can't get the original author to be explicit, I am just wondering if a tad bit of narrow guessing can be warranted?

---

I also want to stress that my suggestion for this auto-generation is purely opt-in via flag and/or metadata. So the user installing such a git repo tries npm install and that fails because of the missing package.json... then they add the --auto-package-json flag or whatever, to explicitly ask npm to do that minimal amount of guessing.

That seems like it would be narrow enough to be safe. No?

[wraithgar]

New feature suggestions usually start at https://github.com/npm/feedback/discussions then make their way to https://github.com/npm/rfcs

[theabhinavdas]

To me, the docs are pretty clear! The docs for npm install explicitly say:

---

A package is:

• a) a folder containing a program described by a package.json file
• b) a gzipped tarball containing (a)
• c) a url that resolves to (b)
• d) a <name>@<version> that is published on the registry (see registry) with (c)
• e) a <name>@<tag> (see npm dist-tag) that points to (d)
• f) a <name> that has a "latest" tag satisfying (e)
• g) a <git remote url> that resolves to (a)

---

From (g), it is implied that a <git remote url> should resolve to a folder containing a program described by a package.json file.

Also,

Surely that's silly that npm is cluttered with people creating worthlessly-forked packages of a commonly used library, just to work-around lack of a package.json.

This argument is a red herring and has nothing to do with your feature suggestion.

@wraithgar should relabel this issue as Wontfix and close IMHO.