メインコンテンツまでスキップ

第27章：npm scripts設計：「覚えなくていい」コマンド体系🧩✨

この章のゴールはシンプル👇 **「毎日使うコマンドを固定して、長い呪文（dockerコマンド等）を隠し、迷いゼロにする」**です😊👍

1) まず知っておくと得すること（npmの“素の挙動”）🔍​

  • npm run は、package.json の scripts を実行するための入口です。コマンド名を省略すると 利用可能なスクリプト一覧が表示されます。(docs.npmjs.com)
  • Node v24 系は npm v11 を同梱していて（つまり npm 側もわりと新しめ）、「npm scriptsは“標準の運用機構”」として使ってOKな時代です。(nodejs.org)
  • pre<name> / post<name> を作ると、対象スクリプトの前後に 自動で走る仕組みがあります（便利だけど、初心者は事故りやすいので使いどころを選ぶ）(docs.npmjs.com)

2) “覚えなくていい体系”の設計ルール（超重要）🧠✨​

ここからが本題です💡 scriptsは「設計」です。コマンドを増やすほど迷うので、入口を絞ります。

ルールA：入口は固定の“5〜8個”にする🚪​

まずはこのへんだけを「人間が覚えるコマンド」にします👇

  • dev（開発を起動）
  • test（テスト一発）
  • lint（チェック）
  • format（整形）
  • typecheck（型だけチェック）
  • build（本番ビルドがあるなら）
  • start（本番起動があるなら）
  • ci（CIでまとめ実行したいなら）

入口が固定だと、チームでも未来の自分でも迷いません😊

ルールB：派生は「コロン」で枝分かれ🌿​

覚えるのは dev だけ。細かいのは“必要な人だけ使う”にします。

  • dev:logs
  • test:watch
  • lint:fix
  • format:check
  • docker:up / docker:down / docker:sh …みたいに用途別に

ルールC：1行で書けないなら「scripts/ に逃がす」🏃‍♂️💨​

package.json に長いコマンドを書き始めると、保守地獄になります😇 やることが増えたらこう👇

  • package.json：入口だけ（短い）
  • scripts/*.mjs：中身（長い処理、分岐、ログ整形など）

ルールD：Windowsの罠は最初から回避🪤​

  • 環境変数の書き方がShellで変わる問題 → cross-env を使う（Windows対策の定番）(npm)

  • rm -rf みたいなUNIX専用 → rimraf か Nodeスクリプトへ

  • 並列実行で & とかに頼るとWindowsのcmd/pwsh差で事故りがち → npm-run-all / concurrently を使うのが無難

    • npm-run-all --parallel は Windowsでも動く前提で作られてる、という話が明記されています。(GitHub)

3) “この教材の典型プロジェクト”向け scripts 例 🧩（コピペOK）​

ポイントは「dev/test/lint/format を固定名にする」と「dockerの長文を隠す」です😎✨

{
  "scripts": {
    "dev": "npm run docker:up",
    "test": "vitest run",
    "test:watch": "vitest",
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "prettier . --write",
    "format:check": "prettier . --check",
    "typecheck": "tsc -p tsconfig.json --noEmit",

    "docker:up": "docker compose up --build",
    "docker:down": "docker compose down",
    "docker:logs": "docker compose logs -f --tail=200",
    "docker:sh": "docker compose exec api sh",
    "docker:ps": "docker compose ps",

    "help": "node scripts/help.mjs"
  }
}

✅ 覚えるのは npm run dev だけ（あとは必要になったら npm run で一覧見ればOK）(docs.npmjs.com)

どういう意図？（超かんたん解説）😊​

  • dev：開発開始の“唯一の入口”🚪✨（中身はdockerに丸投げ）
  • test：CIでもローカルでも同じでOK🧪
  • lint / format：事故防止と読みやすさ🧹
  • typecheck：テストとは別に“型の保証”だけ高速に🔎
  • docker:*：人間が打つには長いものを短縮🪄
  • help：プロジェクト独自の“使い方”を表示（後で効く！）

4) 「help」コマンドで迷子ゼロにする🧭✨​

npm run でも一覧は出ますが、何をするコマンドかまでは伝わりません。 なので、プロジェクト専用の説明を npm run help に入れると強いです😊

./scripts/help.mjs の例👇

const lines = [
  "🧩 よく使うコマンド",
  "  npm run dev           : 開発を起動（Compose up）",
  "  npm run test          : テスト一発",
  "  npm run test:watch    : テストwatch",
  "  npm run lint          : ESLintチェック",
  "  npm run lint:fix      : ESLint自動修正",
  "  npm run format        : Prettier整形",
  "  npm run format:check  : Prettier整形チェックだけ",
  "  npm run typecheck     : 型チェック（noEmit）",
  "",
  "🐳 Docker系",
  "  npm run docker:logs   : ログ追跡",
  "  npm run docker:sh     : apiコンテナに入る",
];

console.log(lines.join("\n"));

これで新しく入った人も、未来の自分も迷いません🥹✨

5) 環境変数をscriptsで使いたい時（Windowsで詰まりやすい）💣​

たとえば「ログを増やす」みたいな時に環境変数を使うことありますよね。

**ダメになりがち例（Shell差が出る）**😵

  • NODE_ENV=development node ... はWindowsだとそのままでは動かないことが多い

安定解：cross-env✅（Windows対策の定番）(npm)

{
  "scripts": {
    "dev:debug": "cross-env LOG_LEVEL=debug npm run dev"
  }
}

6) pre/post scripts は“初心者のうちは控えめ”が正解😇​

prebuild → build → postbuild みたいに自動で前後処理できて便利なんですが、 「いつ何が走ってるのか分からない😵」が起きやすいです。(docs.npmjs.com)

さらに npm の公式ドキュメントでも、preinstall / install は基本的に避けるべき（特殊事情以外）という趣旨が書かれています。(docs.npmjs.com)

なので最初はこういう方針が安全です👇

  • ✅ “開発者が明示的に叩くコマンド”に寄せる（npm run build とか）
  • ✅ 自動で走る系（install hooks）は極力置かない

7) scriptsの追加は「コマンドでやる」と事故らない🛠️✨​

package.json を手でいじってもいいんだけど、タイポが怖いならこれ👇

例：

npm set-script dev "npm run docker:up"
npm set-script docker:up "docker compose up --build"
npm set-script docker:logs "docker compose logs -f --tail=200"

8) ミニ課題（10〜20分）🧪🎮​

  1. npm set-script で、次の3つを追加

  2. npm run を打って、一覧が出るのを確認（“迷ったらここ”）(docs.npmjs.com)

  3. npm run dev → 別ターミナルで npm run docker:logs

  4. scripts/help.mjs を作って npm run help を表示できたら勝ち🏆✨

9) AI拡張の使いどころ（Copilot / Codex向け）🤖✨​

AIは「設計意図を渡す→案を出させる→差分レビュー」が一番安全です👍

そのまま使えるプロンプト例🎁​

  • scripts設計を作らせる

    • 「package.json の scripts を、“入口は dev/test/lint/format/typecheck に固定、派生は colon 記法、docker compose 操作は docker:* にまとめる”方針で提案して。Windowsで壊れやすい書き方は避けて」

  • help.mjs を作らせる

    • 「npm run help で表示する help.mjs を作って。初心者向けに短く、よく使う順で。絵文字も少し入れて」

  • 危険ポイントをチェックさせる

    • 「この scripts は Windows で壊れやすい部分ある？環境変数、パス、並列実行、クォートの観点でレビューして」

10) まとめ（この章で“完成”した状態）🎉​

  • npm run dev だけ覚えれば開発が始まる🚀
  • npm run で一覧を出して迷子にならない🧭(docs.npmjs.com)
  • Dockerの長文コマンドは docker:* に隔離して、普段は見なくていい🫥
  • Windowsの罠（環境変数/並列）を最初から潰す💥（cross-env や npm-run-all 等）(npm)

次の第28章では、この docker:* をさらに整理して Compose操作も完全ワンコマンド化していきます🧱➡️🖱️✨