npm scriptsとpackage.jsonの基礎 | 開発環境構築とNext.js（TypeScript）入門 | Next.jsによるWebアプリケーション開発概論

この節で学ぶこと

この節では、package.json が何を管理するファイルなのか、そして npm scripts がなぜ開発で重要なのかを、整理します。

npm の公式文書では、package.json はパッケージの中核となる設定ファイルであり、scripts は任意のコマンドやライフサイクル処理を定義できる仕組みだと説明されています。

Next.js の公式導入でも、プロジェクト作成後は dev、build、start などの scripts を通じて開発を進める流れが示されています。

この節の到達目標は4つです。

package.json を見て「このプロジェクトが何者か」を大まかに読めること。
scripts が単なるメモではなく、開発手順そのものを表すと理解すること。
npm run dev や pnpm dev が、実際には package.json の scripts を実行していると説明できること。4
dependencies と devDependencies の違いを初歩レベルでつかむことです。 npm 公式は package.json を npm プロジェクト動作の中心として説明しており、scripts は npm run <stage> で実行できると明記しています。

package.jsonとは何か

一言でいえば「プロジェクトの設計メモ兼操作マニュアル」

package.json は、そのプロジェクトの名前、依存ライブラリ、実行コマンド、メタ情報などをまとめる JSON ファイルです。

npm 公式では、package.json は npm の挙動を左右する中心的なファイルであり、公開可能なパッケージには必須だと説明されています。

さらに npm は、package.json で記述された情報をもとに依存関係や scripts を扱います。

初心者のうちは、このファイルを「なんとなく置いてある設定ファイル」と見てしまいがちです。

けれど実際にはかなり重要です。たとえば、開発サーバを起動する dev、本番用ビルドを作る build、本番起動用の start は、しばしばこの中に定義されています。

つまり package.json は、このプロジェクトをどう扱うかを人間とツールの両方に伝えるファイルです。

Next.js の公式インストール手順でも、こうした scripts が最初から用意される構成が示されています。

JSON であることが大事

npm 公式は、package.json は実際の JSON でなければならず、JavaScript オブジェクト風の曖昧な記法ではだめだと説明しています。つまり、末尾カンマやコメントを勝手に書くと壊れます。

たとえば、これは正しい形です。

{
  "name": "my-app",
  "version": "0.1.0",
  "private": true
}

一方で、JSON ではコメントや末尾カンマは許されません。

ここは地味ですが、最初に知っておくと無駄なエラーを避けやすくなります。npm 公式が「must be actual JSON」と強く書いているのは、この種の混乱が多いからです。

Next.js プロジェクトでよく見る package.json

初期状態のイメージ

Next.js の公式導入では、create-next-app により TypeScript、ESLint、App Router などを含んだプロジェクトを生成できます。

その流れで package.json にも基本的な scripts が入ります。公式の手動導入例では、少なくとも dev、build、start、lint が定義されています。

なお、古い Next.js 13 系の文書では lint に next lint が載っていますが、現在の公式インストールページでは lint: "eslint" と示されています。

これは時期によって書き方が変化している点として押さえるべきです。

たとえば、Next.js の現在の公式導入ページに沿うと、次のような形をよく見ます。

{
  "name": "my-app",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint"
  }
}

これだけ見ると短いですが、かなり多くの意味が詰まっています。

name はプロジェクト名、version はバージョン、private は公開前提ではないことの宣言、そして scripts は日常的な操作の入口です。npm 公式も scripts を package.json の主要機能として扱っています。

`scripts` とは何か

コマンドに名前を付ける仕組み

npm 公式では、scripts は package.json の中でスクリプトコマンドの辞書を定義する仕組みであり、npm run <stage> で実行できると説明しています。

さらに pre と post を付けた前後処理も可能です。

たとえば、次のように書けます。

{
  "scripts": {
    "hello": "echo Hello",
    "dev": "next dev"
  }
}

このとき、hello は自分で付けた名前です。

実行するときは次のようにします。

npm run hello

これが分かると、scripts はただの設定ではなく、プロジェクト専用のショートカット集に見えてきます。

長いコマンドを毎回打たずに済むだけでなく、チーム全員が同じ入口から同じ処理を実行できるようになります。

npm 公式も arbitrary scripts をサポートすると明記しています。

`npm run` と `pnpm` の関係

npm 公式では scripts は npm run <stage> で実行するとされています。Next.js の公式ページでは pnpm 版の例として pnpm dev が示されています。つまり、package.json に書いた scripts を、どのパッケージマネージャーから呼び出すかが少し違うだけで、本質は同じです。

たとえば、次の2つは目的がほぼ同じです。

npm run dev

pnpm dev

どちらも、scripts.dev に定義されたコマンドを起動します。

この関係が分かると、コマンドに振り回されにくくなります。「npm の文法」「pnpm の文法」に見えていたものが、実は package.json にある設定の呼び出し方の違いだと見えてくるからです。

Next.js でよく使う scripts

`dev`

Next.js の公式導入では、開発サーバ起動に dev script を使う流れが示されています。通常は中身が next dev です。これにより開発モードでサーバが起動し、http://localhost:3000 で確認できます。

{
  "scripts": {
    "dev": "next dev"
  }
}

これは日常的に最もよく使う script です。

「開発を始めるボタン」くらいに考えてよいです。

`build`

build は本番向けのビルドを作る script で、通常は next build です。Next.js の公式インストール手順にも含まれています。

{
  "scripts": {
    "build": "next build"
  }
}

学習初期は毎日使うわけではありませんが、

「本番向けの準備をする入口」として重要です。

`start`

start は本番モードでアプリを起動する script で、通常は next start です。これも公式の基本セットに含まれています。

{
  "scripts": {
    "start": "next start"
  }
}

dev と違って、こちらは開発中の HMR 体験が中心ではありません。

この違いは第2章の後半でさらに効いてきます。

`lint`

現在の Next.js 公式インストールページでは lint は eslint として示されています。Next.js は eslint-config-next を提供しており、@next/eslint-plugin-next と React 向け推奨ルール群を含みます。

{
  "scripts": {
    "lint": "eslint"
  }
}

ここで少し注意が必要です。

古い記事では next lint と書かれていることがあります。実際、古い Next.js 文書にはその形が載っています。けれど現在の公式の導入ページでは eslint が使われています。古い記事を読むときは、Next.js の世代差を意識することが大切です。

dependenceiesとdevDependencies

何が違うのか

npm 公式の package.json 文書では、依存関係を dependencies や devDependencies として管理できます。一般的には、実行時に必要なものを dependencies、開発時に必要なものを devDependencies に入れます。npm 公式は両方を package.json の依存関係管理の一部として扱っています。

たとえば、次のような形です。

{
  "dependencies": {
    "next": "latest",
    "react": "latest",
    "react-dom": "latest"
  },
  "devDependencies": {
    "eslint": "^9.0.0",
    "typescript": "^5.0.0"
  }
}

初心者向けには、まずこう考えると分かりやすいです。

dependencies はアプリを動かすための材料
devDependencies は作るための道具

もちろん実際にはもう少し複雑ですが、最初はこれで十分です。

private: trueの意味

公開前提ではないプロジェクトだと示す

Next.js の公式インストール例では private: true が含まれています。これは、そのプロジェクトが npm レジストリへの公開対象ではないことを示すための設定としてよく使われます。npm 公式は private を公開制御に関わる項目として扱っています。

{
  "private": true
}

Web アプリの学習や社内開発では、この設定をよく見ます。

「間違って npm に publish しないようにする安全札」と考えると分かりやすいです。

pre / post スクリプト

前後に自動で処理を差し込める

npm 公式では、pre<name> と post<name> を使うと、対応する script の前後で自動実行されると説明しています。たとえば prebuild、build、postbuild のように書けます。

{
  "scripts": {
    "prebuild": "echo buildの前処理",
    "build": "next build",
    "postbuild": "echo buildの後処理"
  }
}

これは少し面白い機能です。

初心者のうちは多用しなくて構いませんが、「build の前に何か確認したい」「後処理でファイル生成したい」といったときに使えます。npm 公式がこの仕組みを標準機能として説明しているので、名前付き script に前後処理を付けられるのは正式な作法です。

package-lock.jsonとの違い

`package.json` は意図、`package-lock.json` は結果の固定

npm 公式では、package-lock.json は npm が node_modules や package.json を変更したとき自動生成され、実際に解決された依存ツリーを正確に記録するファイルだと説明しています。リポジトリへコミットすることも想定されています。

初心者向けには、こう覚えると分かりやすいです。

package.json は「何を使いたいか」
package-lock.json は「実際に何が入ったか」

この違いが見えると、なぜ lock ファイルが存在するのかが納得しやすくなります。

初心者が最初に読むべき package.jsonの場所

まずはこの順番で見る

最初に全部を読む必要はありません。

私は次の順番をおすすめします。

name
private
scripts
dependencies
devDependencies この順番がよい理由は、プロジェクトの性格 → 動かし方 → 材料と道具の順で理解できるからです。npm 公式の package.json 文書も、これらを主要な構成要素として扱っています。

例を1つ通して読む

{
  "name": "prince-web",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint"
  },
  "dependencies": {
    "next": "16.2.4",
    "react": "19.2.0",
    "react-dom": "19.2.0"
  },
  "devDependencies": {
    "eslint": "^9.0.0",
    "typescript": "^5.0.0"
  }
}

このファイルを日本語で読むと、次のようになります。

「prince-web という名前の非公開プロジェクトで、開発は next dev、ビルドは next build、本番起動は next start、lint は eslint を使う。実行時には Next.js と React が必要で、開発時には ESLint と TypeScript が必要」

こう読めるようになると、package.json はただの記号の塊ではなくなります。

よくある誤解

「scripts は npm 専用の特別な言語」

違います。

scripts はコマンドに名前を付けて呼び出しやすくする仕組みです。npm 公式も arbitrary scripts をサポートすると説明しています。中身はシェルコマンドや CLI コマンドです。

「`npm run dev` は npm 自体の機能を直接呼んでいる」

少し違います。

実際には package.json の scripts.dev を呼び出しています。つまり、プロジェクトごとに dev の中身は変わり得ます。Next.js プロジェクトではたまたま next dev が入っている、という理解が正確です。

「`package.json` があれば全部分かる」

かなり多くは分かりますが、全部ではありません。

実際に解決された依存関係は lock ファイル、細かなビルド設定は next.config や tsconfig.json、Lint 設定は ESLint 設定ファイルも関係します。npm 公式の package-lock.json 文書も、この分担を前提にしています。

実践

自分で script を1つ追加する

たとえば、次のように check という script を追加できます。

{
  "scripts": {
    "dev": "next dev",
    "check": "npm run lint && npm run build"
  }
}

この場合、check を実行すると lint のあと build を走らせる、という入口を1つ作れます。

scripts の便利さはここにあります。毎回の作業手順を、名前付きのボタンに変えられるのです。npm 公式は arbitrary scripts を許可しており、npm run <stage> で呼び出せると説明しています。

実行はこうです。

npm run check

練習問題

問1

package.json の説明として最も適切なものはどれですか。

A. 画像だけを保存する専用ファイル

B. プロジェクト名、依存関係、scripts などを管理する中心ファイル

C. CSS のみを書くためのファイル

D. ブラウザ履歴を保存するファイル

B. build script の前後で自動実行される

C. CSS 専用の特別な設定

D. package-lock.json の別名

B. 実際に解決された依存ツリーを記録する

C. API キーを暗号化する

D. Next.js のルーティングを定義する

Next.js の公式導入でも、dev、build、start、lint といった scripts が最初から開発フローの入口になっています。

初心者のうちは、まず次の4つが分かれば十分です。

package.json は JSON 形式の中心ファイルである。
scripts はコマンドに名前を付けて呼び出す仕組みである。
npm run dev や pnpm dev は、package.json の scripts を実行している。
dependencies と devDependencies は、材料と道具の違いとして大まかに捉えられる。

ここが読めるようになると、プロジェクトを開いた瞬間の不安がかなり減ります。

「何を打てばよいのか分からない」から、「まず package.json を見れば入口が分かる」へ変わるからです。

参考文献

npm Docs, package.json.
npm Docs, scripts.
npm Docs, About packages and modules.
npm Docs, package-lock.json.
Next.js Documentation, Getting Started: Installation.
Next.js Documentation, Configuration: ESLint.