Nuxt.js コーディングガイド 暫定版

内容は仮のものです。随時加筆していきますので気になる点などあればコメントお願いします。

コンポーネントについて

Nuxt.js では様々な場面で Vue コンポーネントが利用されます。Vue コンポーネントは Vue.js の主要な構成要素である一方で、非常に多機能で様々な振る舞いをする要素です。

一言で コンポーネントと言っても様々な捉え方が可能であるため、まずはこの用語を整理しておきましょう。

pages フォルダに配置された.vueファイルは、URLと紐づくコンポーネントです。本稿ではこれを ページコンポーネント と呼称します。

layouts フォルダに配置された.vueファイルは、ページコンポーネントのベースレイアウトを定義するコンポーネントです。本稿ではこれを レイアウトコンポーネント と呼称します。

components フォルダに配置された.vueファイルは、ページコンポーネントやレイアウトコンポーネントから参照されるDOM部品としての役割を果たすコンポーネントです。本稿ではこれを単に、 コンポーネント と呼称したり、特に 再利用可能なコンポーネント と表現したりします。

再利用可能なコンポーネントのうち、特定のページで使われることのみを意図して作られるものを 本稿では ページのサブコンポーネント と呼称し、特に利用されるページを限定しないものを、UIコンポーネント と表現します。両者は依存管理の観点から明確に区別されるべきであり、特に UIコンポーネントは StyleGuide などを用いた品質管理、ドキュメント化の実施の検討対象として捉えられるべきです。

最後に、単純に .vue拡張子のコンポーネント全てを指す場合、本稿では Vueコンポーネント、または .vueファイルという表現を用います。

ページコンポーネントについて

pages フォルダには、 URL と紐づく ページコンポーネントを配置します。

全てのページコンポーネントは 原則 index.vue というファイル名で作成し、URL表現はディレクトリ名のみを用いて表現すべきです。

例外的に ルートのネスト機能を利用する際にのみ、index.vue 以外のファイル名を用いることを許容します。これにより どのvueファイルがページの本体で、どの ルートでネストされたルートが用いられているのかひと目で把握する事ができるようになります。

pages フォルダには ページコンポーネントの他に、ページのサブコンポーネントを配置することも出来ます。この場合、利用されるページコンポーネントと同じフォルダ階層に兄弟要素として配置し、ルート化の対象となることを避けるためのファイル名プレフィックス - を付ける必要があります。

ページコンポーネントは、各ページごとに個別のJSファイルとして出力されるため、内容の重複には気にを付ける必要があります。特に、多くのコンポーネント内で同じような記述をしている場合には、共通化する手法を検討しましょう。

多くのページコンポーネントで同じような import 宣言を行っている場合、nuxt.config.jsvendor.build セクションの設定で、グローバルに出力する事を検討しましょう。

多くのページコンポーネントで同じような CSS 記述や CSS 実体のimportを行っている場合、グローバルなCSSの導入を検討しましょう。

結論として、pages フォルダ内の全てのファイルは、 以下のimport 宣言を実施すべきではありません。

  • ../ から始まる import 宣言
  • ~/pages から始まる import 宣言
  • 他の多くのページコンポーネントと共通する import 宣言

再利用可能なコンポーネントについて

components フォルダには、ページやレイアウトから参照可能な様々な .vueファイルを配置する事が出来ます。

ここでのフォルダ構成は複雑になりやすいため、トップレベルで依存関係に基づくフォルダ切り分けを実施しておくのが良いでしょう。

最低限、 ui pages と言ったディレクトリを componenents フォルダ直下に配置し、UIコンポーネントと ページのサブコンポーネントを区別する工夫は行われるべきです。

Vuex の利用について

Vuex は Vueのデータ管理を行うモジュールです。

Vuex はグローバルなステートとしてVue アプリケーション全域に依存をばらまくため、依存の管理が非常に重要になります。

幸い、Vuex には モジュールと呼ばれる機能が存在するため、コレを利用してVuexの依存範囲を管理することが出来ます。Vuex の依存範囲探索には 以下の手法が考えられるでしょう。

  • Vuex モジュールの名前空間を利用した文字列探索
  • Vuex モジュールの名前空間、アクション名を定数化して import 利用
  • Vuex モジュール利用のためのmixinを提供して import 利用

Vuex モジュール依存範囲の探索は、原則 pages ディレクトリ内で収まるように設計するのが好ましいでしょう。多くの場合 components ディレクトリに位置するVueコンポーネントが Vuex を参照しなければならないケースは少ないはずです。

- 接頭辞を利用した、ページのサブコンポーネントを pages フォルダに配置する管理手法は、Vuex の依存探索の対象を拡大するため、大規模な開発場面では控えたほうが良いでしょう。

Vuex を参照するページのサブコンポーネントのみ - 付きで pages ディレクトリ内に配置し、それ以外のページのサブコンポーネントは全て components ディレクトリに配置する、といった運用方法も考えられます。

Vuex モジュールも、アプリケーション全体で利用される事を想定したものと、特定のページ群内でのみ利用されることを想定したものとに別れるでしょう。store ディレクトリに global pages などのフォルダ階層を用意して、依存範囲を明示的に示すのは管理上良い手段です。

なおアプリケーション構成によっては layout でVuex モジュールを利用するケースも多々あります。 pages ディレクトリ同様 layout ディレクトリも Vuex モジュールの依存探索対象となるのは許容されるべきケースです。

CSS の構築について

原則、FLOCSSの形式を取ります。

https://github.com/hiloki/flocss

CSS のフォルダ構成は以下の形を参考にしてください。

assets/scss
├── foundation  # 全体で共通となる項目
│   └── base.scss
├── layout  # layout コンポーネントから import されるべきもの
├── mixins
├── object
│   ├── component # 非ページのコンポーネントからimport されるべきもの 
│   ├── project   # ページコンポーネントからimport されるべきもの
│   ├── utility   # 必要に応じてimport されるヘルパー類
│   └── common.scss
├── mixins.scss    # 各種 コンポーネントがimport すべきグローバル mixin たち
├── variable.scss
└── app.scss # グローバルに取り込むべきCSSの宣言

CSSの利用は Vueコンポーネント内での scoped によるコンポーネント固有のCSS記述の利用を妨げるものではありません。

寧ろCSS の利用は、 再利用されるセレクタ を対象にした最低限のものに制限されるべきです。
再利用されるセレクタは、他のセレクタと区別できるよう適切な接頭辞を用意すべきでしょう。

一方で 再利用されるセレクタを、 scoped のないVueコンポーネントのスタイルで記述する事は管理上好ましくありません。再利用されるセレクタは、少なくとも将来的には適切なSCSSのスタイルガイドツール等を用いて適切に管理されるべきです。

scopedを用いて Vueコンポーネント内の閉じたスタイルを記述する上でもスタイルの共通化は行われるべきです。
Vueコンポーネント間で共通のスタイルを用いる場合、セレクタの再利用よりもまず mixin などを用いた共通化を検討してください。
mixin による共通化は依存の管理が簡便な一方で、CSS 記述の重複を生み出します。
多くの画面で同じようなCSSが出力される事が想定される場合、セレクタの再利用を検討するのが良いでしょう。

CSS の宣言(mixinやvariableではないセレクタ付き定義) をグローバルにすべきか否かは、以下の観点で設計します。

グローバルにすべきもの

各ページ・コンポーネントでの頻出定義はグローバルにすべきです。 ➔ グローバルにすることで各ページのJSサイズが削減されます。

グローバルにすべきでないもの

各ページ固有のCSS表現はグローバルにすべきではありません。

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です