.vercelignoreで/scriptsを除外したら本番ビルドがTS2307で落ちた

結論

テストファイルがscripts/配下のモジュールをimportしていると、Next.jsの本番ビルドの型チェックがそのimportを辿って解決しようとする。.vercelignoreで/scriptsをVercelにアップロードしない設定にしていると、本番ビルドのマシン上にはそのファイルが存在せず、TS2307: Cannot find moduleでビルドが落ちる。

症状

Next.js 16.3.7へ更新した直後、Vercel本番ビルドがTS2307で失敗するようになった。ローカルでnext buildを実行しても再現しない。

原因を辿ると、テストの1つがscripts/lib/配下の.mjsファイルを直接importしていた。名寄せ処理の純粋な検証ロジックをCLIスクリプトとテストの両方から共有するための構成で、ローカルの作業ツリーではそのファイルが実在するため何の問題もなく型が解決できる。

ところがこのプロジェクトの.vercelignoreは、セットアップ専用のファイルをVercelにアップロードしないよう/scriptsを除外していた。Vercel CLIは.gitignoreを見ず.vercelignoreだけを見るため、gitには存在していても本番ビルドのマシン上にはscripts/ディレクトリそのものが無い。

原因

原因は、本番ビルドの型チェック範囲とVercelへ実際にアップロードされるファイルの範囲が、一致している前提になっていなかったことにある。

Next.jsの既定では、next buildの型チェックはプロジェクト全体のtsconfig.jsonを対象にする。これにはテストファイルも含まれるため、テストがscripts/配下をimportしていれば、本番ビルドの型チェックもそのimportを解決しようとする。

一方で.vercelignoreは「本番の実行に不要なファイルをアップロードしない」ためのものであり、/scriptsはまさにその代表（CLI用の運用スクリプト）だった。型チェックの設定側は.vercelignoreが何を除外しているかを一切見ていないため、「ローカルでは存在するが本番マシンには存在しないファイル」を本番ビルドの型チェックが前提にしてしまう状態になっていた。

直す

next.config.tsのtypescript.tsconfigPathに、本番ビルド専用のtsconfig.build.jsonを指定した。この設定ファイルは既存のtsconfig.jsonを継承しつつ、node_modules・__tests__・*.test.ts・*.test.tsxに加えてscripts・supabaseを型チェックの対象から除外する。

これによりnext buildはアプリ本体のコードだけを型チェックするようになり、テストがscripts/配下をimportしていても本番ビルドの型チェックはそこへ到達しない。テスト自体の型チェックは引き続きnpm run typecheck（tsconfig.json・プロジェクト全体）が担当するため、テストコードの型安全性は失われない。

再発防止

この問題が見えにくかったのは、型チェックの設定と.vercelignoreが別々のファイルで、互いを意識せずに書かれていたためだった。tsconfig.jsonは「プロジェクト全体の型を見る」という一般的な既定のまま置かれており、「Vercelへは何がアップロードされないか」という観点がその設定には最初から存在していなかった。

next.config.tsで本番ビルド用の型チェック範囲を明示的に分離したことで、「本番ビルドが型チェックする範囲」と「本番ビルドに実際に存在するファイルの範囲」を一致させる構造にした。テストが将来また別のセットアップ専用ディレクトリをimportするようになっても、tsconfig.build.jsonがその除外リストに含まれている限りは同じ問題を踏まない。