投稿日:

package.jsonとpackage-lock.jsonについて

今回は、Gitの別のNode.jsプロジェクトを参照するためにどのようにすればいいのか整理しようと思います。その前に、package.jsonとpackage-lock.jsonの理解も必要なので、合わせて整理します。

その際に、依存関係をインストールする「npm install」「npm ci」も一緒に見ていきます。

package.jsonとpackage-lock.jsonとは

package.json

package.jsonはNode.jsプロジェクトのルートディレクトリに配置される基本的な設定ファイルのことです。

主に以下の内容を記述します。

  • プロジェクトの基本情報（名前、バージョン、説明など）
  • 依存関係の管理（dependencies、devDependencies）
  • スクリプトの定義（npm scripts）
  • プロジェクトのライセンス情報
{
  "name": "anveloper-project",
  "version": "1.0.0",
  "description": "Anveloper Private Project",
  "main": "index.js",
  "dependencies": {
    "express": "^4.17.1",
    "react": "^17.0.2"
  },
  "devDependencies": {
    "jest": "^27.0.0"
  },
  "scripts": {
    "start": "node index.js",
    "test": "jest"
  }
}

package-lock.json

package-lock.jsonはnpm installコマンドによって自動生成されるファイルで、依存関係の正確なバージョンを記録します。

主な役割

  • 依存関係の正確なバージョンを固定（ロック）する
  • プロジェクトを異なる環境で完全に再現可能にする
  • インストールプロセスを高速化する

このファイルには各パッケージの正確なバージョン、整合性チェック用のハッシュ値、依存関係のツリー構造などが含まれます。

npm installとnpm ciの違い

npm install: 開発環境向け

npm installは主に開発環境での日常的な使用に適しています。

  • package.jsonを基に依存関係をインストールし、必要に応じてpackage-lock.jsonを更新
  • 既存のnode_modulesを保持し、必要な部分だけ追加・更新
  • 柔軟性が高いが、環境間での完全な一貫性は保証されない

npm ci: CI/CD環境向け

npm ci（Clean Install）はCI/CD環境や本番環境でのデプロイ時に適しています。

  • package-lock.jsonを厳密に使用し、変更を一切行わない
  • 常にnode_modulesを全削除してからクリーンインストール
  • package.jsonとpackage-lock.jsonの整合性を検証
  • 高速で再現性の高いインストールを提供

（本題）内部別のプロジェクト（Gitリポジトリ）の参照方法

プロジェクトチームには、共通領域を担当するチームは業務ロジックを作成するチームなど色々なチームが存在しています。その際に、同じGitリポジトリ・プロジェクトで開発を進めると業務チームで共通領域のソースコードを直すことができてしまう。逆に共通領域チームが業務ロジックの修正ができてしまうことによりコーディングミスが起きえると思います。

上記を防ぐために、プロジェクトを分割して開発を進む。業務側では共通領域をインストールして参照すると人によるエラーは起きにくくなるでしょう。

package.jsonでの指定方法

別途Gitリポジトリで管理されている内部プロジェクトを参照するには、package.jsonのdependenciesに以下のように指定します。(package-lock.jsonだけ記述することもできます。)

{
  "dependencies": {
    "your-internal-project": "git+ssh://git@github.com/your-org/anveloper-project.git#main"
  }
}

特定のブランチ、タグ、コミットハッシュを指定することも可能です。

{
  "dependencies": {
    "branch-example": "git+ssh://git@github.com/org/repo.git#develop",
    "tag-example": "git+ssh://git@github.com/org/repo.git#v1.0.0",
    "commit-example": "git+ssh://git@github.com/org/repo.git#a1b2c3d4e5f6"
  }
}

package-lock.jsonでの参照情報

npm install実行後、package-lock.jsonには以下のような情報が記録されます。（pacakge-lock.jsonだけ記述した場合は、npm ciを利用します。）

{
  "dependencies": {
    "your-internal-project": {
      "version": "git+ssh://git@github.com/your-org/anveloper-project.git#a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9",
      "from": "git+ssh://git@github.com/your-org/anveloper-project.git#main",
      "requires": {
        "react": "^17.0.0",
        "typescript": "^4.5.0"
      }
    }
  }
}

注意点

  • version: 実際にインストールされる特定のコミットハッシュ
  • from: package.jsonで指定された参照元（ブランチ/タグなど）

ブランチ参照時の注意点

ブランチを参照する場合（特にmainやdevelopなどの頻繁に更新されるブランチ）、以下の問題が発生する可能性があります：

  • package-lock.jsonに記録されたコミットハッシュがブランチから消えた場合、npm ciが失敗する
  • チームメンバー間で異なるバージョンがインストールされる可能性がある

対策

  • 重要な依存関係にはタグを使用する
  • ブランチを参照する場合は、リベースやフォースプッシュを避ける
  • 定期的にnpm installでpackage-lock.jsonを更新する

まとめ

  • package.jsonは依存関係の大まかな指定に使用
  • package-lock.jsonは正確なバージョンを記録し、環境間の一貫性を保証
  • 内部プロジェクトの参照にはGitリポジトリのURLとブランチ/タグ/コミットハッシュを使用
  • CI環境ではnpm ciを使用して再現性の高いビルドを実現

Node.jsプロジェクトにおける依存関係管理、特に内部プロジェクトの参照方法を理解や活用することで、チーム開発の効率化と品質向上につながるでしょう。

コメントを残す