パッケージのインストール

パッケージマネージャーの基本がわかったところで、実際にパッケージをインストールしてみましょう。

インストールに必要なもの

パッケージをインストールするには、プロジェクトにpackage.jsonファイルが必要です。package.jsonはプロジェクトのメタデータ(名前、バージョン、依存パッケージなど)を管理するファイルです。

まだpackage.jsonがない場合は、次のコマンドで作成できます。

shell
npm init -y

shell
npm init -y

-yオプションをつけると、すべての項目をデフォルト値で自動設定します。

package.jsonの詳細については、次のページを参照してください。

📄️ package.json

package.jsonの役割

パッケージのインストール方法

基本のコマンド

パッケージをインストールするには、package.jsonが存在するディレクトリ(通常はプロジェクトのルートディレクトリ)でnpm installコマンドにパッケージ名を指定します。たとえば、バリデーションライブラリのzodをインストールするには、次のように実行します。

shell
npm install zod

shell
npm install zod

このコマンドを実行すると、次のことが自動的に行われます。

1. パッケージレジストリ(npmjs.com)からzodパッケージをダウンロードする
2. プロジェクトのnode_modulesディレクトリにファイルを配置する
3. package.jsonのdependenciesにzodを追記する
4. package-lock.jsonにインストールしたバージョンの詳細を記録する

開発用パッケージのインストール

テストツールやTypeScriptコンパイラなど、開発時にだけ必要なパッケージは-Dオプション(--save-devの省略形)をつけてインストールします。

shell
npm install -D typescript

shell
npm install -D typescript

-Dをつけるとpackage.jsonのdevDependenciesに記録されます。-Dなしの場合はdependenciesに記録されます。この2つの違いについて詳しくは、package.jsonのページを参照してください。

📄️ package.json

package.jsonの役割

注記

OSSのドキュメントなどでnpm install --save-devという表記を見かけることがあります。--save-devは-Dの省略前の正式名で、同じ意味です。

他のパッケージマネージャーでのコマンド

npm以外のパッケージマネージャーでも、同様の操作ができます。

パッケージマネージャー	コマンド
npm	npm install zod
pnpm	pnpm add zod
Bun	bun add zod
Yarn	yarn add zod

ローカルインストールとグローバルインストール

パッケージのインストールには、ローカルインストールとグローバルインストールの2種類があります。

ローカルインストールは、特定のプロジェクト内でのみパッケージを使えるようにするインストール方法です。npm installのデフォルトの動作で、プロジェクトのnode_modulesディレクトリにパッケージが配置されます。

shell
npm install zod

shell
npm install zod

グローバルインストールは、システム全体でパッケージを使えるようにするインストール方法です。-gオプションをつけます。コマンドラインツールとして使うパッケージ(typescriptのtscコマンドなど)をインストールする際に使うことがあります。

shell
npm install -g typescript

shell
npm install -g typescript

注意

グローバルインストールは、プロジェクトごとのバージョン管理ができません。特別な理由がない限り、ローカルインストールを使うことをお勧めします。ローカルインストールしたコマンドラインツールは、次に説明するnpxコマンドで実行できます。

npxコマンド

npxは、npmに同梱されているコマンド実行ツールです。ローカルインストールしたパッケージのコマンドを直接実行できます。

たとえば、TypeScriptコンパイラをローカルインストールした場合、npxを使って実行します。

shell
npm install -D typescript
npx tsc --version

shell
npm install -D typescript
npx tsc --version

npxを使わない場合、./node_modules/.bin/tscのようにフルパスを指定する必要があります。npxはこの手間を省いてくれる便利なコマンドです。

また、npxはプロジェクトにインストールされていないパッケージを一時的にダウンロードして実行することもできます。プロジェクトの初期化コマンドなど、一度だけ実行したいツールに便利です。

shell
npx create-next-app my-app

shell
npx create-next-app my-app

他のパッケージマネージャーにも同様のコマンドがあります。

パッケージマネージャー	コマンド
npm	npx tsc
pnpm	pnpm exec tsc
Bun	bunx tsc
Yarn	yarn tsc

バージョン指定

パッケージをインストールするとき、特定のバージョンを指定できます。

shell
npm install zod@3.22.0

shell
npm install zod@3.22.0

@の後にバージョン番号を書くことで、そのバージョンをインストールします。バージョンを指定しない場合は、最新バージョンがインストールされます。

package.jsonには、バージョンの範囲を指定する記号が使われることがあります。

記号	意味	例	範囲
^	マイナーバージョンまでのアップデートを許可	^3.22.0	3.22.0以上4.0.0未満
~	パッチバージョンのアップデートのみ許可	~3.22.0	3.22.0以上3.23.0未満
*	すべてのバージョンを許可	*	すべて

npm installでパッケージをインストールすると、package.jsonに記録されるバージョンにはデフォルトで^(キャレット)が付きます。

セマンティックバージョニング

バージョン番号の付け方にはセマンティックバージョニング(Semantic Versioning、略してsemver)という業界標準のルールがあります。バージョン番号は「メジャー.マイナー.パッチ」の3つの数字で構成されます。

たとえば、バージョン3.22.4は次のように読みます。

• 3 ─ メジャーバージョン
• 22 ─ マイナーバージョン
• 4 ─ パッチバージョン

それぞれの数字が上がる条件は次のとおりです。

バージョン	上がる条件	例
メジャー	後方互換性のない変更(破壊的変更)	APIの削除や仕様変更
マイナー	後方互換性のある機能追加	新しい関数の追加
パッチ	バグ修正	既存機能の不具合修正

このルールがあるおかげで、^3.22.0と指定すれば「メジャーバージョンが同じ範囲なら安全にアップデートできる」と判断できます。メジャーバージョンが変わるときだけ、破壊的変更がないか確認すればよいのです。

パッケージはどこからやってくるか？ ─ パッケージレジストリ

npm installを実行すると、パッケージはパッケージレジストリからダウンロードされます。パッケージレジストリとは、パッケージを保管・配布するためのサービスです。

npmjs.com

npmjs.comは、npm公式のパッケージレジストリです。世界最大のJavaScriptパッケージレジストリで、200万以上のパッケージが公開されています。npm installコマンドは、デフォルトでこのレジストリからパッケージをダウンロードします。

パッケージを探すときは、npmjs.comのサイトでパッケージ名や機能を検索できます。パッケージの探し方について詳しくは、次のページを参照してください。

📄️ パッケージを探す

TypeScript/JavaScriptの開発では、「自分でゼロから書く」よりも「既存のパッケージを使う」ほうが効率的な場面が多くあります。しかし、同じ目的のパッケージが複数存在することが珍しくありません。日付操作だけでも、date-fns、dayjs、luxonなど複数の選択肢があります。

GitHub Packages

GitHub Packagesは、GitHubが提供するパッケージレジストリです。企業がプライベートなパッケージを社内に配布する用途で使われることが多いです。

その他のレジストリ

企業によっては、社内専用のプライベートレジストリを運用していることもあります。社内独自のパッケージを安全に配布するために使われます。

コラム: 新しいレジストリーの動向

JavaScriptのパッケージレジストリには新しい動きもあります。jsr.ioは、Denoチームが開発しているパッケージレジストリです。TypeScriptをネイティブにサポートし、ESモジュール専用という特徴があります。まだ初期段階のサービスですが、TypeScript開発者にとって注目すべき動向です。

学びをシェアする

・npm installでパッケージを追加。-Dで開発用依存に記録
・ローカルインストールが基本。npxでCLIツールを実行可能
・semverは「メジャー.マイナー.パッチ」の3数字構成
・npmjs.comがデフォルトのパッケージレジストリ

『サバイバルTypeScript』より

この内容をXにポストする