자동 임포트와 composable

Nuxt 코드에는 import 문이 유난히 적습니다. ref, useFetch, 직접 만든 컴포넌트까지 import 없이 바로 쓰이기 때문입니다. 비밀은 자동 임포트 에 있습니다. 이번 레슨에서는 자동 임포트 규칙과 직접 만드는 컴포저블, 그리고 useNuxtApp·플러그인을 살펴봅니다.

학습 목표

• 어떤 것들이 자동으로 임포트되는지 규칙을 안다.
• composables/ 에 나만의 컴포저블을 만든다.
• 자동 임포트되는 유틸 함수를 작성한다.
• useNuxtApp 과 플러그인의 역할을 이해한다.

자동 임포트되는 것들

Nuxt는 약속된 폴더의 내용을 빌드 시 스캔해 전역에서 쓸 수 있게 합니다.

대상 폴더	자동 임포트되는 것
components/	컴포넌트(템플릿에서 태그로)
composables/	export한 함수·변수
utils/	export한 헬퍼 함수
(Vue)	ref, computed, watch 등
(Nuxt)	useFetch, useState, navigateTo 등

<script setup>
// import 한 줄도 없지만 모두 동작한다
const count = ref(0);
const { data } = await useFetch('/api/tasks');
</script>

<template>
  <!-- components/TaskCard.vue 가 태그로 자동 등록됨 -->
  <TaskCard v-for="t in data" :key="t.id" :task="t" />
</template>

💡 TIP — 컴포넌트가 하위 폴더에 있으면 이름이 합쳐집니다. components/task/Card.vue → <TaskCard>.

composables 직접 만들기

composables/ 폴더에 함수를 두면 자동 임포트됩니다. 컨벤션상 이름은 use 로 시작합니다.

// composables/useTasks.ts
export function useTasks() {
  const { data, pending, refresh } = useFetch('/api/tasks');

  const completed = computed(
    () => (data.value ?? []).filter((t) => t.done),
  );

  return { tasks: data, pending, completed, refresh };
}

<script setup>
const { tasks, completed, pending } = useTasks();
</script>

파일당 default export

파일 하나가 컴포저블 하나라면 default 로 내보내도 됩니다. 이때는 파일 이름 이 함수 이름이 됩니다.

// composables/useNow.ts
export default function () {
  return useState('now', () => new Date().toISOString());
}

⚠️ 주의 — 자동 임포트는 최상위(top-level) composables/ 만 깊이 1단계까지 스캔합니다. 더 깊은 구조가 필요하면 nuxt.config.ts 의 imports.dirs 로 폴더를 추가하세요.

utils 폴더

순수 함수(반응성 없는 헬퍼)는 utils/ 에 두면 마찬가지로 자동 임포트됩니다.

// utils/formatDate.ts
export function formatDate(iso: string) {
  return new Date(iso).toLocaleDateString('ko-KR');
}

<template>
  <time>{{ formatDate(task.createdAt) }}</time>
</template>

useNuxtApp

useNuxtApp() 은 Nuxt 런타임 컨텍스트에 접근하는 통로입니다. 플러그인이 주입한 헬퍼나 런타임 정보를 꺼낼 수 있습니다.

const nuxtApp = useNuxtApp();

// 서버에서 실행 중인지 확인
if (import.meta.server) {
  // ...
}

// 플러그인이 주입한 헬퍼 사용 (아래 플러그인 예시 참고)
const { $hello } = useNuxtApp();
$hello('Nuxt');

플러그인 소개

plugins/ 폴더의 파일은 앱이 시작될 때 한 번 실행됩니다. 외부 라이브러리 초기화나 전역 헬퍼 주입에 씁니다. provide 로 넘긴 값은 $이름 으로 어디서나 쓸 수 있습니다.

// plugins/hello.ts
export default defineNuxtPlugin(() => {
  return {
    provide: {
      hello: (name: string) => console.log(`안녕, ${name}!`),
    },
  };
});

이제 어느 컴포넌트에서나 const { $hello } = useNuxtApp() 로 꺼내 쓸 수 있습니다.

💡 TIP — 파일명을 hello.client.ts 또는 hello.server.ts 로 두면 해당 환경에서만 실행됩니다(예: 브라우저 전용 라이브러리는 .client).

요약

• components/·composables/·utils/ 의 내용과 Vue·Nuxt API는 import 없이 쓰입니다.
• composables/ 에 use* 함수를 만들면 자동 임포트되는 재사용 로직이 됩니다.
• 반응성 없는 순수 헬퍼는 utils/ 에 둡니다.
• useNuxtApp 으로 런타임 컨텍스트와 플러그인 헬퍼에 접근합니다.

연습문제

1. components/TaskCard.vue 를 만들고 import 없이 페이지에서 태그로 써보세요.
2. composables/useTasks.ts 를 만들어 일감 패칭과 완료 개수 계산을 한 곳에 모아 보세요.
3. utils/formatDate.ts 를 만들어 날짜를 한국어 형식으로 표시해 보세요.
4. plugins/hello.ts 로 $hello 헬퍼를 주입하고 useNuxtApp() 으로 호출해 보세요.

힌트 — use* 는 composables/, 순수 함수는 utils/, 전역 주입은 plugins/ + provide 입니다.