DEV Community: Todd Palmer

npm Peer Dependencies for the Professional Developer

Todd Palmer — Mon, 14 Oct 2024 01:30:16 +0000

In this article, I clarify what npm Peer Dependencies are and especially when you should use them. Peer Dependencies are listed in your project's package.json file in the peerDependencies object.

To get the most out of this article you should have at least an introductory understanding of npm.

In this article:

We will compare exactly how Peer Dependencies work versus regular Dependencies.
We will look at some examples of both Peer Dependencies and Dependencies.
Then, we will examine how npm handles version conflicts.
Finally, having the fundamentals solidly in our grasp, we will lay out an approach to deciding when Peer Dependencies are appropriate.

The Scenario

To keep it real, let’s assume you’re creating an Angular or React Component Library or even just a simple JavaScript file that exports some functions.

Your project relies on packages from the npm Registry. These packages are your project’s dependencies.

You want to create your own npm package from your project. So you use npm pack to generate an npm package from your project. You might even decide to publish it to the npm Registry.

Other teams could then find your component library as a package on the npm Registry. They can use npm install to add your package as a dependency in their own projects. We use Dependencies and Peer Dependencies in package.json to tell these other projects what packages also need to be added for our component library to work.

Dependencies Versus Peer Dependencies

At their most basic level here is how Dependencies and Peer Dependencies work:

Dependencies

Dependencies are listed in your project's package.json file in a dependencies object.

When you add a package in your code's dependencies, you are saying:

My code needs this package to run.
If this package doesn’t already exist in my node_modules directory, then add it automatically.
Furthermore, add any packages that are listed in this package’s dependencies. These packages are called Transitive Dependencies.

Peer Dependencies

Peer Dependencies are listed in your project's package.json file in a peerDependencies object.

By adding a package in your code's peerDependencies you are saying:

My code is compatible with this version of the package.
If this package already exists in node_modules, do nothing.
If this package doesn’t already exist in the node_modules directory or it is the wrong version, don’t add it. But, show a warning to the user that it wasn’t found.

Adding Dependencies

So, we add dependencies in the package.json file of our npm package folder. Let’s look at exactly how we add packages as dependencies and some examples of package dependencies.

Adding a Dependency

A Dependency is an npm package that our code depends on in order to be able to run. Some popular packages that can be added as dependencies are lodash, D3, and chartjs.

We add a regular dependency like this:

npm install lodash

npm adds the package name and version to the dependencies object in our project’s package.json file.

"dependencies": {
  "lodash": "^4.17.11"
}

Some of you might remember the old days when we had to use the --save flag to get npm to update the dependencies in package.json. Thankfully, we don’t need to do that anymore.

Adding a Peer Dependency

Peer Dependencies are used to specify that our project is compatible with a specific version of an npm package. Good examples are Angular and React.

To add a Peer Dependency you actually need to manually modify your package.json file. For example, for component library projects, depending on which framework you are using I recommend adding angular/core or react as a peer dependency.

So if you wanted to specify that your package is built for React 18, you could include something like this:

"peerDependencies": {
   "react": "^18.0.0",
}

Or maybe you want to say that you have tested your component library with both Angular version 17 and 18 but not 19 because it wasn't out yet. Then you could use:

"peerDependencies": {
   "@angular/core": ">=17.0.0 || <19"
}

About Conflicts

I get a lot of questions about whether a certain npm package should go into dependencies or into peerDependencies. The key to making this decision involves understanding how npm deals with version conflicts.

If you have read my previous articles, you know I like you to be able to do this stuff along with me! So feel free to work along with me for this little npm experiment.

conflict-test Project

To get started let’s create a trivial test project. I am going to name mine:
conflict-test

I created it like this:

md conflict-test
cd conflict-test
npm init -y

I then manually edited the package.json file and added two dependencies:

"dependencies": {
    "todd-a": "^1.0.0",
    "todd-b": "^1.0.0"
}

These todd-a and todd-b packages also have their own dependencies:

todd-a

"dependencies": {
    "lodash": "^4.17.11",
    "todd-child": "^1.0.0"
}

todd-b

"dependencies": {
    "lodash": "^4.17.11",
    "todd-child": "^2.0.0"
}

The thing I want you to notice here is that todd-a and todd-b use the same version of lodash. But, they have a version conflict for todd-child:
todd-a uses todd-child version 1.0.0
todd-b uses todd-child version 2.0.0

Now I know that, like me, you are keenly interested in seeing how npm handles this version conflict. In my main project conflict-test I run npm install. As we would expect, npm magically installs the todd-a and todd-b packages in our node_modules folder. It also adds the packages that they depend on (the transitive dependencies). So after running npm install we take a look at the node_modules folder. It looks like this:

node_modules
├── lodash 4.17.11
├── todd-a 1.0.0
├── todd-b 1.0.0
│   └── node_modules
│       └── todd-child 2.0.0
└── todd-child 1.0.0

The interesting thing about this is that our project has one copy of lodash. But, it has two copies of todd-child! Notice that todd-b gets its own private copy of todd-child 2.0.0.

So here is the rule:

npm deals with version conflicts by adding duplicate private versions of the conflicted package.

An Approach to Peer Dependencies

As we saw from our experiment with npm version conflicts, if you add a package to your dependencies, there is a chance it may end up being duplicated in node_modules.

Sometimes, having two versions of the same package is fine. However, some packages will cause conflicts when there are two different versions of them in the same code base.

For example, assume our component library was created using React v15. We wouldn’t want our package adding another completely different version of react when someone adds it as a dependency to their React v18 application.

The key is:
We don’t want our library adding another version of a package to node-modules when that package could conflict with an existing version and cause problems.

peerDependencies or dependencies?

So this brings us to the main question for our dependencies:

When my package depends on another package, should I put it in dependencies or peerDependencies?

Well, as with most technical questions: It depends.

Peer Dependencies express compatibility. For example, you will want to be specific about which version of Angular or React your library is compatible with.

The Guidelines

Favor using Peer Dependencies when one of the following is true:

Having multiple copies of a package would cause conflicts
The dependency is visible in your interface
You want the developer to decide which version to install

Let’s take the example of angular/core. Obviously, if you are creating an Angular Library, angular/core is going to be a very visible part of your library’s interface. Hence, it belongs in your peerDependencies.

However, maybe your library uses Moment.js internally to process some time related inputs. Moment.js most likely won’t be exposed in the interface of your Angular or React components. Hence, it belongs in your dependencies.

Angular or React as a Dependency

Given that you are going to specify in your documentation that your library is a set of Angular or React Components, you may be asking the question:

Do I even need to specify angular/core as a dependency? If someone is using my library, they will already have an existing Angular project.

Good question!

Yes, we can usually assume that for our Angular or React specific library the Workspace will already have the Angular or React packages available. Hence, technically we wouldn’t need to bother adding them to our list of dependencies.

However, we really do want to tell the developer which Angular or React versions our library is compatible with. So I recommend the following approach:

Add at least the angular/core or react package for the compatible version to your peerDependencies.

This way developers will see a warning if they try to use your React 18 component library in their React 16 project. Don’t bother adding the other Angular or React packages. You can assume if they have angular/core or react, they have the other related libraries.

In Conclusion

When in doubt you should probably lean toward using peerDependencies. This lets the users of your package make their own choice about which packages to add.

Angular and Internet Explorer

Todd Palmer — Fri, 14 Feb 2020 16:01:41 +0000

This article addresses supporting Internet Explorer as a browser for your Angular 8.x or Angular 9.x application. If you are using an earlier version of Angular, please see my previous article on this topic.

In this article we will discuss:

Getting started with an Angular CLI application
The error in Internet Explorer
The steps necessary to support Internet Explorer in Production
How to support Internet Explorer in Development

If you just want to make it work and don’t care about the details, you can scroll down to the section: The Cure.

Getting Started

First use Angular CLI to generate and serve a starter application:

ng new ie-test
cd ie-test
ng serve

Point basically any browser except Internet Explorer at: http://localhost:4200 and you will see the basic Angular CLI application that we all know and love. In Firefox it looks like this:

The Symptom

But, if we try to use Internet Explorer, we see something like this:

Well, it seems to be doing something because at least the title is correct. If we open the Browser Console and re-load the page, we see something like:
Unspecified error.

The Cure

To get Internet Explorer working we need to do the following steps:

Un-comment some imports in the polyfill.ts file.
Install a couple of npm packages.
Modify the browserslist file.

Below are the details for each of these steps.

Polyfill Imports

First open the polyfills file in your IDE or text editor:
ie-test\src\polyfills.ts

There are two commented out lines that you need to un-comment:

// import 'classlist.js';  // Run `npm install --save classlist.js`.

// import 'web-animations-js';  // Run `npm install --save web-animations-js`.

Install npm Packages

Notice there are some npm install commands in the comments. You need to run:

npm install --save classlist.js
npm install --save web-animations-js

Modify browserslist File

Open the browserslist file in your IDE or text editor:
ie-test\browserslist

The default file created by Angular CLI looks something like this:

# This file is used by the build system to adjust CSS and JS output to support the specified browsers below.
# For additional information regarding the format and rule options, please see:
# https://github.com/browserslist/browserslist#queries

# You can see what browsers were selected by your queries by running:
#   npx browserslist

> 0.5%
last 2 versions
Firefox ESR
not dead
not IE 9-11 # For IE 9-11 support, remove 'not'.

You need to change that last line by removing the not. After you make the changes the last line should read:

IE 9-11 # For IE 9-11 support, remove 'not'.

Internet Explorer in Production

For now, Internet Explorer still won’t work with ng serve. There are a few more steps required.

However, if all you care about is supporting Internet Explorer in production, the previous steps are enough. You can prove this to yourself by doing a production build and pointing a web server at your dist/ie-test folder.

ng build --prod

Notice that now, when you run the build, it is producing the ES5 bundles:

$\ie-test> ng build --prod
Generating ES5 bundles for differential loading...
ES5 bundle generation complete.
chunk {0} runtime-es2015.edb2fcf2778e7bf1d426.js (runtime) 1.45 kB [entry] [rendered]
chunk {0} runtime-es5.edb2fcf2778e7bf1d426.js (runtime) 1.45 kB [entry] [rendered]
chunk {2} polyfills-es2015.2987770fde9daa1d8a2e.js (polyfills) 36.4 kB [initial] [rendered]
chunk {3} polyfills-es5.ef4b1e1fc703b3ff76e3.js (polyfills-es5) 123 kB [initial] [rendered]
chunk {1} main-es2015.77c5c44e21b70d1ec41a.js (main) 169 kB [initial] [rendered]
chunk {1} main-es5.77c5c44e21b70d1ec41a.js (main) 190 kB [initial] [rendered]
chunk {4} styles.3ff695c00d717f2d2a11.css (styles) 0 bytes [initial] [rendered]
Date: 2019-12-03T23:28:06.809Z - Hash: 89a94328c69b68370cb8 - Time: 43148ms

Now you can use a web server to test. For example, I will use local-web-server with npx. By the way, if you haven’t used npx, check out Kat Marchán’s article:
Introducing npx: an npm package runner

After building you can run:

cd .\dist\ie-test\
npx local-web-server

This serves up your Angular application. Point Internet Explorer at it and you should see:

NOTE:
If you still don’t see your application you may need to turn off Display intranet sites in Compatibility View in your Compatibility View Settings.

Internet Explorer in Development

However, if you use:

ng serve

you will still get the blank Internet Explorer. This is because ng serve doesn’t automatically generate the ES5 bundle.

There are a couple of ways to configure this:

Modify the tsconfig.json file.
Create an ES5 configuration.

Modify tsconfig.json

You can find your tsconfig.json file in the root of your Angular Workspace. Open it up in your IDE or text editor and you will see:

{
  "compileOnSave": false,
  "compilerOptions": {
    "baseUrl": "./",
    "outDir": "./dist/out-tsc",
    "sourceMap": true,
    "declaration": false,
    "downlevelIteration": true,
    "experimentalDecorators": true,
    "module": "esnext",
    "moduleResolution": "node",
    "importHelpers": true,
    "target": "es2015",
    "typeRoots": [
      "node_modules/@types"
    ],
    "lib": [
      "es2018",
      "dom"
    ]
  },
  "angularCompilerOptions": {
    "fullTemplateTypeCheck": true,
    "strictInjectionParameters": true
  }
}

Notice the line: target: es2015. You can change it to es5. It will then look like this:

"target": "es5",

Now you can run: ng serve

Point Internet Explorer at http://localhost:4200 and you should see it working just fine.

Creating an ES5 Configuration

If you don’t like the idea of directly modifying your tsconfig.json just so you can use Internet Explorer with ng serve, your can create an ES5 configuration.

I won’t go into detail about this here as Ali Kamalizade did a pretty good job of explaining it in his article:
How To Fix Your Angular App When It’s Not Working in IE11

Summary

Supporting Internet Explorer in Angular is easy if you just remember where to find the polyfills.ts and browserslist files.