专业开发人员的 npm 对等依赖关系-js教程-PHP中文网

npm Peer Dependencies for the Professional Developer

在本文中，我将阐明 npm 对等依赖项 是什么，特别是何时应该使用它们。 对等依赖项 列在项目的 package.json 文件的peerDependency 对象中。

要充分利用本文，您至少应该对 npm 有一个介绍性的了解。

内容

在这篇文章中：

我们将比较对等依赖关系与常规依赖关系的工作方式。
我们将查看一些关于对等依赖关系和依赖关系的示例。
然后，我们将研究 npm 如何处理版本冲突。
最后，在我们牢牢掌握了基础知识后，我们将提出一种方法来决定何时适当的对等依赖关系。

场景

为了保持真实，我们假设您正在创建一个 Angular 或 React 组件库，甚至只是一个导出一些函数的简单 JavaScript 文件。

您的项目依赖于 npm 注册表中的包。这些包是您项目的依赖项。

您想从您的项目创建自己的npm 包。因此，您使用 npm pack 从您的项目生成 npm 包。您甚至可能决定将其发布到 npm 注册表。

其他团队可以在 npm 注册表上找到您的组件库作为包。他们可以使用 npm install 将您的包添加为他们自己的项目中的依赖项。我们在 package.json 中使用依赖项和对等依赖项来告诉其他项目还需要添加哪些包才能使我们的组件库正常工作。

依赖关系与对等依赖关系

在最基本的层面上，这是依赖关系和对等依赖关系的工作原理：

依赖关系

依赖项列在项目的 package.json 文件的依赖项对象中。

当您在代码的依赖项中添加包时，您是在说：

我的代码需要这个包才能运行。
如果我的node_modules目录中尚不存在此包，则自动添加它。
此外，添加此包的依赖项中列出的任何包。这些包称为传递依赖项。

对等依赖性

对等依赖项列在项目的 package.json 文件的peerDependency 对象中。

通过在代码的对等依赖项中添加一个包，您可以说：

我的代码与此版本的软件包兼容。
如果该包已存在于node_modules中，则不执行任何操作。
如果node_modules目录中尚不存在此包或者版本错误，请不要添加它。但是，向用户显示未找到它的警告。

添加依赖项

因此，我们在 npm 包文件夹的 package.json 文件中添加依赖项。让我们具体看看如何添加包作为依赖项以及包依赖项的一些示例。

添加依赖项

A 依赖项 是一个 npm 包，我们的代码依赖它才能运行。一些可以作为依赖项添加的流行软件包是 lodash、D3 和 Chartjs。

我们添加如下常规依赖项：

npm install lodash

登录后复制

npm 将包名称和版本添加到我们项目的 package.json 文件中的依赖项对象。

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

登录后复制

你们中的一些人可能还记得过去我们必须使用 --save 标志来让 npm 更新 package.json 中的依赖项。值得庆幸的是，我们不需要再这样做了。

添加对等依赖项

对等依赖项 用于指定我们的项目与 npm 包的特定版本兼容。 Angular 和 React 就是很好的例子。

要添加对等依赖，您实际上需要手动修改package.json 文件。例如，对于组件库项目，根据您使用的框架，我建议添加 angular/core 或 react 作为对等依赖项。

因此，如果您想指定您的包是为 React 18 构建的，您可以包含如下内容：

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

登录后复制

或者你可能想说你已经使用 Angular 版本 17 和 18 测试了你的组件库，但没有使用 19，因为它还没有发布。然后你可以使用：

"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.

但是，我们确实想告诉开发人员我们的库与哪些 Angular 或 React 版本兼容。所以我推荐以下方法：