いきなりVue+Nuxtプロジェクトに入った人のための手引
こんにちは、フロントエンド開発をしている人です。
バグ修正や保守対応などプロジェクトの進展に伴い、サーバーサイドで別の言語を書いていたメンバーを迎え入れることがしばしばあります。その際に説明している内容がだいたいいつも同じになるので、汎用的な内容としてドキュメントにまとめました。チームリーダーが必ずしも親切とは限らないので、この手引書があなたのこれからのフロントエンド開発に役立てば幸いです。
まえおき
あなたが入ったプロジェクトは、以下の条件をだいたい満たしているとします。
- Gitでチーム開発をしている
- すでに実装がある程度進んでいる
- コードのレビュワー（メンター、チューター）がいる
- メンバーとすぐにコミュニケーションできる状況にある
- 環境構築やコーディング規約、開発指針についてはすでにドキュメント化されている
いきなりVue+Nuxtプロジェクトに入るという状況は、開発フェーズに伴ってフロント側の人手が足りなくなったり、サーバー側の手が空いてきたりといった状況だと思われるので、以上のような条件を満たしていると思います。
したがって、以下のような内容については説明しません。
- VueおよびNuxtプロジェクトの新規作成
- PugやTypeScriptの導入
- HTMLやCSSなどの設計規則
- デザインパターンにもとづくコンポーネント分割
- lodashなど、議論のあるライブラリについての利用の是非
以上に挙げた事柄は、コーディング規約や実装それ自体によってある程度すでに固まっているものと想像します。なので基本的にはそれらを眺めて、実際の開発状況に合わせてもらうほかないと思います。新規開発なら色々と工夫する余地がありますが、今のあなたの状況としては「郷に入っては郷に従え」です。
もっとも、HTMLやCSS、JavaScriptの知識に加えて、Vueの基本的な動き方については知っておくと便利です。前者は MDN Web Docs をはじめとするリファレンスを都度参照してもらうこととして、後者については Vue公式のガイド に目を通しておくと見通しが良くなります。あとは必要に応じて検索結果から APIリファレンス などのページを参照するとよいでしょう。
環境構築
JavaScriptの開発環境として、以下のツールを導入しましょう。
- Node.js
- Yarn
Node.jsはJavaScriptの実行環境です。Pythonプログラムは python main.py といったコマンドで実行しますが、この python に当たります。JavaScriptプログラムそれ自体はブラウザ上でネイティブに動作するのですが、JavaScript開発環境はモジュールバンドラーなどの仕組みを用いてこれらのコードを生成するので、PCやサーバー上でそれらを動作させるために必要です。
（2021/2/25追記 Node.jsはバージョン（n系などと呼称されます）によって期待する動作をしない場合があります。Node.jsは標準でインストールされていることもありますが、これによる問題を避けるためにNode.jsのバージョン管理ツールをまず導入することをおすすめします。代表的なものに n やnodenv、nodebrew などがあります。）
YarnはJavaScriptのパッケージ管理ツールです。Pythonにおけるpipとかcondaにあたるやつですね。Node.jsにも標準でnpm（Node Package Manager）というのがついていますが、 色々と使い勝手が悪い ので、一般的にはYarnが採用されていることが多いです。 git clone してきたディレクトリに移動し、 yarn install で環境構築します。
エディタ
AWS Cloud9などのクラウドベースIDEを利用していない限り、 Visual Studio Code（以下VS Code）の利用を強く推奨します。 その理由として、JavaScriptおよびVueの開発に最適化されていること、またそのための拡張機能が充実していること、ターミナル起動やデバッグなども完結する統合開発環境（IDE）であること、実際にフロントエンド開発者の中で現在最も多く利用されていること（※体感）などを挙げます（あと教える側が他のエディタだとショートカットコマンド分からなくて困るという問題もあります…）。
その上で、Vue+Nuxt開発で入れておくと便利な拡張機能を紹介します。
VeturはVue用のシンタックスハイライトやコード補完などをしてくれます。これがあるとVueの構造が視覚的にわかるようになります。
ESLintとPrettierはそれぞれリンターとフォーマッターです。保存するたびにこれらが走り、コードをいい感じに整形してくれたりします。両者はしばしば競合しますが、開発中のプロジェクトではおそらくそうならないよう設定済みだと思います。
GitLensはコードの行単位でのコミット履歴を表示してくれます。バグ修正などでスクリプトの編集経緯を追うのに便利です。
Visual Studio IntelliCodeは2019年から提供が開始されたものですが、開発者が編集しているコードの文脈とパターンを用いて、入力中の変数や関数をAIがサジェストしてくれるという優れものです。
それから以下に、視覚的な助けになる拡張機能を紹介します。
Indent Rainbowはインデントを、Brackert Pair Colorizerはカッコをそれぞれ階層ごとに色分けしてくれます。構造を追いやすくなりますし、ネストを減らそうという気持ちにもなります。
Material Iconsはサイドバーのアイコンをより親しみやすいものに置き換えます。個人的には元のも嫌いではないんですが、こちらが好きという人が多いです。
拡張機能
Chromeをお使いなら、Vue用のDevToolsはマストです。各コンポーネントが持っている情報がリアルタイムで把握・操作できます。
ディレクトリ構造
Vue+Nuxtプロジェクトのディレクトリ構造は、まずJavaScriptのパッケージ開発に一般的なものと、Nuxt特有のものとに分けられます。それぞれについて重要なものを解説します。
パッケージ一般
- package.json
- jsconfig.json/tsconfig.json
- nuxt.config.json
- yarn.lock
- src/
package.json はJavaScriptパッケージの核となるファイルであり、この情報をもとにNodeおよびnpm（Yarn）はパッケージをPCやサーバーにインストールします。
jsconfig.jsonにはこれをコンパイルするための設定などがJSON形式で書かれています。
そのほか、hoge.config.json といった形でフレームワーク等の設定が置かれていることがあります。NuxtJSにおいては nuxt.config.json に当たります。
yarn.lock はYarnでパッケージを管理する上でライブラリ同士の依存情報を保存しておくために生成されるファイルです。したがって編集対象ではないのですが、.gitignore に指定されていないとライブラリを加えるたびに差分が出てきて目につくかもしれません。
以上のファイルは基本的に開発初期で設定が終わっているので、プロジェクトに入った段階で触ることはあまりないと思います。主に編集することになるファイルは src/ ディレクトリ以下に入っています。
Nuxt特有
以下、src/ ディレクトリの中でNuxtJSプロジェクトにおける主要なディレクトリを挙げます。
- pages/
- components/
- layouts/
- store/
- plugins/
- assets/
- interfaces/
pages/ に各画面ごとのページファイルが置かれています。自動ルーティングがそのまま採用されているなら、ディレクトリ構造はそのままURLのパスを反映しているはずです。アンダースコアで始まる名前 _id のファイルおよびディレクトリは、そこがパラメータになることを表しています。NuxtJSにおいては this.$route.params.id といった形で参照されます。
components/ にはコンポーネントとして切り出されたファイルが置かれています。これらがページファイルでインポートして使われます。
layouts/ にはレイアウトファイルが置かれています。default.vue の他にも存在する場合は、画面によってレイアウトの使い分けがあるかもしれません。これらはページファイルの layout オプションで指定されます。
store/ には Vuex の状態やアクションを定義するファイルが置かれています。 this.$store.getter('fileName/getterName') といった形でアクセスできます。
plugins/ にはライブラリをプラグインとして利用するための設定が置かれています。新たにプラグインを追加する場合、ここに定義ファイルを追加する必要があるかもしれません。
assets/ には画像やアイコンなどのコンテンツが置かれています。 require('~/assets/...') と利用することが多いです。
interfaces/ はTypeScriptを導入したプロジェクトに存在するディレクトリです。APIとの疎通などに利用されるインターフェース定義ファイルが置かれています。
その他のディレクトリについては、公式ドキュメント を参照するといいでしょう。
あとがき
以下はプロジェクトに入る人に気をつけてほしいというより、引き継ぎの際に「今までこうしておけばよかった、レビューの時に気をつけておけばよかった…」と感じる反省です。
- 変数名や関数名は略しすぎず、要点を得た命名をしよう
- コンポーネントだけでなく、よく使う定数も constants/ などに切り出そう
- 仕様を知らない人がコードを読んでも理解できるよう、コードには引き継ぎを想定したコメントを残そう
- その場しのぎの修正を続けていくとコードがめちゃくちゃになる。根本的なリファクタリングも検討しよう
入ったプロジェクトによっては、上に挙げたような事柄でかなり苦しめられることもあります（そうしたコードから生まれてくるバグを直すため、あなたがそこに投入されたのかもしれません…）。その時は今回のプロジェクトを反面教師としつつ、よりよいコードの書き方を学んでください。そうすれば次にあなたが新しいプロジェクトを担当したとき、やがてそれを引き継ぐことになる人が苦労しなくて済むようになるでしょう。ともかくも、新しい言語やフレームワークを習得できる機会を喜んで受け入れましょう… Happy Coding!
Discussion