ANDPAD 引合粗利管理のフロントエンドを担当している小泉です。
昨年 7 月に Nuxt 4 が正式リリースされ、私たちのチームでもアップデートに向けた準備を本格的に進めています。
その過程で、Nuxt の大きな特徴の１つである、関数やコンポーネントの「自動インポート」を完全に無効化し、全ファイルに明示的なインポート文を追加するという意思決定を行いました。
こう書くと、一見、Nuxt ならではの利便性を手放し、Vue / Nuxt をあえて採用するメリットを損なうような選択に見えるかもしれません。しかし、実際はそうではなく、むしろ今後も長く Nuxt を使い続けていくための、ポジティブな意思決定でした。
この記事では、Nuxt を採用しながらあえて明示的なインポートに移行した理由と、数千ファイルに及ぶ大規模な移行をどのように完遂したかについて紹介します。
アップデートを阻む密結合なテスト
自動インポートの無効化に踏み切った最大のきっかけは、Nuxt 4 への移行準備中に、「テストが壊れてアップデートできない」という問題に直面したことです。
現在私が担当しているプロダクトは、2020 年に Nuxt 2 で開発をスタートし、2023 年に Nuxt 3 へ移行しました。当時はまだ公式モジュールである @nuxt/test-utils が十分に整備されていなかったこともあり、自動インポート相当のインポート文をテスト実行時にも補完するために、自前で多くのモックや自動追加用のコードを書いて対応していました。
これは当時発生したエラーを乗り越えるためには必要な対応でしたが、結果としてテストが Nuxt の具体的な内部実装に強く依存することになりました。そのため、Nuxt のバージョンを上げようとすると自前モックがうまく適用されず、失敗するテストが多発したのです。
問題は、このテストを直すために @nuxt/test-utils へ移行しようとしても、そのリリースのために Nuxt の最新バージョンへのアップデートが要求されることです。Nuxt 本体のアップデートだけでも大規模なコード修正と慎重な全体検証が必要なのに、そこにテストの修正まで同時に乗るのは負荷が大きく、他のメンバーが開発した機能とのコンフリクトも大きくなってしまいます。
そもそも、本来であれば「Nuxt をアップデートしてもテストが落ちないから安心」と言いたいのに、「Nuxt をアップデートするためにテストの大量修正が必要」という状態では、テストが全く安心材料になりません。しかも、これは今後のアップデートのたびに直面することが目に見えています。
もし import 文がファイルに明示されていれば、Nuxt ランタイムを介さずとも、ユニットテストは Vitest 単体で実行できます。useState や useAsyncData の挙動が大きく変わりでもしない限り、テストがフレームワークのバージョンアップの影響を受けることはなくなります。
テストとプロダクトコードの依存関係を切り離して、個別にアップデート可能な状態を保つためには、自動インポートの無効化が最善だと考えるに至りました。
AI コーディングによる開発体験の変化
もう１つの大きな理由は、昨今の AI によるコーディング支援との相性です。
Nuxt 3 の自動インポートは TypeScript による型定義の恩恵を受けられるので、人間が手でコードを書くだけなら非常に快適な機能です。
しかし、GitHub Copilot や Cursor といった AI にとっては、ファイル内に記述された import 文によってどのライブラリのどの関数を呼び出しているかが明示されていることは、そのコードの依存関係を理解するためのヒントになります。
もちろん、MCP や Skills などを活用することで代替できる部分もありますが、ファイルという最小単位のコンテキストの中に情報が閉じている方が精度は高くなるでしょう。
コーディング AI が日に日に進化していく中で、この長期的なメリットは、オートインポートをやめる強力な後押しとなりました。
移行のハードルを乗り越えるアイデア
方針は決まったものの、「数百ファイルで使われている関数をそれぞれ特定し、適切な import 文を挿入する」という作業を手動で進めるのは現実的ではありません。スクリプトで一括処理しようにも、例外パターンが多く、非常に複雑なロジックが必要になることが想像されました。
かといって、AI に丸投げするにも修正箇所が多すぎて、レビューの品質を担保できません。
どのように進めるべきか頭を悩ませていた際、ヒントをくれたのが他のチームのフロントエンドメンバーでした。
ANDPAD では毎週、チームの垣根を超えてフロントエンドエンジニアが集まって最近の話題や悩みについてざっくばらんに話し合う会が開かれています。
そこで出たのが、「一旦、自動インポート対象の関数をすべて機械的にインポート文として追加してしまって、その後に eslint-plugin-unused-imports を走らせて余計なものを削る」というアイデアでした。
Nuxt が自動インポートしている対象は .nuxt/imports.d.ts や .nuxt/components.d.ts に全て定義されているので、これを利用して「とにかく全部のファイルを対象に、可能性のある import 文を一度すべて挿入する」だけなら、シンプルなロジックで書くことができます。
そこから使われていないものを既存のツール（ESLint）で削除すれば、安全かつ確実に移行できます。このアイデアによって、自動インポートの無効化というタスクが一気に現実的になりました。
大規模移行のために AI に「ツール」を作らせた
今回の移行作業では、AI に直接コードを書き換えさせるのではなく、AI と対話しながら「書き換えスクリプト」を共作するアプローチを採用しました。
数千箇所に及ぶ大規模な修正を AI に直接行わせると、修正内容がブラックボックス化しやすく、レビューコストも膨大になります。
そこで、AI に修正そのものを任せるのではなく、まず「一括挿入＋自動削除」を実現する codemod のプロトタイプを AI に作らせました。その後、それを実際に手元で走らせ、見つかった課題をその都度フィードバックして修正させる、というサイクルをひたすら繰り返しました。
一例としては、「既に import 文が書かれているファイルに追加すると、 import 文の重複が発生して自動削除されない」という問題が見つかったので、「まず重複する import 文は先に削除しておいて追加する」という分岐を入れたように、少しずつスクリプトを改善していきました。
こうして完成した書き換えスクリプトを通して修正することで、修正作業に再現性が生まれ、レビュー時に意図しない修正が混入するリスクを抑えられます。
さらに、他のメンバーが開発した最新機能をプロジェクトにマージする際にも、スクリプトを再実行するだけで即座に最新状態へ追随できる、という大きなメリットをもたらしました。
この結果、数百ファイル以上に及ぶ修正でありながら、他のメンバーが開発した新規機能と同時に、かつ短期間でリリースできました。
選択肢がある柔軟さが Nuxt の強み
私は元々、リリース直後の Nuxt 3 に初めて触れた際に、「自動インポートでも完璧に型が付く」という魔法のような開発体験に感動し、それを積極的に"布教"してきた側の人間でした。
そのため、今回の意思決定には「自分がこれまで Nuxt の良さとして語ってきたポイントを、自ら否定することにならないか？」という迷いを感じていました。
しかし、今回の移行を経て気づいたのは、「Progressive Framework」を謳う Vue や Nuxt の真の強みは、直感的で魔法のような開発体験を提供しながらも、必要に応じてその魔法を使わない選択肢を提供しているところにある、ということです。
Nuxt の自動インポートは今でも優れた機能だと思っていますし、私も個人開発では積極的に活用し続けています。
プロジェクトが大規模化し、多くのユーザーを抱える今のプロダクトフェーズにおいては、テストと実コードを疎結合にできることのメリットが開発中の利便性を上回っただけで、どちらかが常に優れているわけではありません。
また、AIコーディングの普及という、数年前には想像もできなかった潮流の変化もありました。今は「人間にとっての書きやすさ」よりも「AIにとってのコンテキスト量」が重要視される時代なので、明示的インポートを選択することは極めて合理的ですが、数年後にはまた別の技術によって自動インポートが再評価される未来があるかもしれません。
重要なのは、Nuxt が特定の開発スタイルや先進的な技術をユーザーに押し付けるのではなく、柔軟なオプションを提供しているからこそ、この選択ができた、という点です。
オートインポートを簡単に無効化できるように、時代の変化やプロダクトの特性に応じて最適な形を選択できる懐の広さこそが Nuxt の真価であり、今回の選択は Nuxt の良さを否定するものではなく、むしろその強みを最大限に活かした結果だと捉えています。
おわりに
AI コーディングを活用することで、運用中の大規模プロジェクトであっても、明示的インポートへの切り替えは驚くほど安全かつスムーズに行えます。もし今、依存関係の複雑化やアップデートの沼にハマっている方がいれば、有効な解決策の１つとしてぜひ検討してみてください。
そして、最速で立ち上げたプロダクトを、後から堅牢な構成へとシームレスに移行できる柔軟性は、Nuxt の大きなメリットです。「Nuxt プロジェクトは大規模化すると破綻しやすいのではないか」という不安を感じている方にとっても、この記事が安心材料になれば幸いです。
今回の意思決定を実現するアイデアが、チームの垣根を超えたざっくばらんな相談の場から生まれたように、アンドパッドでは、こうした技術的な議論を楽しみながら、共にプロダクトを成長させていく仲間を募集しています。
アンドパッドでのフロントエンド開発に興味を持った方は、ぜひカジュアル面談などお気軽にご応募ください！
