자동 임포트

Nuxt는 컴포넌트, 컴포저블, 그리고 Vue.js API를 애플리케이션 전반에서 명시적으로 임포트하지 않고도 사용할 수 있도록 자동으로 임포트합니다.

<script setup lang="ts">
const count = ref(1) // ref는 자동 임포트됩니다
</script>

Nuxt는 의견이 반영된 디렉토리 구조 덕분에 components/, composables/, utils/ 디렉토리의 파일을 자동으로 임포트할 수 있습니다.

기존의 전역 선언과 달리, Nuxt는 타입, IDE 자동완성 및 힌트를 보존하며, 프로덕션 코드에서 사용되는 것만 포함합니다.

내장 자동 임포트

Nuxt는 데이터 패칭, 앱 컨텍스트 및 런타임 설정 접근, 상태 관리, 컴포넌트 및 플러그인 정의를 위한 함수와 컴포저블을 자동 임포트합니다.

<script setup lang="ts">
/* useFetch()는 자동 임포트됩니다 */
const { data, refresh, status } = await useFetch('/api/hello')
</script>

Vue는 ref나 computed와 같은 반응성 API, 라이프사이클 훅, 헬퍼를 노출하며, 이들 역시 Nuxt에 의해 자동 임포트됩니다.

<script setup lang="ts">
/* ref()와 computed()는 자동 임포트됩니다 */
const count = ref(1)
const double = computed(() => count.value * 2)
</script>

Vue 및 Nuxt 컴포저블

Vue와 Nuxt에서 제공하는 내장 Composition API 컴포저블을 사용할 때, 이들 중 다수가 올바른 _컨텍스트_에서 호출되어야 한다는 점을 유의하세요.

컴포넌트 라이프사이클 동안, Vue는 현재 컴포넌트의 임시 인스턴스(그리고 유사하게 Nuxt는 nuxtApp의 임시 인스턴스)를 전역 변수로 추적한 뒤, 같은 틱에서 이를 해제합니다. 이는 서버 렌더링 시 두 요청 간의 상태 오염(두 사용자 간에 공유 참조가 누출되는 것)과 서로 다른 컴포넌트 간의 누출을 방지하기 위해 필수적입니다.

즉, (아주 드문 예외를 제외하고) Nuxt 플러그인, Nuxt 라우트 미들웨어, Vue setup 함수 외부에서는 이들을 사용할 수 없습니다. 또한, 동기적으로 사용해야 하며, <script setup> 블록, defineNuxtComponent로 선언된 컴포넌트의 setup 함수, defineNuxtPlugin, defineNuxtRouteMiddleware 내에서는 await 이후에도 동기 컨텍스트를 유지하도록 변환이 이루어지므로 예외적으로 사용할 수 있습니다.

Nuxt instance is unavailable과 같은 에러 메시지가 발생한다면, Vue 또는 Nuxt 라이프사이클에서 잘못된 위치에서 Nuxt 컴포저블을 호출했기 때문일 가능성이 높습니다.

잘못된 코드 예시:

// 컴포저블 외부에서 런타임 설정에 접근하려고 시도
const config = useRuntimeConfig()

export const useMyComposable = () => {
  // 여기서 런타임 설정에 접근
}

정상 동작하는 코드 예시:

export const useMyComposable = () => {
  // 컴포저블이 라이프사이클의 올바른 위치에서 호출되므로,
  // useRuntimeConfig가 여기서 동작합니다
  const config = useRuntimeConfig()

  // ...
}

디렉토리 기반 자동 임포트

Nuxt는 정의된 디렉토리에 생성된 파일을 직접 자동 임포트합니다:

• Vue 컴포넌트를 위한 components/
• Vue 컴포저블를 위한 composables/
• 헬퍼 함수 및 기타 유틸리티를 위한 utils/

명시적 임포트

Nuxt는 모든 자동 임포트를 #imports 별칭으로 노출하여, 필요하다면 명시적으로 임포트할 수 있습니다:

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

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

자동 임포트 비활성화

컴포저블과 유틸리티의 자동 임포트를 비활성화하려면, nuxt.config 파일에서 imports.autoImport를 false로 설정할 수 있습니다.

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

이렇게 하면 자동 임포트가 완전히 비활성화되지만, 여전히 #imports에서 명시적 임포트를 사용할 수 있습니다.

부분적으로 자동 임포트 비활성화

ref와 같은 프레임워크 전용 함수는 자동 임포트로 남기고, 사용자 정의 코드(예: 커스텀 컴포저블)에 대해서만 자동 임포트를 비활성화하려면, nuxt.config.ts 파일에서 imports.scan 옵션을 false로 설정할 수 있습니다:

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

이 설정을 사용하면:

• ref, computed, watch와 같은 프레임워크 함수는 수동 임포트 없이 계속 동작합니다.
• 커스텀 코드(예: 컴포저블)는 파일에서 직접 임포트해야 합니다.

자동 임포트된 컴포넌트

Nuxt는 ~/components 디렉토리의 컴포넌트도 자동으로 임포트하지만, 이는 컴포저블 및 유틸리티 함수의 자동 임포트와는 별도로 설정됩니다.

자신의 ~/components 디렉토리에서 컴포넌트 자동 임포트를 비활성화하려면, components.dirs를 빈 배열로 설정할 수 있습니다(단, 이 설정은 모듈에서 추가된 컴포넌트에는 영향을 주지 않습니다).

export default defineNuxtConfig({
  components: {
    dirs: []
  }
})

서드파티 패키지에서 자동 임포트

Nuxt는 서드파티 패키지에서도 자동 임포트를 지원합니다.

예를 들어, vue-i18n 패키지의 useI18n 컴포저블을 자동 임포트하려면 다음과 같이 설정할 수 있습니다:

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