Codey

Appearance

Report a problem:

Problems can be reported via Microsoft Teams in your team channel within the "IT - Codey" team.

Please include the following information:

Report type:
Docs problem report a bug instead →
Path:
/vnext/contributing/adr/records/001__package-dependencies-or-peer-dependencies.html
Message:

DESCRIBE THE PROBLEM BEFORE SUBMITTING TO CODEY

Package Dependencies Or Peer Dependencies ​

Status: Approved

Decision Date: 22/10/2022

Scope: All published packages

Context ​

When it comes to using dependencies or peerDependencies in a package.json file, there are some important considerations to take into account. The main rule of thumb normally is:

  • dependencies:
    • Packages listed here are installed automatically with your library.
    • Use if your library absolutely needs this package to function and you control the version tightly.
    • Example: A small utility your library wraps or extends.
  • peerDependencies:
    • Packages listed here must be installed manually by the project that uses your library.
    • Use if your library expects a package to exist but shouldn’t dictate its version (especially if it's already in the user's project).
    • Example: pinia, i18n, vue, etc. (you want your library to work with the app’s version, not pull its own).

How npm handles pre-release tags and version wildcards ​

There is another consideration to take into account regarding versioning and the usages of pre-releases. We noticed that having a library like @xerius/codey-hello-customer that has a dependency to @xerius/codey-components using a pre-release version would not automatically update with respect of the ^ version range. This is caused by how npm interprets the version range of suffixed versions. So when you have a version like "@xerius/codey-components": "^11.0.0-next.1" and you have version 11.0.0-next.2 published, npm will not install that version automatically. The ^ range does not apply to pre-releases.

Addition information can be found about this here.

This behavior meant that setting dependencies with pre-release versions would not be updated automatically. This is a problem when you have a package that has a dependency to another package that is in pre-release and you want to use the latest version of that package.

Decision ​

Because of this behavior we decided to use peerDependencies for all package dependencies we publish from our repo as this requires them to be explicitly installed. Together with the option ___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH.updateInternalDependents = always of changesets, version numbers will be bumped when internal dependencies are updated. This ensures that updates are correctly referenced and installed.

This mainly applies to codey-components as it references to other published packages that are required as dependency.

Consequences ​

There are more peerDependencies than are required. Some of them could just be dependencies as the user technically does not have control or choice over the version. This is a trade-off we are willing to make as it allows us to use pre-releases and have correctly specified versions defined. Having to find out about the described behavior is time consuming and not obvious at all. It would lead to a lot of confusion and frustration if we would have to deal with this in the future.

Alternatives ​

Using yarn would solve this problem as it does resolve these versions correctly. Swapping package manager for this would also required a setup change in CI/CD and local development.