How should I use package.hugo.json?

[will]

After doing hugo mod npm pack in my theme to generate package.hugo.json, what do I do with it? Do I check it in? Do I npm install with it instead of my own package.json, somehow?

If my Hugo module doesn’t depend on any other Hugo modules, is it important that I still generate package.hugo.json for other modules that depend on my module? Or can I leave it out, and other modules can use hugo mod npm pack to generate a package.hugo.json that includes my module’s npm deps?

[razon]

I think it depends on how the theme build the assets (CSS, JS etc). If the theme requires users to install the dependencies via NPM (used by Hugo Pipes), then you should define the theme’s dependencies inside package.hugo.json, so that users can pull/merge the dependencies from the theme/module into their sites.

$ cd user-site
$ hugo mod get -u github.com/foo/bar
$ hugo mod npm pack
$ npm update

A common case is that if a theme introduces a new dependency, then the user needs to install the corresponding dependency, otherwise they will get an error like can not resolve new-deps.

[will]

But npm doesn’t work with package.hugo.json. If you run npm install in a directory with package.hugo.json and without package.json, you get an error:

❯ npm install
npm ERR! code ENOENT
npm ERR! syscall open
npm ERR! path /Users/Will/Developer/paige/package.json
npm ERR! errno -2
npm ERR! enoent ENOENT: no such file or directory, open '/Users/Will/Developer/paige/package.json'
npm ERR! enoent This is related to npm not being able to find a file.
npm ERR! enoent 

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/Will/.npm/_logs/2023-02-21T05_36_12_821Z-debug-0.log

So I’m not clear on how package.hugo.json is actually used.

[razon]

Actually, the package.hugo.json is a template for generating package.json, when executing the hugo mod npm pack, the generated package.json will include the dependencies defined in package.hugo.json from modules and themes.

For example, the theme/module requires katex, the package.hugo.json as follows:

{
  "dependencies": {
    "katex": "^0.16.4"
  }
}

Users need to perform the hugo mod npm pack to pull the dependencies from modules and themes if necessary, the generated package.json as follows.

{
  "comments": {
    "dependencies": {
      "katex": "github.com/razonyang/hugo-lab"
    },
    "devDependencies": {}
  },
  "dependencies": {
    "katex": "^0.16.4"
  },
  "devDependencies": {},
  "name": "exampleSite",
  "version": "0.1.0"
}

Then the user can install or update the all required dependencies.

npm install

npm update

When the module introduced a new feature with new dependencies, those dependencies also need to be declared in package.hugo.json, so that users can install the new dependencies after upgrading the module.

$ cd user-site
$ hugo mod get -u github.com/foo/bar
$ hugo mod npm pack
$ npm update

[will]

Makes sense. Thanks!