まず結論
package.json は、JavaScriptプロジェクトの説明書です。
どんなプロジェクトか、どんなコマンドがあるか、どんなパッケージに依存しているかが書かれています。
新しいリポジトリを見たら、まず package.json を読むと全体像をつかみやすくなります。
よくある構成
{
"name": "my-site",
"version": "1.0.0",
"type": "module",
"scripts": {
"dev": "astro dev",
"build": "astro build",
"preview": "astro preview"
},
"dependencies": {
"astro": "^6.0.0"
},
"devDependencies": {
"typescript": "^5.0.0"
},
"engines": {
"node": ">=22.0.0"
}
}
すべてを暗記する必要はありません。まず見るべき場所は scripts、dependencies、devDependencies、engines です。
scripts
scripts は、よく使うコマンドの名前を定義する場所です。
{
"scripts": {
"dev": "astro dev",
"build": "astro build"
}
}
この場合、次のように実行できます。
npm run dev
npm run build
dev は開発サーバ、build は本番用ビルドであることが多いです。ただし中身はプロジェクトごとに違います。必ず scripts の中身を見ます。
dependencies
dependencies は、プロジェクトが依存しているパッケージです。
{
"dependencies": {
"astro": "^6.0.0",
"mermaid": "^11.0.0"
}
}
アプリの実行やビルドに必要なものが入ります。フレームワークや本番コードで使うライブラリがここに入ることが多いです。
devDependencies
devDependencies は、開発や検証に使うパッケージです。
{
"devDependencies": {
"typescript": "^5.0.0",
"tailwindcss": "^4.0.0"
}
}
テスト、lint、型チェック、ビルド補助ツールなどが入ります。
フロントエンドでは、最終的に静的ファイルへビルドするため、本番サーバで直接使わないものも多くあります。そのため、dependenciesとの境界はプロジェクトによって少し変わります。
engines
engines は、必要なNode.jsやnpmのバージョンを示します。
{
"engines": {
"node": ">=22.0.0",
"npm": ">=10.0.0"
}
}
ローカルでは動くのにCIや本番で動かない場合、Node.jsのバージョン違いが原因になることがあります。
type: module
type は、JavaScriptのモジュール形式に関係します。
{
"type": "module"
}
type: "module" のプロジェクトでは、import / export を使うES Modulesとして扱われます。古いCommonJS形式では require() が使われます。
読む順番
初めて見るプロジェクトでは、次の順番が実用的です。
scriptsで起動・ビルド・検証コマンドを見るdependenciesで主要フレームワークを見るdevDependenciesで開発ツールを見るenginesでNode.jsの条件を見る- lockfileがあるか見る
実践メモ: READMEが古いことはありますが、package.jsonのscriptsは実際に動くコマンドに近い情報です。
まとめ
package.json は、プロジェクトの入口です。起動方法、ビルド方法、依存しているパッケージ、必要な実行環境が分かります。
エラー調査や新しいプロジェクト参加時は、まず package.json を読む習慣をつけると、迷子になりにくくなります。
