Skip to main content

Managing dependencies

Keeping dependencies up-to-date is crucial for stability and security, as well as keeping your package.json dependencies clean and up-to-date. Please carefully learn and follow the principles below.

Yarn configuration​

We use Yarn on top of npm to manage dependencies. Your project should contain a yarnrc.yml file at its root, with the following settings:

enableTelemetry: false
nodeLink: node-modules

You can adjust the Yarn configuration to your needs, be please:

  • Don't enable caching
  • Don't use PNP—although this may change in the future. We can't use it for now because of some incompatible dependencies.

Adding dependencies​

There are different types of dependencies that have an impact on our consumers when they install our packages.

  • Think carefully when you add a dependency: is it a regular dependency (yarn add ...) or a dev dependency (yarn add --dev ...)?

  • Run yarn install and carefully review and fix the unmet peer dependencies.

  • Commit your yarn.lock file.

Pinning dependencies​

First, learn and understand the SemVer ranges and dependency pinning concepts.

Then follow the rules we have defined for the Quartz ecosystem:

Updating dependencies​

We use the Mend Renovate App in our CI workflows to catch necessary updates and generate PRs. Renovate will automatically merge some PRs when the CI runs successfully.

When updating a dependency, don't forget to:

  • thoroughly test your code when upgrading a major version of a dependency
  • review the peer dependencies requirements, as they evolve with versions

Avoiding duplicate dependencies​

Because Yarn ensures deterministic installs, there can sometimes be multiple versions of the same dependency installed, increasing the size of your package. This is true for all projects, including monorepos (see below).

Keep dependencies up-to-date​

Monitor Renovate's PRs that need your attention, and review your dependencies regularly:

  • Check unmet peer dependencies
  • Reassess dependency types (dev or regular)
  • Remove unused dependencies
  • Review other constraints (required node version, yarn version, etc.)

Specific rules for monorepos​

Many repositories of Quartz are organized as monorepos. For example:

  • component libraries generate packages for several frameworks
  • brand repositories generate packages for their design tokens, assets, fonts, and icon libraries

Yarn has strong support for monorepos through its workspaces feature. Make sure you read and understand how they work.

Because their nature, monorepos have a different organization of dependencies:

  • shared dependencies go in the root package.json when possible
  • individual workspace's package.json contain only:
    • dev dependencies required by the scripts
    • regular or dev dependencies specific to that package
    • peer dependencies required by a 3rd-party library (ex: angular)
Last updated on