ローカルパッケージをシンボリックリンクでインストールしたらTypeScriptの型定義がコンフリクトして困った

npmやyarnには、依存先のパッケージをシンボリックリンクとしてnode_modules内にインストールする手法があります。

npm link

が代表的な例です。しかしながら、多くの場合この状況となるのはpackage.jsonに

{"dependencies":{"bando-commons":"file:path/to/directory"}}

のように指定がなされている場合です¹。

この時、指定されたディレクトリがnode_modules配下にシンボリックリンクされますが、この時指定されたディレクトリ内にあるnode_moduleが紛れ込んでしまうことに注意が必要です。

project
├─ package.json
├─ node_modules
│ ├─ linked_project (symlink)
│ │ ├─ node_modules

のような感じです。通常の方法でインストールした場合はnpm自体の依存関係解決機能により１つのパッケージのみしかインストールされないため大丈夫なのですが。

この構成がTypeScriptの型定義ファイルに悪影響を及ぼす場合があります。具体的にはインストール先とインストール元で異なるバージョンのパッケージを使っていた場合です。この時、異なる内容のdeclare module宣言が重複するため、TypeScriptはどちらを使ってよいか判断できず困るという具合です。

解決方法としては簡単で、双方の依存先のパッケージのバージョンをそろえるだけです。package-lock.jsonやyarn.lockの内容を確認しましょう。yarnでの手法についてはこちらが参考になります。

なお、関連する話題のissueがありますので併せて確認すると良いと思います。