.nuxtrc ファイルとは？〜Nuxt 設定をもっとシンプルに〜

Nuxt プロジェクトの設定は通常 nuxt.config ファイルで行いますが、設定が複雑になると管理が煩雑になることがあります。そんなときに役立つのが .nuxtrc ファイルです。

.nuxtrc はフラットな構文で Nuxt の設定を記述できるファイルで、設定の見通しを良くしつつ、手軽に設定を切り替えたり追加したりできます。特に複数のプロジェクトで共通設定を使いたい場合や、簡単な設定変更を素早く行いたい場合に便利です。

本記事では、.nuxtrc の基本的な使い方から実務での活用例、注意すべきポイントまで丁寧に解説します。

まず結論：.nuxtrc のポイントまとめ

• .nuxtrc はフラットなキー＝値形式で Nuxt の設定を記述できるファイル
• nuxt.config よりもシンプルで、設定の上書きや追加が手軽にできる
• プロジェクト単位だけでなく、ホームディレクトリにグローバル設定ファイルを置くことも可能
• nuxt.config の設定が最優先で、.nuxtrc はその下位互換的な位置づけ
• 複雑な設定や関数を使う場合は nuxt.config を使うべき

いつ使うべき？ 使わない方がよいケースは？

使うべきケース

• シンプルな設定変更を素早く行いたいとき
  例えば SSR の有効・無効切り替えやモジュールの追加など、単純なキーと値の設定を手軽に管理したい場合。

• 複数プロジェクトで共通設定を共有したいとき
  ホームディレクトリにグローバル .nuxtrc を置くことで、すべての Nuxt プロジェクトに共通のデフォルト設定を適用可能。

• 設定の上書きや環境ごとの微調整を分かりやすく管理したいとき
  例えば CI/CD 環境やローカル環境で異なる設定を簡単に切り替えたい場合。

使わない方がよいケース

• 複雑なロジックや関数を含む設定が必要な場合
  .nuxtrc はフラットな構文なので、動的な設定や関数を使いたい場合は nuxt.config を使うべきです。

• プラグインの詳細設定やカスタムビルド設定など高度な設定が必要な場合
  これらは .nuxtrc では対応できません。

実務でよくあるユースケースとサンプルコード

1. SSR の有効・無効切り替え

開発中は SSR を無効にして高速なホットリロードを実現し、本番では SSR を有効にするケース。

# .nuxtrc
ssr=false

本番環境用の .nuxtrc では ssr=true に切り替えるだけで設定変更が完了します。

2. モジュールの追加・管理

画像最適化やセキュリティ強化のためにモジュールを追加したい場合。

# .nuxtrc
modules[]=@nuxt/image
modules[]=nuxt-security

modules[] のように配列形式で複数モジュールを簡単に指定できます。

3. 開発ツールの有効化

開発時のみ DevTools を有効にする設定。

# .nuxtrc
devtools.enabled=true

環境ごとに .nuxtrc を切り替えることで、開発環境と本番環境の設定を分けられます。

よくある落とし穴・注意点

1. 設定の優先順位に注意

.nuxtrc の設定は nuxt.config の設定に上書きされます。つまり、nuxt.config に同じキーがある場合はそちらが優先されるため、.nuxtrc の設定が反映されないことがあります。

2. フラットな構文の制約

.nuxtrc はキー＝値のフラットな構文なので、ネストしたオブジェクトや関数、動的な設定はできません。複雑な設定は nuxt.config に任せましょう。

3. SSR と CSR の切り替え時の挙動

SSR を .nuxtrc で切り替える場合、ビルドやキャッシュの影響で意図した通りに反映されないことがあります。設定変更後は必ずビルドをやり直し、キャッシュをクリアして動作確認を行いましょう。

4. パフォーマンスへの影響

.nuxtrc 自体は設定ファイルなのでパフォーマンスに直接影響しませんが、設定内容（例：SSR 無効化やモジュール追加）がアプリのパフォーマンスに影響を与えるため、設定の意味を理解して使うことが重要です。

まとめ

.nuxtrc ファイルは、Nuxt の設定をシンプルかつフラットな形式で管理できる便利なツールです。特に複数プロジェクトで共通設定を使いたい場合や、単純な設定変更を素早く行いたい場合に役立ちます。

ただし、複雑な設定や動的なロジックが必要な場合は nuxt.config を使うべきであり、両者の役割を理解して使い分けることが大切です。

適切に使えば、開発効率の向上や設定管理の簡素化に大きく貢献するでしょう。

参考情報

• .nuxtrc は unjs/rc9 に基づく設定ファイル形式です。
• 詳細な Nuxt 設定オプションは公式ドキュメントの nuxt.config を参照してください。

# 例：グローバル .nuxtrc の設置場所

# macOS/Linux
~/.nuxtrc

# Windows
C:\Users\{username}\.nuxtrc

このグローバルファイルを使うと、すべての Nuxt プロジェクトに共通のデフォルト設定を適用できます。プロジェクト単位の .nuxtrc や nuxt.config が優先されるため、環境に応じて柔軟に設定を切り替えられます。