[Nuxt3] 플러그인

Nuxt 3 플러그인은 애플리케이션 전역에서 재사용할 수 있는 기능을 제공하는 모듈입니다. 주요 용도는 다음과 같습니다:

• API 클라이언트와 같은 전역 유틸리티 제공
• 전역 상태 관리 (Pinia)
• 인증 및 권한 관리
• 글로벌 컴포넌트 및 디렉티브 등록
• Vue 및 서드파티 라이브러리(i18n, axios 등) 초기화
• 서버 사이드 렌더링(SSR)과 클라이언트 환경에서 코드 분기

 플러그인 사용 시 주의사항

• 플러그인을 로드한다는 것은 defineNuxtPlugin() 함수의 매개변수(함수)를 실행한다는 것입니다.
• 전역으로 제공하는 Helper는 신중히 선택하고, composables로 기능을 분리하는 것을 우선적으로 고려하세요.
• SSR 환경에서는 브라우저 전용 객체(window, document) 사용 시 반드시 클라이언트 모드로 분기 처리해야 합니다.
• 플러그인이 많을 경우 번들 크기가 커질 수 있으므로 성능 최적화를 고려해야 합니다.

언제, 어떤 플러그인 방식을 사용할까?

사용 목적	추천 방식
전역 상태 관리	Vue 플러그인 (Pinia 등)
API 클라이언트, 인증	Helper 제공 (provide)
Vue 라이브러리 초기화 (i18n 등)	Vue 플러그인 (vueApp.use())
글로벌 디렉티브 추가	Vue 디렉티브 등록 (vueApp.directive)
SSR 환경 분기 처리	mode 옵션 (client/server)

 

플러그인 타입

interface NuxtPlugin {
  src: string
  mode?: 'all' | 'server' | 'client'
  order?: number
}

NuxtPlugin 인터페이스는 src와 선택적인 mode (기본값: 'all'), order 속성을 포함하고 있습니다. mode는 'all', 'server', 'client' 중 하나일 수 있으며, 이를 통해 플러그인이 작동하는 환경을 지정할 수 있습니다. 플러그인 파일에 .client.ts 또는 .server.ts 접미사를 붙이면, 해당 플러그인은 클라이언트나 서버에서만 작동하게 됩니다.

 

플러그인 작성 방법

플러그인은 plugins/ 디렉터리에 정의하며 자동으로 로드됩니다. 플러그인 작성 방법은 다음과 같이 여러 가지가 있습니다.

기본 플러그인 등록

기본적인 형태는 defineNuxtPlugin을 이용하여 정의합니다.

// plugins/simplePlugin.ts
export default defineNuxtPlugin(() => {
  console.log('Nuxt 플러그인 초기화');
});

Helper 함수 제공하기 (provide)

전역적으로 사용할 수 있는 헬퍼를 제공합니다.

⚠️ 주의: 전역적인 네임스페이스 오염을 방지하기 위해 composables을 활용하는 것을 추천합니다.

// plugins/helper.ts
export default defineNuxtPlugin(() => ({
  provide: {
    formatDate: (date: Date) => date.toLocaleDateString('ko-KR')
  }
}));

<script setup lang="ts">
const { $formatDate } = useNuxtApp();
const today = $formatDate(new Date());
</script>

<template>
  <div>{{ today }}</div>
</template>

 

Vue 플러그인 등록 (vueApp.use())

Vue 생태계에서 제공하는 플러그인(i18n, Pinia 등)을 Nuxt 3에 등록할 때 사용합니다.

// plugins/i18n.ts
import { createI18n } from 'vue-i18n';

export default defineNuxtPlugin(({ vueApp }) => {
  const i18n = createI18n({
    legacy: false,
    globalInjection: true,
    locale: 'ko',
    messages: {
      ko: { home: '홈' },
      en: { home: 'Home' }
    }
  });

  vueApp.use(i18n);
});

<template>
  <button>{{ $t('home') }}</button>
</template>

클라이언트/서버 전용 플러그인 (환경 분기)

서버 또는 클라이언트에서만 실행되는 플러그인을 작성할 수 있습니다.

// plugins/clientOnly.ts
export default defineNuxtPlugin({
  mode: 'client',
  setup() {
    console.log('클라이언트 전용 플러그인');
  }
});

// plugins/serverOnly.ts
export default defineNuxtPlugin({
  mode: 'server',
  setup() {
    console.log('서버 전용 플러그인');
  }
});

플러그인 로딩 순서 제어 (pre/post)

플러그인 간 실행 순서를 제어할 때 유용합니다.

// plugins/prePlugin.ts
export default defineNuxtPlugin({
  enforce: 'pre',
  setup() {
    console.log('가장 먼저 실행');
  }
});

// plugins/postPlugin.ts
export default defineNuxtPlugin({
  enforce: 'post',
  setup() {
    console.log('마지막에 실행');
  }
});

글로벌 디렉티브 등록

전역 디렉티브를 쉽게 추가할 수 있습니다.

// plugins/directive.ts
export default defineNuxtPlugin(({ vueApp }) => {
  vueApp.directive('focus', {
    mounted(el: HTMLElement) {
      el.focus();
    }
  });
});

<template>
  <input v-focus />
</template>