npm Peer Dependencies untuk Pembangun Profesional

この記事では、npm ピア依存関係 とは何か、特にそれらをいつ使用する必要があるかを明確にします。 ピア依存関係 は、プロジェクトの package.json ファイルのpeerDependency オブジェクトにリストされています。

この記事を最大限に活用するには、少なくとも npm の入門知識を持っている必要があります。

コンテンツ

この記事の内容:

1. ピア依存関係と通常の依存関係がどのように機能するかを正確に比較します。
2. ピア依存関係と依存関係の両方の例を見ていきます。
3. 次に、npm が バージョンの競合 をどのように処理するかを調べます。
4. 最後に、基本をしっかりと理解したので、いつピア依存関係が適切であるかを決定するためのアプローチを示します。

シナリオ

現実を保つために、Angular または React コンポーネント ライブラリ、あるいはいくつかの関数をエクスポートする単純な JavaScript ファイルを作成していると仮定しましょう。

あなたのプロジェクトは、npm レジストリのパッケージに依存しています。これらのパッケージはプロジェクトの依存関係です。

プロジェクトから独自の npm パッケージ を作成したいと考えています。したがって、npm Pack を使用して、プロジェクトから npm パッケージ を生成します。 npm レジストリに公開することもできます。

他のチームは、npm レジストリ上の パッケージ としてコンポーネント ライブラリを見つけることができます。 npm install を使用して、パッケージを依存関係として自分のプロジェクトに追加できます。 package.json で Dependency と Peer dependency を使用して、コンポーネント ライブラリが機能するためにどのパッケージも追加する必要があるかを他のプロジェクトに伝えます。

依存関係とピア依存関係

最も基本的なレベルで、依存関係 と ピア依存関係 がどのように機能するかを示します。

依存関係

依存関係は、プロジェクトの package.json ファイルの依存関係オブジェクトにリストされます。

コードの依存関係にパッケージを追加すると、次のようになります:

• 私のコードを実行するにはこのパッケージが必要です。
• このパッケージが node_modules ディレクトリに存在しない場合は、自動的に追加されます。
• さらに、このパッケージの依存関係にリストされているパッケージを追加します。これらのパッケージは 推移的な依存関係 と呼ばれます。

ピアの依存関係

ピアの依存関係は、プロジェクトの package.json ファイルのpeerDependency オブジェクトにリストされます。

コードのpeerDependencyにパッケージを追加すると、次のようになります。

• 私のコードは、このバージョンのパッケージと互換性があります。
• このパッケージが既に node_modules に存在する場合は、何もしません。
• このパッケージがnode_modulesディレクトリに存在しないか、バージョンが間違っている場合は、追加しないでください。ただし、見つからなかったことをユーザーに警告します。

依存関係の追加

そこで、npm パッケージ フォルダーの package.json ファイルに依存関係を追加します。パッケージを依存関係として追加する正確な方法と、パッケージの依存関係の例をいくつか見てみましょう。

依存関係の追加

依存関係 は、コードが実行できるようにするために依存する npm パッケージです。依存関係として追加できる一般的なパッケージには、lodash、D3、chartjs などがあります。

次のような通常の依存関係を追加します。

npm install lodash

npm は、プロジェクトの package.json ファイル内の依存関係オブジェクトにパッケージ名とバージョンを追加します。

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

package.json 内の依存関係を更新するために npm を取得するために --save フラグを使用する必要があった昔のことを覚えている人もいるかもしれません。ありがたいことに、もうその必要はありません。

ピア依存関係の追加

ピア依存関係 は、プロジェクトが 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.

Walau bagaimanapun, kami benar-benar ingin memberitahu pembangun versi Angular atau React yang mana pustaka kami serasi. Jadi saya mengesyorkan pendekatan berikut:

Tambahkan sekurang-kurangnya pakej sudut/teras atau tindak balas untuk versi yang serasi pada peerDependencies anda.

Dengan cara ini pembangun akan melihat amaran jika mereka cuba menggunakan pustaka komponen React 18 anda dalam projek React 16 mereka. Jangan bersusah payah menambah pakej Angular atau React yang lain. Anda boleh menganggap jika ia mempunyai sudut/teras atau bertindak balas, ia mempunyai perpustakaan lain yang berkaitan.

Kesimpulannya

Apabila ragu-ragu, anda mungkin harus cenderung menggunakan peerDependencies. Ini membolehkan pengguna pakej anda membuat pilihan mereka sendiri tentang pakej yang hendak ditambah.

Atas ialah kandungan terperinci npm Peer Dependencies untuk Pembangun Profesional. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!