gil-wiki/wiki/nuxt-auto-imports.md

Nuxt 자동 임포트

카테고리: 핵심 개념 최종 수정: 2026-05-13 관련: nuxt-lifecycle, nuxt-routing

요약

Nuxt는 app/components/, app/composables/, app/utils/, Vue API(ref, computed 등), Nuxt 내장 composable을 자동 임포트한다. 프로덕션 빌드에는 실제로 사용된 것만 포함됨.

---

자동 임포트 대상

종류	디렉토리	예시
Vue 컴포넌트	app/components/	<MyButton />
Vue composable	app/composables/	useMyComposable()
유틸 함수	app/utils/	formatDate()
Vue API	(내장)	ref, computed, watch
Nuxt composable	(내장)	useFetch, useState, useRoute
서버 유틸	server/utils/	서버 라우트에서만

<script setup lang="ts">
// 모두 임포트 없이 사용 가능
const count = ref(1)                    // Vue API
const double = computed(() => count.value * 2)  // Vue API
const { data } = await useFetch('/api/data')    // Nuxt composable
const myData = useMyComposable()                // app/composables/ 내 파일
</script>

---

주의사항: 컨텍스트 제약

Nuxt composable은 올바른 컨텍스트에서 호출해야 함. Nuxt 플러그인, 라우트 미들웨어, Vue setup() 함수 외부에서 호출 시 "Nuxt instance is unavailable" 에러 발생.

// ❌ 잘못된 패턴 — composable 파일 루트 스코프
const config = useRuntimeConfig()  // 에러!

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

// ✅ 올바른 패턴 — 함수 안에서 호출
export const useMyComposable = () => {
  const config = useRuntimeConfig()  // 올바른 컨텍스트
  // ...
}

또한 await 이후에 composable을 호출하면 컨텍스트를 잃을 수 있음 (<script setup>, defineNuxtPlugin, defineNuxtRouteMiddleware 내부는 예외).

---

명시적 임포트

자동 임포트를 명시적으로 쓰고 싶을 때 #imports 별칭 사용:

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

---

자동 임포트 설정

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

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

자동 임포트 전체 비활성화

export default defineNuxtConfig({
  imports: {
    autoImport: false,  // #imports로 명시적 임포트는 여전히 가능
  },
})

커스텀 코드만 비활성화 (프레임워크 API는 유지)

export default defineNuxtConfig({
  imports: {
    scan: false,  // ref, computed 등은 자동 임포트 유지
    // 단, 레이어 시스템의 오버라이드 기능이 깨질 수 있음
  },
})

컴포넌트 자동 임포트 비활성화

export default defineNuxtConfig({
  components: {
    dirs: [],  // app/components/ 비활성화 (모듈이 추가한 컴포넌트는 유지)
  },
})

---

자동 임포트와 TypeScript

Nuxt가 자동 임포트 타입 선언 파일(.nuxt/imports.d.ts)을 자동 생성. IDE 자동완성과 타입 체킹이 동작함.

---

참고 / 출처

• reference/3.guide/1.concepts/3.auto-imports.md