brand logo

ドキュメント

Version 33.17Version 44.10

自動インポート

Nuxtはコンポーネント、コンポーザブル、ヘルパー関数、Vue APIを自動インポートします。

Nuxtは、コンポーネント、コンポーザブル、およびVue.js APIをアプリケーション全体で明示的にインポートすることなく使用できるように自動インポートします。

app.vue
const count = ref(1) // refは自動インポートされます

Nuxtは、その意見に基づいたディレクトリ構造のおかげで、components/、composables/、およびutils/を自動インポートできます。

従来のグローバル宣言とは異なり、Nuxtは型情報、IDEの補完とヒントを保持し、本番コードで使用されるものだけを含めます。

ドキュメントでは、明示的にインポートされていないすべての関数はNuxtによって自動インポートされ、コード内でそのまま使用できます。自動インポートされたコンポーネント、コンポーザブル、ユーティリティのリファレンスはAPIセクションで見つけることができます。

serverディレクトリでは、Nuxtはserver/utils/からエクスポートされた関数と変数を自動インポートします。

カスタムフォルダやサードパーティパッケージからエクスポートされた関数を自動インポートするには、nuxt.configファイルのimportsセクションを設定することができます。

ビルトイン自動インポート

Nuxtは、データフェッチを実行し、アプリケーションコンテキストやランタイム設定にアクセスし、状態を管理したり、コンポーネントやプラグインを定義するための関数やコンポーザブルを自動インポートします。

/* useFetch()は自動インポートされます */
const { data, refresh, status } = await useFetch('/api/hello')

VueはrefやcomputedのようなリアクティビティAPIを公開しており、ライフサイクルフックやヘルパーもNuxtによって自動インポートされます。

/* ref()とcomputed()は自動インポートされます */
const count = ref(1)
const double = computed(() => count.value * 2)

VueとNuxtのコンポーザブル

VueとNuxtが提供するビルトインのComposition APIコンポーザブルを使用する際、多くのものが正しい_コンテキスト_で呼び出されることに依存していることに注意してください。

コンポーネントのライフサイクル中、Vueは現在のコンポーネントの一時インスタンスをグローバル変数を通じて追跡し、同様にNuxtはnuxtAppの一時インスタンスを追跡し、同じティックでそれを解除します。これは、サーバーレンダリング時に、クロスリクエストの状態汚染（2人のユーザー間で共有参照が漏れること）を避け、異なるコンポーネント間の漏れを避けるために重要です。

つまり、（非常に少数の例外を除いて）Nuxtプラグイン、Nuxtルートミドルウェア、またはVueセットアップ関数の外でそれらを使用することはできません。さらに、それらを同期的に使用する必要があります。つまり、<script>ブロック内、defineNuxtComponentで宣言されたコンポーネントのセットアップ関数内、defineNuxtPluginまたはdefineNuxtRouteMiddleware内を除いて、コンポーザブルを呼び出す前にawaitを使用することはできません。これらの場所では、awaitの後でも同期コンテキストを保持するための変換を行います。

Nuxt instance is unavailableのようなエラーメッセージが表示された場合、それはおそらくVueまたはNuxtのライフサイクルの間違った場所でNuxtコンポーザブルを呼び出していることを意味します。

非SFCコンポーネント内でNuxtコンテキストを必要とするコンポーザブルを使用する場合、defineComponentの代わりにdefineNuxtComponentでコンポーネントをラップする必要があります。

こちらも参照 guide > going-further > experimental-features#asynccontext こちらも参照 github.com > nuxt > nuxt > issues > 14269

壊れるコードの例:

composables/example.ts
// コンポーザブルの外でランタイム設定にアクセスしようとしています
const config = useRuntimeConfig()

export const useMyComposable = () => {
  // ここでランタイム設定にアクセス
}

動作するコードの例:

composables/example.ts
export const useMyComposable = () => {
  // ライフサイクルの正しい場所でコンポーザブルが呼び出されるため、
  // useRuntimeConfigはここで動作します
  const config = useRuntimeConfig()

  // ...
}

ディレクトリベースの自動インポート

Nuxtは定義されたディレクトリに作成されたファイルを直接自動インポートします：

サンプルコードの編集とプレビューexamples > features > auto-imports

自動インポートされたrefとcomputedはコンポーネントの<template>でアンラップされません。 :br これは、Vueがテンプレートのトップレベルでないrefをどのように扱うかによるものです。詳細はVueのドキュメントで読むことができます。

明示的なインポート

Nuxtは、必要に応じてインポートを明示的にするために使用できる#importsエイリアスで、すべての自動インポートを公開します：

import { ref, computed } from '#imports'

const count = ref(1)
const double = computed(() => count.value * 2)

自動インポートの無効化

コンポーザブルやユーティリティの自動インポートを無効にしたい場合は、nuxt.configファイルでimports.autoImportをfalseに設定できます。

nuxt.config.ts
export default defineNuxtConfig({
  imports: {
    autoImport: false
  }
})

これにより自動インポートは完全に無効になりますが、#importsからの明示的なインポートを使用することは依然として可能です。

自動インポートの部分的な無効化

refのようなフレームワーク固有の関数を自動インポートのままにしておきたいが、自分のコード（例：カスタムコンポーザブル）の自動インポートを無効にしたい場合は、nuxt.config.tsファイルでimports.scanオプションをfalseに設定できます：

export default defineNuxtConfig({
  imports: {
    scan: false
  }
})

この設定では：

  • ref、computed、watchのようなフレームワーク関数は、手動でインポートする必要なく動作します。
  • カスタムコード、例えばコンポーザブルは、ファイル内で手動でインポートする必要があります。

注意: この設定にはいくつかの制限があります：

  • プロジェクトをレイヤーで構成する場合、各レイヤーからコンポーザブルを明示的にインポートする必要があり、自動インポートに依存することはできません。
  • この設定はレイヤーシステムのオーバーライド機能を破壊します。imports.scan: falseを使用する場合、この副作用を理解し、アーキテクチャを適切に調整してください。

自動インポートされたコンポーネント

Nuxtは、~/componentsディレクトリからコンポーネントを自動的にインポートしますが、これはコンポーザブルやユーティリティ関数の自動インポートとは別に設定されています。

こちらも参照 guide > directory-structure > components

自分の~/componentsディレクトリからのコンポーネントの自動インポートを無効にするには、components.dirsを空の配列に設定できます（ただし、モジュールによって追加されたコンポーネントには影響しません）。

nuxt.config.ts
export default defineNuxtConfig({
  components: {
    dirs: []
  }
})

サードパーティパッケージからの自動インポート

Nuxtはサードパーティパッケージからの自動インポートも可能です。

そのパッケージのNuxtモジュールを使用している場合、モジュールがそのパッケージの自動インポートをすでに設定している可能性があります。

例えば、vue-i18nパッケージからuseI18nコンポーザブルの自動インポートを有効にするには、次のようにします：

nuxt.config.ts
export default defineNuxtConfig({
  imports: {
    presets: [
      {
        from: 'vue-i18n',
        imports: ['useI18n']
      }
    ]
  }
})

tips

このセクションは公式ドキュメントの翻訳ではなく、本サイト独自の補足記事です。

Nuxtの自動インポート機能とは？〜開発効率化の強力な味方〜

Nuxtは、Vueコンポーネントやコンポーザブル、ユーティリティ関数、さらにはVueのリアクティビティAPIまでを自動的にインポートしてくれる機能を備えています。これにより、毎回明示的にimport文を書く手間が省け、コードがすっきりするだけでなく、IDEの補完や型推論も損なわれません。

この機能は、特に大規模なプロジェクトや複数人での開発において、コードの可読性と保守性を高めるうえで非常に役立ちます。さらに、Nuxtは実際に使用されているものだけを本番コードに含めるため、不要なコードがバンドルに混入することも防げます。

まず結論：Nuxtの自動インポートのポイント

  • 明示的なimport不要：refやcomputed、useFetchなどのVue/NuxtのAPIを直接使える
  • 型情報とIDE補完を保持：自動インポートでも型推論や補完が効くため開発が快適
  • ディレクトリ構造に依存：components/、composables/、utils/など特定フォルダのファイルを自動認識
  • サードパーティパッケージも対応可能：設定次第で外部ライブラリの関数も自動インポート可能
  • 必要に応じて無効化や部分的無効化も可能：柔軟に設定を切り替えられる

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

使うべきケース

  • 開発効率を優先したいとき
    明示的なimport文を省略できるため、コードがシンプルになり、開発速度が向上します。

  • 共通的に使うAPIやコンポーネントが多い場合
    例えばrefやuseFetchなど頻繁に使うものは自動インポートに任せると便利です。

  • 型安全性を保ちつつコードを簡潔にしたい場合
    自動インポートは型情報を保持するため、IDEの補完や型チェックが効きます。

  • サードパーティのコンポーザブルを多用する場合
    Nuxtの設定で自動インポートを拡張すれば、外部ライブラリの関数も手軽に使えます。

使わない方がよいケース

  • 明示的な依存関係を明確にしたい場合
    大規模チームで依存関係をコード上で明示的に管理したいときは、自動インポートを避けることもあります。

  • パフォーマンスやバンドルサイズを厳密に管理したい場合
    自動インポートは不要なコードを除外しますが、設定ミスで意図しないコードが含まれる可能性もあるため注意が必要です。

  • レイヤードアーキテクチャで明示的なインポートが求められる場合
    imports.scan: false設定時は自動インポートが制限されるため、手動インポートが必要です。

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

1. VueのリアクティビティAPIをシンプルに使う

const count = ref(0)
const doubled = computed(() => count.value * 2)

refやcomputedを明示的にimportしなくても使えるため、コードがすっきりします。

2. APIデータフェッチを簡単に実装

const { data, refresh } = await useFetch('/api/items')

useFetchも自動インポートされるため、API呼び出しが簡単に書けます。

3. カスタムコンポーザブルの自動インポート

composables/useUser.tsを作成すると、以下のようにimport不要で使えます。

export const useUser = () => {
  const user = ref(null)
  // ユーザー情報取得ロジックなど
  return { user }
}

const { user } = useUser()

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

1. コンポーザブルの呼び出しタイミングに注意

NuxtのコンポーザブルはVueのライフサイクルやNuxtのコンテキスト内で同期的に呼び出す必要があります。例えば、コンポーザブルをモジュールのトップレベルで呼ぶとNuxt instance is unavailableエラーが発生します。

// NG例
const config = useRuntimeConfig() // トップレベルで呼ぶとエラーになる

export const useMyComposable = () => {
  // ...
}

// OK例
export const useMyComposable = () => {
  const config = useRuntimeConfig() // 関数内で呼ぶのが正しい
  // ...
}

2. 自動インポートされたrefやcomputedはテンプレートでアンラップされない

Vueの仕様により、<template>内で自動インポートされたrefは自動的に値が展開されません。テンプレートで使う場合は.valueを明示的に書くか、setup内で展開して渡す必要があります。

3. 自動インポートの無効化や部分的無効化の副作用

nuxt.config.tsでimports.autoImportやimports.scanを無効化すると、自動インポートが使えなくなります。特にimports.scan: falseはレイヤー構成のオーバーライド機能を破壊するため、プロジェクト構成に注意が必要です。

4. サードパーティパッケージの自動インポート設定忘れ

外部ライブラリの関数を自動インポートしたい場合は、nuxt.config.tsのimports.presetsに明示的に設定しないと使えません。設定漏れでエラーになることが多いので注意しましょう。

まとめ

Nuxtの自動インポート機能は、VueやNuxtのAPI、カスタムコンポーザブル、ユーティリティ関数を明示的なimportなしで使える強力な機能です。これによりコードがシンプルになり、開発効率が大幅に向上します。

ただし、呼び出しタイミングや設定の副作用には注意が必要です。特にコンポーザブルは正しいライフサイクル内で同期的に使うこと、設定変更時の影響範囲を理解することが重要です。

実務では、頻繁に使うAPIや共通処理を自動インポートに任せつつ、必要に応じて明示的なimportも併用する柔軟な運用が望まれます。これにより、保守性と開発効率のバランスを保ちながらNuxtの恩恵を最大限に活用できます。

© 2016–PRESENT Nuxt Labs https://nuxt.com

※このページは Nuxt.js 公式ドキュメントの翻訳ページです。

公式ドキュメントの該当ページはこちら：
https://nuxt.com/docs/3.x/guide/concepts/auto-imports