chore: use catalog for dependencies across multiple packages and the website

[bjohansebas]

Description

Using a catalog allows you to define a dependency in a single place and share it with the rest of the packages that require it. This can be useful to ensure that the same dependencies are always shared consistently

Validation

Related Issues

https://openjs-foundation.slack.com/archives/CVAMEJ4UV/p1748813652063899

Check List

• I have read the Contributing Guidelines and made commit messages that follow the guideline.
• I have run pnpm format to ensure the code follows the style guide.
• I have run pnpm test to check if all tests are passing.
• I have run pnpm build to check if the website builds without errors.
• I've covered new added functionality with unit tests if necessary.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
nodejs-org	✅ Ready (Inspect)	Visit Preview	Jun 1, 2025 10:04pm

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 75.46%. Comparing base (c11af00) to head (6fb1425).

✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7824      +/-   ##
==========================================
- Coverage   75.48%   75.46%   -0.03%     
==========================================
  Files         101      101              
  Lines        8309     8309              
  Branches      218      218              
==========================================
- Hits         6272     6270       -2     
- Misses       2035     2037       +2     
  Partials        2        2              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[bjohansebas]

These were the dependencies I saw repeated more than once across all the packages and the website. Feel free to suggest any that might be missing.

[avivkeller]

When the packages are published, will these be replaced with normal versions?

Edit: Yes, see https://pnpm.io/catalogs#publishing

[avivkeller]

If we do this, I'm slightly inclined to do it to all of our packages.

[bjohansebas]

If we do this, I'm slightly inclined to do it to all of our packages.

It would be good to include only the dependencies that are repeated across packages, we don’t want
to fill this list with all the dependencies.

[AugustinMauroy]

https://pnpm.io/catalogs#caveats

will these dep be updated by dependabot?

[bjohansebas]

yes https://github.blog/changelog/2025-02-04-dependabot-now-supports-pnpm-workspace-catalogs-ga

[avivkeller]

Suggested change

[avivkeller]

maybe add typescript-eslint?

[avivkeller]

We should add cross-env

[avivkeller]

Maybe we should add our testing deps, like tsx JSdom, etc?

[avivkeller]

It would be good to include only the dependencies that are repeated across packages

That also sounds good, but I don't think we should selectively include, I feel we should either:
None
All repeated
All

But that's just me

[MattIPv4]

Very much as an aside, but I am surprised none of the changes in this PR require approval from web-infra as a code owner.

[ovflowd]

Is this catalog: syntax compatible with npm? Is this a more-or-less standard field in package.json?

[ovflowd]

Very much as an aside, but I am surprised none of the changes in this PR require approval from web-infra as a code owner.

Agreed. These sort of changes should require web-infra as per the governance, they're not specifically related as a website development feature but more an infrastructural aspect.

[MattIPv4]

Is this catalog: syntax compatible with npm? Is this a more-or-less standard field in package.json?

It relies on pnpm-workspace.yaml to work, so no, npm will not support it AIUI.

[avivkeller]

Is this catalog: syntax compatible with npm? Is this a more-or-less standard field in package.json?

#7824 (review)

It relies on pnpm-workspace.yaml to work, so no, npm will not support it AIUI.

When we run pnpm publish, it gets replaced with the standard versions, so npm will support it, unless you import directly from the git repo

[ovflowd]

Appreciate the effort, @bjohansebas but I'm -1 on features that are locked on a specific package manager.

[MattIPv4]

Appreciate the effort, @bjohansebas but I'm -1 on features that are locked on a specific package manager.

With all the respect in the world, this feels like a ridiculous reason to object when we 1. voted to use pnpm, and 2. are specifically enforcing that pnpm is used when contributing:

nodejs.org/package.json

Lines 54 to 59 in ed840c2

	"devEngines": {
	"packageManager": {
	"name": "pnpm",
	"version": "10.11.1"
	}
	}

[avivkeller]

I agree with @ovflowd — this change introduces an additional layer of complexity that contributors will need to learn, which could make contributing harder.

Also, it’s worth pointing out that if the consumer is importing via git subdirectories, this approach requires them to use pnpm, ruling out alternatives like yarn that also support git subdirectory imports.

[MattIPv4]

Also, it’s worth pointing out that if the consumer is importing via git subdirectories, this approach requires them to use pnpm, ruling out alternatives like yarn that also support git subdirectory imports.

Out of curiosity, we already use workspace: directives in here, do those work w/ git subdirectory imports w/ yarn/pnpm? Are they both smart enough to resolve those to the git repository as a whole?

[MattIPv4]

I expressed this in Slack, but honestly, I'm quite disappointed with the objections here, both because we actively voted to use pnpm yet are now against using the niceties it gives us, but also because I don't see how this is particularly anymore complex than the workspace: syntax we already use which also require additional mental overhead to understand, resolving a version to elsewhere in the repository, very similar to what catalog: is doing.

[avivkeller]

Out of curiosity, we already use workspace: directives in here, do those work w/ git subdirectory imports w/ yarn/pnpm? Are they both smart enough to resolve those to the git repository as a whole?

We intentionally avoid using the workspace: syntax within packages/ to allow for package manager independent imports. We aren't expecting anyone to import apps/site, so we make use of it there.

[ovflowd]

I expressed this in Slack, but honestly, I'm quite disappointed with the objections here, both because we actively voted to use pnpm

I recall our votes were explicitly to use pnpm in favor for our CI/CD and improve installation speed. I don't think we voted on using pnpm specific features that are only available for pnpm. I did not recall the PR that added pnpm-workspaces.yml and I'm pretty sure pnpm is compatible with npm workspaces. (https://docs.npmjs.com/cli/v7/using-npm/workspaces)

I also feel we should use syntax as much as possible that is cross-compatible with other package managers. Although yes, users will be asked to use pnpm when installing due to the requirements we added on package.json, I do feel that:

a) i should be able to install via npm or yarn or deno or bun or whatever I want
b) we probably should remove the explicit pnpm requirement, I believe that's the packageManager field (https://github.com/nodejs/nodejs.org/blob/main/package.json#L50) as if I recall devEngines is what dependabot uses? Please correct me if I'm wrong.

But I want to make it explicit that our vote fas in favor of using pnpm by default due to the reasons I listed above; Making it exclusory or using pnpm-only terminology isn't just a learning curve, it is blocking users from choosing their own package manager.

There's a Collaboration Space within OpenJS with the specific goal of making Package Managers Interoperable; I feel dubious that whilst OpenJS is working towards that (ie @Ethan-Arrowood) we are doing the opposite by locking down our repo to only work with pnpm.

[avivkeller]

I did not recall the PR that added pnpm-workspaces.yml and I'm pretty sure pnpm is compatible with npm workspaces. (https://docs.npmjs.com/cli/v7/using-npm/workspaces)

We added that in the initial migration, IIRC. I didn't know pnpm supported npm workspaces.

---

For devEngines, we explicitly voted to set both of them, so, at the very least, I would feel more comfortable calling a second vote if we wanted to change it.

[ovflowd]

For devEngines, we explicitly voted to set both of them, so, at the very least, I would feel more comfortable calling a second vote if we wanted to change it.

I recall that yes; But didn't realize npm would block you from using it due to packageManager.

We added that in the initial migration, IIRC. I didn't know pnpm supported npm workspaces.

As far as I know pnpm, yarn and npm support the simplified workspace: setting on package.json... Maybe you could experiment w/ that?

[ovflowd]

FYI I don't want to block the PR unnecessarily, and apparently pnpm does NOT support NPM's workspace... and we're already using yarn/pnpm specific syntax with workspace:* so let's gon ahead with this PR.

I still am -1 on this, but I am the minority, so I don't want to block this PR when everyone else is okay with it

[AugustinMauroy]

Why not but catalog is a new npm feature so idk if it's good idea