Nuxt는 app/plugins/ 디렉터리의 파일을 자동으로 읽고 Vue 애플리케이션이 생성될 때 로드합니다.
nuxt.config에 따로 추가할 필요가 없습니다..server 또는 .client 접미사를 사용하여 플러그인을 서버 또는 클라이언트 측에서만 로드할 수 있습니다.디렉터리의 최상위에 있는 파일(또는 하위 디렉터리 내의 index 파일)만 플러그인으로 자동 등록됩니다.
-| plugins/
---| foo.ts // scanned
---| bar/
-----| baz.ts // not scanned
-----| foz.vue // not scanned
-----| index.ts // currently scanned but deprecated
foo.ts와 bar/index.ts만 등록됩니다.
하위 디렉터리에 있는 플러그인을 추가하려면, nuxt.config.ts의 app/plugins 옵션을 사용할 수 있습니다:
export default defineNuxtConfig({
plugins: [
'~/plugins/bar/baz',
'~/plugins/bar/foz',
],
})
플러그인에 전달되는 유일한 인자는 nuxtApp입니다.
export default defineNuxtPlugin((nuxtApp) => {
// nuxtApp으로 무언가를 수행
})
더 고급 사용 사례를 위해 객체 문법을 사용하여 플러그인을 정의하는 것도 가능합니다. 예를 들어:
export default defineNuxtPlugin({
name: 'my-plugin',
enforce: 'pre', // 또는 'post'
async setup (nuxtApp) {
// 이것은 일반 함수형 플러그인과 동일합니다
},
hooks: {
// 여기에서 Nuxt 앱 런타임 훅을 직접 등록할 수 있습니다
'app:created' () {
const nuxtApp = useNuxtApp()
// 훅에서 무언가를 수행
},
},
env: {
// 서버 전용 또는 아일랜드 컴포넌트를 렌더링할 때 플러그인이 실행되지 않도록 하려면 이 값을 `false`로 설정하세요.
islands: true,
},
})
enforce: import.meta.server ? 'pre' : 'post'와 같이 설정하면 Nuxt가 플러그인에 대해 수행할 수 있는 향후 최적화를 무력화하게 됩니다.
Nuxt는 객체 문법을 사용할 때 모든 훅 리스너를 정적으로 사전 로드하므로, 플러그인 등록 순서를 걱정하지 않고도 훅을 정의할 수 있습니다.파일 이름에 '알파벳' 번호 접두사를 붙여 플러그인이 등록되는 순서를 제어할 수 있습니다.
plugins/
| - 01.myPlugin.ts
| - 02.myOtherPlugin.ts
이 예시에서 02.myOtherPlugin.ts는 01.myPlugin.ts에 의해 주입된 모든 것에 접근할 수 있습니다.
이는 한 플러그인이 다른 플러그인에 의존하는 상황에서 유용합니다.
10.myPlugin.ts는 2.myOtherPlugin.ts보다 먼저 옵니다. 이 때문에 예시에서는 한 자리 숫자 앞에 0을 붙입니다.기본적으로 Nuxt는 플러그인을 순차적으로 로드합니다. 플러그인을 parallel로 정의하면 Nuxt는 다음 플러그인을 로드하기 전에 해당 플러그인의 실행이 끝날 때까지 기다리지 않습니다.
export default defineNuxtPlugin({
name: 'my-plugin',
parallel: true,
async setup (nuxtApp) {
// 다음 플러그인은 즉시 실행됩니다
},
})
플러그인이 실행되기 전에 다른 플러그인을 기다려야 하는 경우, dependsOn 배열에 해당 플러그인의 이름을 추가할 수 있습니다.
export default defineNuxtPlugin({
name: 'depends-on-my-plugin',
dependsOn: ['my-plugin'],
async setup (nuxtApp) {
// 이 플러그인은 실행되기 전에 `my-plugin`의 실행이 끝날 때까지 기다립니다
},
})
Nuxt 플러그인 내에서 composables와 utils를 사용할 수 있습니다:
export default defineNuxtPlugin((nuxtApp) => {
const foo = useFoo()
})
하지만 몇 가지 제한 사항과 차이점이 있다는 점을 기억하세요:
nuxtApp 인스턴스에만 바인딩됩니다.NuxtApp 인스턴스에 헬퍼를 제공하고 싶다면, 플러그인에서 provide 키 아래에 반환하면 됩니다.
export default defineNuxtPlugin(() => {
return {
provide: {
hello: (msg: string) => `Hello ${msg}!`,
},
}
})
export default defineNuxtPlugin({
name: 'hello',
setup () {
return {
provide: {
hello: (msg: string) => `Hello ${msg}!`,
},
}
},
})
그런 다음 컴포넌트에서 이 헬퍼를 사용할 수 있습니다:
<script setup lang="ts">
// 또는 여기에서 사용할 수도 있습니다
const { $hello } = useNuxtApp()
</script>
<template>
<div>
{{ $hello('world') }}
</div>
</template>
composables를 사용할 것을 강력히 권장합니다.ref 또는 computed를 제공하는 경우, 컴포넌트 <template>에서 언래핑되지 않습니다.플러그인에서 헬퍼를 반환하면 자동으로 타입이 지정되며, useNuxtApp()의 반환값과 템플릿 내에서 타입 정보를 확인할 수 있습니다.
useNuxtApp()을 호출하여 타입이 지정된 버전을 가져올 수 있습니다. 하지만 일반적으로 플러그인의 순서를 확실히 알고 있는 경우가 아니라면 이는 피하는 것이 좋습니다.고급 사용 사례의 경우, 주입된 속성의 타입을 다음과 같이 선언할 수 있습니다:
declare module '#app' {
interface NuxtApp {
$hello (msg: string): string
}
}
declare module 'vue' {
interface ComponentCustomProperties {
$hello (msg: string): string
}
}
export {}
vue-gtag처럼 Google Analytics 태그를 추가하기 위한 Vue 플러그인을 사용하려면, Nuxt 플러그인을 통해 이를 사용할 수 있습니다.
먼저 Vue 플러그인 의존성을 설치합니다:
npm install --save-dev vue-gtag-next
yarn add --dev vue-gtag-next
pnpm add -D vue-gtag-next
bun add -D vue-gtag-next
그런 다음 플러그인 파일을 생성합니다:
import VueGtag, { trackRouter } from 'vue-gtag-next'
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.use(VueGtag, {
property: {
id: 'GA_MEASUREMENT_ID',
},
})
trackRouter(useRouter())
})
마찬가지로, 플러그인에서 커스텀 Vue 디렉티브를 등록할 수 있습니다.
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.directive('focus', {
mounted (el) {
el.focus()
},
getSSRProps (binding, vnode) {
// 여기에서 SSR 전용 props를 제공할 수 있습니다
return {}
},
})
})
~/plugins/my-directive.client.ts로 옮기고 서버용으로는 ~/plugins/my-directive.server.ts에 'stub' 디렉티브를 제공할 수 있습니다.