Use npm workspaces in addition to `package.hugo.json`

[schnerring]

I currently develop a theme and make use of the hugo mod npm pack feature. I develop the theme with an example site within the same repo under a directory named exampleSite/.

For the theme's dependencies I use npm packages, so I don't clutter the code base with any third-party code.

I was thinking that it would be pretty nice to keep the theme dependencies up-to-date with the help of Dependabot. Correct me if I'm wrong, I have not yet used Dependabot, but from what I've read in the docs I'm pretty sure it requires the npm manifest's name to be package.json. You can place package.json in any directory, even update multiple package.json files, but it's impossible to specify a file name like package.hugo.json. So I could update exampleSite/package.json with Dependabot and then manually patch the package.hugo.json from time to time.

Which is the workflow I do a lot during development which IMO feels a little backwards. When I want to install a new npm package, I npm i inside exampleSite/ and then patch the package.hugo.json file in the theme directory after and then run hugo mod npm pack again, so the comments get updated.

With npm modules, things would have a nicer workflow IMO. To initialize npm for the theme, run:

npm init
npm init --workspace hugo

... resulting in a package.json file:

{
  "name": "test",
  "workspaces": [
    "hugo"
  ]
}

... and a hugo/package.json file:

{
  "name": "hugo"
}

We could then install packages on the theme level by running:

npm install --workspace hugo <package-name>
# or short
npm i -w hugo <package-name>

... and then run hugo mod npm pack to patch exampleSite/.

The only caveat I can see is that the Node LTS version doesn't (natively?) support workspaces, only the current version (v16) does. Which is fine because hugo mod npm pack is experimental anyway 🤣

IMO this would make the workflow better because we'd use npm's API instead of relying on manual patching, reduce the number of steps required to install new packages, and allow the use of Dependabot on top which already supports Node v16.

[bep]

Thanks a lot for this, much appreciated. Yes, I wasn't totally happy with the package.hugo.json approach.

So, if I understand you correctly.

• Themes/modules use a Hugo workspace.
• npm mod npm pack merges those Hugo workspaces into a package.json (not a workspace)

??

I don't mind Node v16 for the "packing", but it would not be great if that was also required for the final runtime (e.g. what happens on Netlify etc.)

Also, we should try to support both workspaces and package.hugo.json if not too hard.

[schnerring]

So, if I understand you correctly.

You do 😄

I don't mind Node v16 for the "packing", but it would not be great if that was also required for the final runtime (e.g. what happens on Netlify etc.)

Only the npm -w workflow of managing the package.json file would require v16.

Also, we should try to support both workspaces and package.hugo.json if not too hard.

Yes. I think the only difference between the two approaches is the filename, package.hugo.json vs. hugo/package.json. The way I see it, Hugo wouldn't even be aware of npm workspaces, so the "root" package.json isn't required. It's only there to be able to leverage the native npm workspace API.

[HEIGE-PCloud]

Is it possible to allow the theme to specify the path of package.json in its theme.toml? Adding an option such as

[dependency]
  package_json_path = "./package.json"

The path should be relative to the root of the theme. (And the name of those options surely needs more consideration.)

In this way, a theme can manage the package.json in its own way (use a npm workspace, use the package.hugo.json or just use the default package.json).