Managing Hyas integrations via Node.js packages (npm) vs. Hugo modules: Pros and Cons

[salim-b]

I want to learn what all the (perceived) pros and cons of using Node.js packages (npm) instead of "native" Hugo modules are. I understand that Hyas uses npm to make Hugo itself a dependency of the website you're building (using hugo-installer). But Hyas integrations like images, inline-svg and seo could in principle still be added as Hugo modules instead of npm packages.

(Perceived) pros of npm I imagine:

• Hugo modules require a working installation of Golang. This can be worked around to some part by hugo mod vendoring the modules into the project with the added downside of significantly increasing the project's Git repo size (although it's debatable how much a downside this actually is when only using a dozen or less modules that have little to no transitive dependencies).

  npm package dependencies in a Hugo module are also not a problem. Hugo 0.75 introduced hugo mod npm pack to create a composite package.json that accounts for all npm dependencies used in imported Hugo modules. So it's still possible to offer a convenient out-of-the-box experience via npm install for Hyas theme end-users.

(Perceveived) cons of npm I can think of:

• Not embracing Hugos native dependency management infrastructure makes maintaining Hyas integrations more work, I guess. Also users have to wait for new npm releases.

  With Hugo modules, we just reference Git refs – as soon as the referenced branch is updated, users can fetch the updated code via hugo mod get if they like. KISS.

Did I miss misinterpret something? Other thoughts?

[h-enk]

Some of my findings why I didn't opt for using Hugo Modules:

• A lot of Hugo Modules also include npm modules, thereby introducing a second system for managing dependencies
• There's no global registry of available packages for Hugo Modules, like there is for npm
• You cant' manage versions with Hugo Modules, you'll always get the latest
• You can't manage scripts in Hugo Modules, like you can with npm
• hugo mod npm pack [flags] [args] is experimental and it failed my tests for Hyas. Also note that scripts are not supported
• Hugo Modules require Go, introducing another dependency

Some of my findings on why I did opt for using npm as a dependency manager:

• One system for managing dependencies
• Dependencies are explicitly declared in a single place
• Installing and updating are handled by npm
• Your project is locked onto specific versions

[h-enk]

I understand that Hyas uses npm to make Hugo itself a dependency of the website you're building (using hugo-installer).

Hugo is usually installed in a global location. This way however, your project users could be using different Hugo versions. Hyas however, installs Hugo locally in your project. This way, your project users will always use the same Hugo version. Also now, you and your project users will always use a Hugo version that works with (is tested for) a specific version of Hyas.

[h-enk]

and think this is the most important downside of using Hugo modules vs. npm, since we need npm anyways. 🙂

Yes, I agree, and in addition to that, one of the core design principles for Hyas is to make managing dependencies and scripts as easy as possible.

I think a single system for managing dependencies — like npm for Node.js (or Composer for PHP, Bundler for Ruby, or pip for Python for that matter) — is more in line with that principle than a dual system like Hugo Modules.

[salim-b]

Well, I don't think it is that important to do everything with a single dependency system – as long as it doesn't introduce additional work for end-users. The Hyas base being an npm package but managing its integrations as Hugo modules would be completely transparent for end-users¹, while at the same time being more convenient for developers. You could also share your work on Hyas integrations with the broader Hugo community. For example, there is already a Hugo module for Bootstrap (5), no need for a Hyas-specific integration anymore.

That being said, I'm totally fine with Hyas continuing to use npm exclusively as long as you're happy to maintain all those npm packages. 😄

Footnotes

1. As mentioned before, the modules could even be vendored, so Hyas would also work out-of-the-box for users that don't have Golang installed. ↩

[h-enk]

The Hyas base being an npm package but managing its integrations as Hugo modules would be completely transparent for end-users1, while and at the same time being more convenient for developers.

I see at least two types of users.

Hyas is a web framework using Hugo as the build engine and npm for managing dependencies (including Hugo itself). You could look at Hyas as a bridge between the Javascript world and the Hugo world. From a Javascript world perspective, npm is the most logical choice for managing dependencies. From a Hugo world perspective that is Hugo Modules with (experimental) support for npm.

To me — as a hybrid — the Hugo Modules way is fairly complex (and not robust) and npm is way more user-friendly (and more widely accepted). I also like that npm explicitly declares and isolates dependencies, whereas Hugo Modules does that more implicitly.

For now, I'm still in favor of an npm-only solution (I guess because I like npm more and like to keep things simple). However, it's an interesting thought if you could use Hugo Modules next to that — if you'd want that. We'll have to set up a POC to see how that works.

[h-enk]

However, it's an interesting thought if you could use Hugo Modules next to that — if you'd want that. We'll have to set up a POC to see how that works.

Well, that was easy — what's not to love about Hugo?!

• Repository: https://github.com/h-enk/hyas-hugo-mod-bootstrap
• Website: https://main--steady-pony-d10294.netlify.app/

What I did:

• I started with template-basic-starter-rec
• Then added hugo-mod-bootstrap-scss
• Updated themes/my-basic-theme/assets/scss/app.scss
• And, booom!

Good to know (and document) that this is a possibility — if you fancy that.

[salim-b]

Nice, glad to hear your PoC works as expected!

[salim-b]

Another important piece of information:

Multiple mounts within the same Hugo module (incl. the top-level project) with target = "assets" are not guaranteed to work reliably, i.e. the overlaying seems random¹. Future improvements to Hugo's mounts behaviour might improve on this situation according to Hugo's lead dev, but currently it's pretty-much broken. I just realized that the exact same mounts config produces different results with npm run dev/hugo server than with npm run build/hugo/Netlify: With the former, the assets/scss/layouts/_custom.scss file from the top-level project wins, but with with the latter it's the one from the doks-core node module.

In the course of trying to understand how Hugo mounts work I seem to have pissed off Hugo's lead dev – he closed the forum topic without further comments, so I couldn't ask more specifically. But apparently Hugo does merge assets correctly between imports but not necessarily between multiple mounts in the same module.

Update: The cause of the different results of hugo server vs. hugo was not Hugo modules but environments (development vs. production) and an outdated PurgeCSS config in the latter environment which didn't whitelist the common/_custom.scss Bootstrap file. 😑 Sorry for the confusion. Nevertheless I think Hyas should switch to properly set up Hugo modules and stop managing Hugo dependencies via npm. Hugo's assets component folder merge behaviour is currently a pain, regardless of my false alarm above (striked out).

Footnotes

1. It's likely no coincidence that the merge behaviour of assets – in contrast to all other relevant component folders – is not documented (additionally, that doc hasn't been updated to mention modules; too many Hugo devs really hate properly documenting the awesome shit they throw at us uninitiated fools 🙄). ↩