【Nuxt】メンテナビリティ向上。import文の相対パス統一

メンテナビリティ向上。import文の相対パス統一はじめまして！5月からCCIで内定者アルバイトを始めたshunshunです。来年の入社までのアルバイトなので、今は新卒0年目といったところでしょうか。早く一人前のエンジニアとしてCARTAの力になれるよう日々努力中です。

さて、人生で初めて技術系の記事を書くのですがそれが会社のテックブログとあって緊張しています。ご笑覧いただければ幸いです。

はじめに

今私はNuxt.jsで作られた社内サービスのNuxt2→Nuxt3のバージョンアップを担当しています。そのプロジェクトの中でコードを眺めていた時に、インポートするモジュールのパスの書き方が揃っていないことに気づきました。

import { hogeModule } from "~/utils/hoge"
import { fugaModule } from "@/utils/fuga"
import { varModule } from "../utils/var"

これには以下のような問題があります。

一貫性の欠如により、モジュールのインポートエラーが発生した際パスの書き方に起因するのかそうでないのかを判断するのに時間がかかる
新しく参加したメンバーがどのような書き方で書けば良いかわからなく困ってしまう

そこで、バージョンアップで大きく書き換えるついでに統一したいということで何か方針を考えようとなりました。それが本記事を書くに至った出発点です。

この記事では、パスの書き方がバラバラなNuxt.jsのプロジェクトにおいてどのように書き方を揃えていくかを考えた顛末を書いていきます。

結論

このプロジェクトではパスの書き方は相対パスを基本として書いて行くことを決めました。とはいえ、これがNuxtにおけるベストプラクティスかと言われるとそうだとは言い切れません。以下では自分のプロジェクトがなぜ相対パスを採用するに至ったかについて書こうと思います。

まず、公式はどう言っているの？

大抵の場合、公式がお勧めする手法があるならばそれに従うのが吉です。ところがNuxt3のドキュメントではパスの書き方に言及する記述やサンプルコードは見つけられませんでした。(2023/06/19時点)

ただNuxt2のドキュメントにはエイリアスについて以下のような記述がありました。

We recommend using the ~ as an alias. @ is still supported but will not work in all cases such as with background images in your css.

つまりNuxt2的には~の利用を推奨しているようです。ただ、Nuxt3のドキュメントには同様の記述を見つけられなかったため、特に今は何も推奨していないのでしょう。

社内の詳しい人に聞いてみよう

CARTA内には#frontend-knowledge-centerというslackチャンネルがあるのでそこで質問することにしました。

すると以下のような回答が返ってきました。

基本は相対パス、特別なものだけalias設定して絶対importが基本方針になるはず
絶対パスでのimportはtsconfigやバンドラの設定が必要になるので濫用すべきでなはない
- 年単位で見た時にビルド周りの移行で面倒が起きるリスクがある

また、相対パスのデメリットである記述が長くなってしまうというデメリットについては

今時importを人間が書くことないであろう
ファイル移動時もIDEが勝手に修正してくれる

という点から大きな問題にはならないとのアドバイスをいただきました。ご回答いただいた皆様、ありがとうございました。

なら、相対パスでいいじゃない

このアドバイスを受けて私たちは相対パスを基本方針にすることを決めました。相対パスによって../../が長く続いてしまうという問題は、上であげたのもそうですが、コードベースのあまり大きくない今回のプロダクトではあまり大きな問題になりません。その反対にバンドラなどへの依存を少なくできるため、ビルドツールなどが変更になっても影響を抑えることができるでしょう。

これは大きな機能追加は予定されず、修正とバージョンアップ対応を行なって行くことがメインの今回のプロダクトにとって大きなメリットになると考えました。こうして、私たちは相対パスに統一して行くことにしたのです。

対応方針

以上を踏まえて、自分たちの対応方針を説明します。

まず、importの記述はプロジェクトの至る所で使われるものなので、かなり大きな変更になります。そのため、全てのパスの記述を一気に相対パスに統一するというコミットを作るのはかなりリスキーです。

そこで開発時にファイルを触ったとき、その変更にパスの変更を忍ばせるという形で徐々に統一していきました。今回はNuxt2→Nuxt3という大きな改修中で、ほとんど全てのファイルを触ることになっていたのでそのついでに行うことで少しずつ検証しながらパスを統一できました。

最後に

今回の修正を通してESLintなどで絶対パスを強制するようなルールもある中、相対パスのメリットについて考えられたのが良かったです。また、それについて考えたことでどんなメリデメがあるかなどを考えることができ、勉強になりました。

また、このようなパスの修正をすることができたのはバージョンアップによる大規模なコードの変更を行う最中であったというのが大きかったように思います。というのも今回のような変更は全体に影響を及ぼす割に、プロダクトの成長にはあまり寄与しない部分だからです。場合によっては今回の問題は既存コードには手を加えないということもあり得たでしょう。このプロダクトの成長に寄与するかという観点は、先輩に指摘されて初めて考慮した部分でした。

こうした観点でコードを見つめることができたのも、内定者アルバイトを始めて良かったと感じました。