gil
5f664546cf
- CLAUDE.md 운영 규칙 - wiki/ 정리된 지식 페이지 (Nuxt + Claude Code) - raw/ 원본 자료 - reference/ Nuxt 4.x 공식 문서 Co-authored-by: Cursor <cursoragent@cursor.com>
134 lines
3.3 KiB
Markdown
134 lines
3.3 KiB
Markdown
# 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`
|