자동 임포트(Auto-imports)

자동 임포트(Auto-imports)

Nuxt는 컴포넌트, 컴포저블, 헬퍼 함수, 그리고 Vue.js API를 명시적으로 import하지 않아도 앱 전체에서 쓸 수 있게 자동으로 임포트해줘요. 전역 선언과 달리 타입과 IDE 완성 힌트를 보존하고, 프로덕션 코드에서 실제로 사용하는 것만 포함해요. 이 동작을 구성하는 방법을 정리할게요.

출처: https://nuxt.com/docs/4.x/guide/concepts/auto-imports

기본 동작

Nuxt는 의견이 정해진 디렉토리 구조 덕분에 app/components/, app/composables/, app/utils/ 안의 파일을 자동 임포트해요. 예를 들어 app/app.vue에서 ref를 import 없이 바로 쓸 수 있어요.

<script setup lang="ts">
const count = ref(1) // ref 는 자동으로 임포트됨
</script>

server 디렉토리에서는 server/utils/에서 export된 함수와 변수를 자동 임포트해요. 커스텀 폴더나 서드파티 패키지에서 export된 함수를 임포트하려면 nuxt.config의 imports 섹션을 설정하면 돼요.

내장 자동 임포트

Nuxt는 데이터 fetching을 수행하고, 앱 컨텍스트·런타임 설정에 접근하며, 상태를 관리하는 함수와 컴포저블을 자동 임포트해요. 예를 들어 useFetch()는 import 없이 쓸 수 있어요.

/* useFetch() 는 자동 임포트됨 */
const { data, refresh, status } = await useFetch('/api/hello')

Vue의 반응형 API인 ref, computed와 라이프사이클 훅·헬퍼도 Nuxt가 자동 임포트해요.

Vue·Nuxt 컴포저블 컨텍스트

내장 Composition API 컴포저블 중 상당수는 올바른 컨텍스트에서 호출돼야 해요. Vue는 컴포넌트 라이프사이클 동안 현재 컴포넌트의 임시 인스턴스(그리고 Nuxt는 nuxtApp의 임시 인스턴스)를 전역 변수로 추적했다가 같은 틱에 해제해요. 이는 서버 렌더링에서 요청 간 상태 오염을 피하는 데 필수적이에요.

그래서 (극히 일부 예외를 빼고) 이런 컴포저블은 Nuxt 플러그인, Nuxt 라우트 미들웨어, 또는 Vue setup 함수 밖에서는 쓸 수 없어요. 게다가 동기적으로 호출해야 하는데, <script setup> 블록이나 defineNuxtComponent로 선언된 setup, defineNuxtPlugin, defineNuxtRouteMiddleware 안에서는 await 후에도 동기 컨텍스트를 유지하는 변환을 수행하므로 예외적으로 허용돼요.

Nuxt instance is unavailable 같은 오류가 나면, Nuxt 컴포저블을 Vue·Nuxt 라이프사이클에서 잘못된 위치에 호출했다는 뜻일 가능성이 커요.

디렉토리 기반 자동 임포트

정의된 디렉토리에서 파일을 직접 자동 임포트해요.

  • app/components/ → Vue 컴포넌트
  • app/composables/ → Vue 컴포저블
  • app/utils/ → 헬퍼 함수와 기타 유틸리티

컴포넌트 <template>에서 자동 임포트된 ref와 computed는 unwrap되지 않아요. 이는 템플릿 최상위가 아닌 ref를 Vue가 처리하는 방식 때문이에요.

명시적 임포트

Nuxt는 모든 자동 임포트를 #imports 별칭으로 노출하므로, 필요하면 명시적 import를 할 수 있어요.

import { computed, ref } from '#imports'

자동 임포트 비활성화

컴포저블과 유틸리티의 자동 임포트를 끄려면 imports.autoImport를 false로 설정해요. 그래도 #imports에서 명시적 임포트는 가능해요.

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

부분 비활성화

ref 같은 프레임워크 함수는 자동 임포트를 유지하고 우리 코드(커스텀 컴포저블)만 끄려면 imports.scan을 false로 설정해요. 이때 커스텀 컴포저블은 파일에서 직접 import해야 해요. 다만 레이어 구성에서는 각 레이어의 컴포저블을 명시적으로 import해야 하고, 레이어 시스템의 오버라이드 기능이 깨지는 부작용이 있으니 주의하세요.

자동 임포트된 컴포넌트

Nuxt는 ~/components 디렉토리의 컴포넌트도 자동 임포트해요. 이건 컴포저블·유틸리티 자동 임포트와는 별개로 구성돼요. 비활성화하려면 components.dirs를 빈 배열로 설정해요(모듈이 추가한 컴포넌트에는 영향 없음).

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

써드파티 패키지 자동 임포트

Nuxt는 서드파티 패키지에서도 자동 임포트를 지원해요. 해당 패키지의 Nuxt 모듈을 쓰면 이미 자동 임포트가 설정돼 있을 가능성이 높아요. 예를 들어 vue-i18n 패키지에서 useI18n 컴포저블을 자동 임포트하도록 설정할 수 있어요.

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

더 알아보기