開発コマンドの統一は何を優先したのか:環境一致という価値選択

著者: ClaudeMix Team |

開発コマンドの統一は、ローカル開発環境と本番のビルドプロセスを一致させることを優先している。

① 開発コマンドの統一は何を優先したか

一般的な開発フローでは、「動作確認用のプレビューコマンド」と「日常の開発コマンド」を区別せずに使うことがある。特にエッジランタイム向けのビルドプロセスでは、プレビュー用コマンドが内部で本番相当のビルドを再度実行し、開発用のビルドプロセスと二重にライブラリをバンドルしてしまうことがある。

cloudflareDevProxyVitePlugin のような公式プラグインは、Viteの開発サーバー内でエッジ環境をシミュレートし、単一のビルドプロセスに統一することを優先する。

  • 【優先した価値】: ローカル開発環境と本番ビルドプロセスの一致。単一のビルドプロセスでライブラリを管理し、重複バンドルの発生源を構造的になくす
  • 【犠牲にした価値】: 個別ライブラリを external 化するような対症療法の速さ。根本原因(開発コマンドの誤用)に向き合う分、調査と修正に時間がかかる

② ClaudeMixでやったこと

Before: 開発用コマンドとして、ビルド後の動作確認用である wrangler pages dev を使用していた。Reactを使う全コンポーネントで Invalid hook call エラーが発生していた。

// package.json(変更前)
{
  "scripts": {
    "dev": "cross-env NODE_OPTIONS=--max-old-space-size=4096 remix vite:dev",
    "dev:wrangler": "npm run build && wrangler pages dev ./build/client --compatibility-date=2024-09-23 --compatibility-flags=nodejs_compat"
  }
}

After: cloudflareDevProxyVitePlugin をVite設定に追加し、dev コマンドを remix vite:dev に一本化した。

--- a/vite.config.ts
+++ b/vite.config.ts
-import { vitePlugin as remix } from "@remix-run/dev";
+import { vitePlugin as remix, cloudflareDevProxyVitePlugin } from "@remix-run/dev";

 export default defineConfig({
   plugins: [
-    remix({ future: { v3_relativeSplatPath: true } }),
+    cloudflareDevProxyVitePlugin(),
+    remix({ future: { v3_relativeSplatPath: true }, serverModuleFormat: "esm" }),
     tsconfigPaths(),
   ],
--- a/package.json
+++ b/package.json
-    "dev": "cross-env NODE_OPTIONS=--max-old-space-size=4096 remix vite:dev",
-    "dev:wrangler": "npm run build && wrangler pages dev ./build/client --compatibility-date=2024-09-23 --compatibility-flags=nodejs_compat",
+    "dev": "remix vite:dev",

③ 技術的負債

  • 【解消した負債】: React Hooksを使用する全コンポーネントでのエラー発生。改修前は「Hooksを使う全コンポーネントでエラーが発生」、改修後は「完全に解消」で、エラー発生の有無という構造的なカウントで検証できる。所要時間や割合としての定量値は本文に存在しない
  • 【新たに生まれた負債(あれば)】: なし。external 化のような対症療法を避け、開発コマンドの構造自体を修正したため、新たな回避コードは残っていない

④ 経営翻訳

倉庫からの出荷準備を、通常業務用の作業手順と、出荷前の最終確認用の作業手順とで別々の担当者・別々の設備を使って行っていたところ、同じ荷物が二重に梱包される事態が発生していた業務に相当する。最終確認用の設備を日常の作業にそのまま流用していたことが原因だった。出荷準備の手順を1つの設備・1つのプロセスに統一することで、二重梱包は完全になくなった。

この「ローカルと本番の環境差異」という問題は、ファイルシステムAPIが使えないという制約に直面した記録にも通じる。後に、Windowsでのキャッシュロックなど、wrangler pages devが引き起こす別種の環境問題も明らかになるが、それは本記事とは別の側面の話になる。