Автоимпорты

Nuxt автоматически импортирует компоненты, композаблы, хелперы и API Vue.

Nuxt автоматически импортирует компоненты, композаблы и API Vue.js по всему приложению — импортировать их вручную не нужно.

app/app.vue
<script setup lang="ts">
const count = ref(1) // ref импортируется автоматически
</script>

Благодаря заданной структуре директорий Nuxt может автоимпортировать содержимое app/components/, app/composables/ и app/utils/.

В отличие от глобального объявления, Nuxt сохраняет типы, подсказки и автодополнение в IDE и включает в продакшен-код только то, что реально используется.

В документации каждая функция, которая не импортируется явно, автоимпортируется Nuxt и может использоваться как есть. Справка по автоимпортируемым компонентам, композаблам и утилитам — в разделе API.
В директории server Nuxt автоимпортирует экспортируемые функции и переменные из server/utils/.
Автоимпорт из своих папок или сторонних пакетов можно настроить в секции imports файла nuxt.config.

Встроенные автоимпорты

Nuxt автоимпортирует функции и композаблы для получения данных, доступа к контексту приложения и runtime-конфигу, управления состоянием, объявления компонентов и плагинов.

<script setup lang="ts">
/* useFetch() автоимпортируется */
const { data, refresh, status } = await useFetch('/api/hello')
</script>

Vue предоставляет API реактивности (ref, computed), хуки жизненного цикла и хелперы — они тоже автоимпортируются Nuxt.

<script setup lang="ts">
/* ref() и computed() автоимпортируются */
const count = ref(1)
const double = computed(() => count.value * 2)
</script>

Композаблы Vue и Nuxt

При использовании встроенных композаблов Vue и Nuxt важно вызывать их в правильном контексте.

В жизненном цикле компонента Vue отслеживает текущий экземпляр через глобальную переменную и сбрасывает её в том же тике. Аналогично Nuxt отслеживает временный экземпляр nuxtApp. Это нужно для SSR: чтобы не «протекало» состояние между запросами разных пользователей и между разными компонентами.

Поэтому (за редкими исключениями) композаблы нельзя вызывать вне Nuxt-плагина, Nuxt route middleware или функции setup компонента Vue. Кроме того, вызывать их нужно синхронно — нельзя использовать await перед вызовом композабла, кроме блоков <script setup>, функции setup компонента с defineNuxtComponent, defineNuxtPlugin и defineNuxtRouteMiddleware, где контекст сохраняется после await.

Если появляется ошибка вроде Nuxt instance is unavailable, скорее всего композабл Nuxt вызывается не в том месте жизненного цикла.

Если композабл требует контекст Nuxt внутри компонента не-SFC, оберните компонент в defineNuxtComponent вместо defineComponent.
Экспериментальная возможность asyncContext позволяет использовать композаблы Nuxt в асинхронных функциях.
Подробное объяснение в комментарии на GitHub.

Пример некорректного кода:

composables/example.ts
// попытка доступа к runtime config вне композабла
const config = useRuntimeConfig()

export const useMyComposable = () => {
  // использование config здесь
}

Пример корректного кода:

composables/example.ts
export const useMyComposable = () => {
  // композабл вызывается в нужном месте жизненного цикла,
  // useRuntimeConfig здесь работает
  const config = useRuntimeConfig()

  // ...
}

Автоимпорты по директориям

Nuxt автоимпортирует файлы из заданных директорий:

Прочитайте и отредактируйте живой пример в Docs > 4 X > Examples > Features > Auto Imports.
Автоимпортированные ref и computed не разворачиваются в <template> компонента.
Это связано с тем, как Vue обрабатывает ref'ы не верхнего уровня в шаблоне. Подробнее — в документации Vue.

Явный импорт

Nuxt предоставляет алиас #imports для всех автоимпортов — при необходимости импорт можно сделать явным:

<script setup lang="ts">
import { computed, ref } from '#imports'

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

Отключение автоимпортов

Чтобы отключить автоимпорт композаблов и утилит, в 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, хотя эта настройка отдельна от автоимпорта композаблов и утилит.

Узнать больше Docs > 4 X > Directory Structure > App > Components.

Чтобы отключить автоимпорт компонентов из своей ~/components, задайте components.dirs пустым массивом (это не затронет компоненты, добавленные модулями):

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

Автоимпорт из сторонних пакетов

Nuxt позволяет автоимпортировать из сторонних пакетов.

Если у пакета есть Nuxt-модуль, скорее всего он уже настроил автоимпорты для этого пакета.

Например, автоимпорт композабла useI18n из vue-i18n можно включить так:

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