【package.json】1つのリポジトリに複数のプロジェクトフォルダがある時の注意点

はじめに

プロジェクトの概要→ディレクトリ構成→詳細の設定方法という流れで書いていきます
不要なところは飛ばしてみてください

プロジェクト概要

今回アサインされた案件では、管理画面とホームページの2種類のサービスが存在し、両者で共通して利用する FirebaseのAPIやコンポーネントがありました。そこで、以下のようなディレクトリ構成にてプロジェクトを管理することにしました。

project-root/
├── web/                # Next.js の雛形（ホームページ用）
│   ├── pages/
│   ├── public/
│   ├── package.json
│   └── ... その他のファイル
├── admin/              # Next.js の雛形（管理画面用）
│   ├── pages/
│   ├── public/
│   ├── package.json
│   └── ... その他のファイル
├── firebase/           # Firebase API 関連のファイル群
└── common-components/  # 共通コンポーネントのファイル群

デプロイに関して

管理画面とホームページは、それぞれ別のGCPサービスにアップロードする予定です。
例えば管理画面の場合、admin/ ディレクトリ内の Dockerfileを用いてコンテナ化するため、
プロジェクトルートにある Firebase APIやコンポーネントを正しく配置してpathを正確に指定してあげないと
うまく動作しない問題が発生してしまいました

ワークスペースの詳細設定

今回のプロジェクトでは、npm のワークスペース機能を利用して、ルートディレクトリから各サブプロジェクトの依存関係を一括で管理しています。以下、その仕組みと注意点について詳しく解説します。

1. npm install の挙動

ルートの package.json でワークスペース（例: web/, admin/, firebase/）を指定している場合、ルートで npm install を実行すると、各ワークスペースの依存関係も自動的にインストールされます。
つまり、個別のフォルダで別々に npm install を実行する必要はなく、全体の依存関係が一括管理されるため、セットアップが非常に楽になります。

2. package.json の設定

ワークスペースを活用する上で重要なのが、各プロジェクト（読み込む側、読み込まれる側）の package.json の設定です。
ここでは、読み込まれる側（共通で利用する Firebase API やコンポーネント）と、読み込む側（web や admin）での設定例を紹介します。

2.1 ルートの package.json

まずはルートにおけるワークスペースの指定です。
以下のように、各サブディレクトリを workspaces 配列に記載します。

{
  "private": true,
  "workspaces": [
    "web",
    "admin",
    "firebase"
  ]
}

これでルートでnpm installするだけで個別のフォルダで別々に npm install を実行する必要はなくなりました

2.2 読み込まれる側：共通コンポーネントの package.json

共通のコードは、例えば common-components ディレクトリにまとめ、package.json の name フィールドでモジュール名を定義します。
また、main フィールドでエントリーポイントを指定しておくことで、読み込む側での参照が簡単になります。

{
  "name": "common-components",
  "version": "1.0.0",
  "main": "index.ts"
}

共通モジュールのコード例（common/index.js）:

export { default as Production } from "./production/production";

自分の場合はProductionコンポーネントを作成しました
他にもコンポーネントを共有したい場合は都度作成し、ここでまとめてexportできるようにしていくイメージです

2.3 読み込む側：web プロジェクトの package.json

読み込む側では、依存関係に共通モジュールを追加します。
ここで指定するバージョンは、共通側の package.json と一致させる必要があります。

{
  "name": "web",
  "version": "1.0.0",
  "dependencies": {
    "common": "1.0.0"
  }
}

2.4 読み込み側のコード例

web プロジェクト内で、共通モジュールを読み込む例です。

// web/pages/index.js
import { Production } from 'common';

export default function HomePage() {
  return <Production/ >;

3. 注意点（ここでめちゃくちゃ詰まった）

• ワークスペースの指定:
  こういったパスの指定の仕方があるのですが、

"dependencies": {
  "file:../common-components"
}

ディレクトリ構造や環境が変わると動作しなくなる可能性があるのでバージョンで指定してあげる方がいいです。

• フォルダ名と package.json の name の一致:
  各ワークスペースのディレクトリ名と、その中の package.json に記載する name フィールドは一致させる必要があります。
  自分はキャメルケースでフォルダ名を作成していたんですが、package.jsonではスネークケースが推奨されるらしく、ほなpackage.jsonはスネークケースで書くか...→謎のエラー発生で解決に時間がかかり辛かったです、、

この設定により、各サービスで共通のコードを効率的に共有・管理しつつ、デプロイ時は個別の GCP サービスにアップロードできる柔軟な環境を実現できます。