Modules

모듈 호환성

Nuxt 3에는 @nuxt/kit 자동 래퍼를 사용하는 Nuxt 2 모듈용 기본 하위 호환 레이어가 있습니다. 하지만 일반적으로 모듈을 Nuxt 3와 호환되게 만들기 위해 따라야 할 단계들이 있으며, 경우에 따라 버전 간 호환성을 위해 Nuxt Bridge를 사용하는 것이 필요합니다.

@nuxt/kit을 사용해 Nuxt 3 준비가 된 모듈을 작성하기 위한 전용 가이드를 준비해 두었습니다. 현재로서는 이 가이드를 따라 모듈을 다시 작성하는 것이 가장 좋은 마이그레이션 경로입니다. 이 가이드의 나머지 부분은 전체 재작성은 피하면서도 모듈을 Nuxt 3와 호환되게 만들고 싶을 때 필요한 준비 단계를 포함합니다.

플러그인 호환성

Nuxt 3 플러그인은 Nuxt 2와 완전한 하위 호환성을 가지지 않습니다.

Vue 호환성

Composition API를 사용하는 플러그인이나 컴포넌트는 Vue 2 또는 Vue 3 중 하나만을 단독으로 지원해야 합니다.

vue-demi를 사용하면 Nuxt 2와 3 모두와 호환되도록 만들 수 있습니다.

모듈 마이그레이션

Nuxt 3 사용자가 모듈을 추가할 때, 더 이상 모듈 컨테이너(this.*)에 접근할 수 없으므로 컨테이너 기능에 접근하기 위해 @nuxt/kit의 유틸리티를 사용해야 합니다.

@nuxt/bridge로 테스트

@nuxt/bridge로 마이그레이션하는 것은 Nuxt 3를 지원하기 위한 첫 번째이자 가장 중요한 단계입니다.

모듈에 픽스처나 예제가 있다면, 해당 설정에 @nuxt/bridge 패키지를 추가하세요(예시는 여기 참고).

CommonJS에서 ESM으로 마이그레이션

Nuxt 3는 TypeScript와 ECMAScript Modules를 네이티브로 지원합니다. 더 많은 정보와 업그레이드 방법은 Native ES Modules를 확인하세요.

플러그인의 기본 내보내기 보장

export default가 없는 Nuxt 플러그인(예: 전역 Vue 플러그인)을 주입하는 경우, 마지막에 export default () => { }를 추가했는지 확인하세요.

// ~/plugins/vuelidate.js
import Vue from 'vue'
import Vuelidate from 'vuelidate'

Vue.use(Vuelidate)

// ~/plugins/vuelidate.js
import Vue from 'vue'
import Vuelidate from 'vuelidate'

Vue.use(Vuelidate)

export default () => { }

런타임 모듈 피하기

Nuxt 3에서는 Nuxt가 이제 빌드 타임 전용 의존성이 되었기 때문에, 모듈이 Nuxt 런타임에 훅을 걸려고 해서는 안 됩니다.

모듈은 buildModules에만 추가되더라도(modules 대신) 동작해야 합니다. 예를 들어:

• Nuxt 모듈 안에서 process.env를 수정하고 Nuxt 플러그인에서 이를 읽는 방식은 피하고, 대신 runtimeConfig를 사용하세요.
• (*) 프로덕션 환경에서 vue-renderer:*와 같은 런타임 훅에 의존하는 것을 피하세요.
• (*) 모듈 안에서 직접 임포트하여 serverMiddleware를 추가하는 것을 피하세요. 대신 파일 경로를 참조하는 방식으로 추가하여 모듈의 컨텍스트와 독립적으로 동작하도록 하세요.

(*) nuxt dev 용도로만 사용하고 if (nuxt.options.dev) { }로 가드하는 경우는 예외입니다.

TypeScript 사용 (선택 사항)

필수는 아니지만, Nuxt 생태계 대부분이 TypeScript를 사용하는 방향으로 이동하고 있으므로 마이그레이션을 고려하는 것이 매우 권장됩니다.