# 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/` | 서버 라우트에서만 |

```vue
<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" 에러 발생.

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

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

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

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

---

## 명시적 임포트

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

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

---

## 자동 임포트 설정

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

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

### 자동 임포트 전체 비활성화

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

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

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

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

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

---

## 자동 임포트와 TypeScript

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

---

## 참고 / 출처

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