Make internal package references strict (or peer dependencies)

[vezaynk]

Provide a general summary of the feature here

I'm running into a recurring issue every time react-spectrum makes a new release, and I'd like to open a thread on whether it's something that can be fixed on your end (or whether it should be mitigated on my end somehow).

Long story short, it's very easy to accidentally install duplicate packages, which breaks type overrides in my monorepo (among other things).

Here's an example from today.

My design system declares all-things-react-aria as peer dependencies, in order to make sure that I don't accidentally end up references multiple versions of react-aria which would produce 2 singletons that don't reference each other. (Turns out this doesn't save us!)

To integrate ReactAria with ReactRouter, I have the following snippet in index.d.ts:

declare module 'react-aria-components' {
  interface RouterConfig {
    href: To;
    routerOptions: NavigateOptions;
  }
}

RouterConfig doesn't actually come directly from react-aria-components. It comes from @react-types/shared (which is declared as a peer dependency of my design system and pinned to "3.31.0" in both my design system and in my monorepo).

Now today, React-spectrum cuts a new release which comes with new versions, including @react-types/shared@3.32.0.

Annoyingly, @react-types/shared@3.32.0 actually gets pulled into my dependencies because @react-aria/breadcrumbs@3.5.28 (also a new release) expects it, which is in turn installed by react-aria@3.42.0 (which is my current version).

So my node_modules ends up both containing @react-types/shared@3.32.0 and @react-types/shared@3.31.0 and its a crapshoot on which one gets referenced where.

And all of this is happening because react-aria declares @react-aria/breadcrumbs with a version range

"dependencies": {
    "@react-aria/breadcrumbs": "^3.5.27",

This could be gracefully managed by either

A. making internal dependencies strict (no version range):

"dependencies": {
    "@react-aria/breadcrumbs": "3.5.27",

This will avoid unintended version bumps but does not necessarily guarantee de-duplication.

B. making internal dependencies "peers"

This is my preferred solution, where it will be up to consumers to explicitly declare the version they want to install

"peerDependencies": {
    "@react-aria/breadcrumbs": "^3.5.27",

This will ensure that every package that is intended to be a singleton actually behaves that way.

The best I can do today is to override the behavior via package.json's resolutions field:

"resolutions": {
    "@react-types/shared": "3.31.0"
  },

More importantly, I end up with multiple instances of @react-aria/utils which makes RouterProvider not apply to different copies and breaks my links. Not fun!

This works, but I don't enjoy needing to reach for it.

🤔 Expected Behavior?

I shouldn't end up with duplicate installs.

😯 Current Behavior

Its possible to end up with duplicate installs.

💁 Possible Solution

Make internal package references a peers with a strict (or not strict) version.

🔦 Context

All context already provided

💻 Examples

No response

🧢 Your Company/Team

No response

🕷 Tracking Issue

No response

[devongovett]

Pinning would likely introduce even more duplication. Then libraries built on top of React Aria would each end up with their own copy, especially if each of them pinned.

Peer dependencies would mean your package.json would have to add 200+ dependencies probably.

Usually duplication of compatible ranges can be solved with npm/yarn dedupe commands. By default they try to retain existing versions in the lock file but the dedupe command can fix that.

In the future we might do away with the individual packages entirely and merge all of the code into a single (or a few) packages which could greatly simplify this.

[vezaynk]

@devongovett Package-manager dedupping only works for upgrading (at least for yarn and pnpm). In this case, I would need it to downgrade.

Pinning would likely introduce even more duplication. Then libraries built on top of React Aria would each end up with their own copy, especially if each of them pinned.

If they upgrade all packages in one go, every time, then they should be fine.

I think right now, without pinning version, there's a lot of potential from pain due to version drift. It would make a lot of sense for all of react-spectrum packages to march in lockstep with one-another without potential of one package being significantly newer than another.

[vezaynk]

Also, this isn't necessarily true:

Peer dependencies would mean your package.json would have to add 200+ dependencies probably.

Package managers generally can install peer-dependencies without them being listed explicitly. npm and pnpm will do this by default, in fact. So unless if you want a specific version, you don't have to list it.

[devongovett]

In this case, I would need it to downgrade.

Could you explain this more? What's the reason for downgrading?

Package managers generally can install peer-dependencies without them being listed explicitly.

At least Yarn is very strict about peer dependencies always being provided by all packages that consume them.

[snowystinger]

Linking relevant issues

• Pin dependency versions on release
• Unmanageable dependency versions - Proposal: make react-aria and react-stately truly monolith. #7946
• peerDependency issue with multiple react-aria packages

[vezaynk]

@devongovett

Looks like Yarn is the odd one out: yarnpkg/berry#5421. NPM and PNPM both flip-flopped on the behavior but decided it was best to allow and enable by default.

My scenario for needing to downgrade, to get specific, is the following:

• We have two projects: one is our design system (launchpad-ui), and then our main app which imports it.
• For both projects, we want to be deliberate about upgrades, so we pin all our dependency versions.

A specific example of where it goes wrong:

• Our design system pins "@react-types/shared": "3.31.0" (as peer) because that's the last version we tested
• Our app pins "@react-types/shared": "3.31.0" because that's the last version we tested
• Same goes for react-aria@3.42.0
• Despite my version-pinning everywhere react-aria@3.42.0 can install "@react-types/shared": "3.32.0"
• yarn/pnpm depupe would try to upgrade my packages to "@react-types/shared": "3.32.0" if it were allowed, which it isn't, because I'm not ready to upgrade yet
• I would enjoy if yarn dedupe would instead downgrade react-aria->breadcrumbs->shared-types to 3.31.0 but neither yarn nor pnpm are able to do this

[snowystinger]

Odd, Yarn specifies that you can set a strategy, where I would have assumed you could choose "lowest" https://yarnpkg.com/cli/dedupe
But it would appear that the only option they support, which is also the default, is "highest"...
https://github.com/yarnpkg/berry/blob/f6a58c2803d6572af28e118eecd10c795e1228b1/packages/plugin-essentials/sources/dedupeUtils.ts#L27

[devongovett]

Yeah currently the only way to pin globally is using resolutions. As I mentioned before, if you pin within each dependency, you'd get even more duplication. For example:

• Design system library uses react-aria-components "1.9.0"
• External component library uses react-aria-components "1.10.0"

You generally want those to resolve to the same version, not multiple.

It also might not be so obvious as that. An external library might depend on some individual package such as @react-aria/interactions at one version, and react-aria-components -> react-aria -> @react-aria/interactions might be at a different version. Again, you want to resolve those to a single version.

That's why we use caret ranges currently. It allows the package manager to deduplicate. But there is the tradeoff that it's hard to pin to specific versions without writing resolutions for every package.

[vezaynk]

IMO -- The bigger trade-off with resolutions fields is that it is a "break-glass" override, which allows installing packages that are incompatible with one another. It also keeps the same problem as peers, which need to list 200 packages in order to enforce consistency.

Based on the conversation so far, I think pinned peer dependencies sound optimal because they guarantee consistency at the cost of needing a big package.json (which could be fixed by unifying or bundling packages differently within react-aria). Again, this cost only kicks in if you're using yarn.

There's also the possibility of having setup scripts for installing/updating react-aria packages.

[snowystinger]

There's also the possibility of having setup scripts for installing/updating react-aria packages.

Yes, this is something we'd love to explore more.
We don't have any automated warnings at the moment (possibly in a post install step), which we'd love to have to let people know when they have duplicates installed.

We do have a script which can help find duplicates https://github.com/adobe/react-spectrum/wiki/Frequently-Asked-Questions-(FAQs)#why-are-there-errors-after-upgrading-a-react-spectrum-package

As well as a yarn plugin https://github.com/adobe/react-spectrum/blob/main/lib/yarn-plugin-rsp-duplicates.js

[devongovett]

We're considering merging all code into a single package instead of re-exporting from individual packages, which should make it much easier to upgrade and pin versions. It will be backward compatible. Please see the RFC, and feel free to leave feedback! #8797