The end goal of writing a library is having an application consume our code. In other words, our library would become a dependency of a project. In the same way as projects can depend on our library, our library can also have its own dependencies.

There are three types of dependencies:

1. Dependencies we rely on (dependencies)

2. Dependencies we only need for development (devDependencies)

3. Dependencies we expect our users to provide (peerDependencies)

How package.json defines dependencies#

Our package.json file defines the three types of dependencies. Each dependency has a name to a corresponding version. We can use every type of dependency, or none of them at all. There is no rule on the number of dependencies in a project. Though keep in mind adding a dependency to our library comes at a cost. Every dependency added may make our library grow in size, and adds additional security concerns. Let's take a look at an example package.json:

{

  "name": "my-library",

  "version": "1.0.0",

  "description": "",

  "main": "index.js",

  "dependencies": {

    "whatwg-fetch": "3.5.0"

  },

  "devDependencies": {

    "webpack": "^5.0.0"

  },

  "peerDependencies": {

    "react": ">16.0.0",

    "react-dom": ">16.0.0"

  }

}

When defining dependencies we want to stick to a version, or a range of versions we know will work with our library. Packages in npm (Node Package Manager) use semantic versioning. The semantic versioning standard communicates changes on a project. Version numbers are immutable, or cannot change once they're published. Semantic Versioning is defined as numbers separated by periods: MAJOR.MINOR.PATCH. When the major number is incremented there is a high probability of a breaking change in the code. For example, upgrading Webpack 4.0.0 to 5.0.0 is a major jump in features and deprecations; the code using Webpack will likely break when upgrading versions. Minor numbers are incremental updates. These could be new features, but breaking changes are minimal. Lastly, patch numbers communicate bug fixes and security patches. There should be no breaking changes.

Now that versioning is cleared up, what is up with those symbols in package.json of the last example? npm has additional utilities to make handling dependencies easier. For example, the caret ^ tells npm to use version 5.0.0 except if a newer minor or patch version exists. If version 5.0.1 had been published when we run yarn, then version 5.0.1 would be installed instead of 5.0.0. These utility symbols are useful to reduce micromanaging dependencies, and allow security fixes to be installed automatically. A full list of symbols can be found here.

Keep semantic versioning in mind when managing dependencies and publishing your packages.