새로운 Composition API

Nuxt Bridge는 Nuxt 3와 호환되는 composable들을 구현합니다.

@nuxtjs/composition-api에서 Nuxt 3 호환 API로 마이그레이션하면, Nuxt 3로 이전할 때 재작성해야 할 코드가 줄어듭니다.

ssrRef 및 shallowSsrRef

이 두 함수는 내부적으로 매우 비슷하게 동작하는 새로운 composable인 useState로 대체되었습니다.

주요 차이점은 이 상태에 대해 키(key) 를 제공해야 한다는 점입니다 (ssrRef와 shallowSsrRef에서는 Nuxt가 자동으로 생성해 주었습니다). 그리고 useState는 Nuxt 3 플러그인(defineNuxtPlugin으로 정의됨) 또는 컴포넌트 인스턴스 내에서만 호출할 수 있습니다. (즉, 요청 간 상태 공유 위험 때문에 전역/ambient 컨텍스트에서는 useState를 사용할 수 없습니다.)

- import { ssrRef } from '@nuxtjs/composition-api'

- const ref1 = ssrRef('initialData')
- const ref2 = ssrRef(() => 'factory function')
+ const ref1 = useState('ref1-key', () => 'initialData')
+ const ref2 = useState('ref2-key', () => 'factory function')
  // 상태에 접근
  console.log(ref1.value)

상태가 키로 구분되기 때문에, 동일한 키를 사용하는 한 여러 위치에서 같은 상태에 접근할 수 있습니다.

이 composable을 사용하는 방법에 대해서는 Nuxt 3 문서에서 더 자세히 읽어볼 수 있습니다.

ssrPromise

이 함수는 제거되었으며, 사용 중이었다면 대체 구현을 찾아야 합니다. ssrPromise에 대한 사용 사례가 있다면, 토론을 통해 알려 주세요.

onGlobalSetup

이 함수는 제거되었지만, 그 사용 사례는 defineNuxtPlugin 내부에서 useNuxtApp 또는 useState를 사용하여 충족할 수 있습니다. 또한 레이아웃의 setup() 함수 내에서 원하는 커스텀 코드를 실행할 수도 있습니다.

- import { onGlobalSetup } from '@nuxtjs/composition-api'

- export default () => {
-   onGlobalSetup(() => {
+ export default defineNuxtPlugin((nuxtApp) => {
+   nuxtApp.hook('vue:setup', () => {
      // ...
    })
- }
+ })

useStore

Vuex 스토어 인스턴스에 접근하기 위해서는 useNuxtApp().$store를 사용할 수 있습니다.

- import { useStore } from '@nuxtjs/composition-api`
+ const { $store } = useNuxtApp()

useContext 및 withContext

주입된 헬퍼들에 접근하기 위해서는 useNuxtApp을 사용할 수 있습니다.

- import { useContext } from '@nuxtjs/composition-api`
+ const { $axios } = useNuxtApp()
useNuxtApp()은 nuxt2Context라는 키도 제공하는데, 여기에는 Nuxt 2 컨텍스트에서 일반적으로 접근하던 모든 속성이 포함되어 있습니다. 하지만 이는 Nuxt 3에서는 존재하지 않으므로, 직접 사용하는 것은 권장되지 않습니다. 대신 필요한 것에 접근할 다른 방법이 있는지 확인해 보세요. (없다면 기능 요청이나 토론을 올려 주세요.)

wrapProperty

이 헬퍼 함수는 더 이상 제공되지 않지만, 다음 코드로 대체할 수 있습니다:

import { computed, getCurrentInstance } from 'vue'

const wrapProperty = (property: string, makeComputed = true) => () => {
  const vm = getCurrentInstance().proxy
  return makeComputed ? computed(() => vm[property]) : vm[property]
}

useAsync 및 useFetch

이 두 composable은 useLazyAsyncData와 useLazyFetch로 대체할 수 있으며, 이들은 Nuxt 3 문서에 문서화되어 있습니다. 이전 @nuxtjs/composition-api composable과 마찬가지로, 이 composable들은 클라이언트 측에서 라우트 네비게이션을 차단하지 않습니다(이름에 'lazy'가 붙은 이유입니다).

이름이 비슷하더라도 API는 완전히 다르다는 점에 유의하세요. 특히, 이전 useFetch에서 했을 수도 있듯이 composable 외부의 다른 변수 값을 변경하려고 해서는 안 됩니다.
useLazyFetch는 Nitro를 위해 설정되어 있어야 합니다.

useAsync에서 새로운 composable로 마이그레이션:

<script setup>
- import { useAsync } from '@nuxtjs/composition-api'
- const posts = useAsync(() => $fetch('/api/posts'))
+ const { data: posts } = useLazyAsyncData('posts', () => $fetch('/api/posts'))
+ // 또는, 더 간단하게!
+ const { data: posts } = useLazyFetch('/api/posts')
</script>

useFetch에서 새로운 composable로 마이그레이션:

<script setup>
- import { useFetch } from '@nuxtjs/composition-api'
- const posts = ref([])
- const { fetch } = useFetch(() => { posts.value = await $fetch('/api/posts') })
+ const { data: posts, refresh } = useLazyAsyncData('posts', () => $fetch('/api/posts'))
+ // 또는, 더 간단하게!
+ const { data: posts, refresh } = useLazyFetch('/api/posts')
  function updatePosts() {
-   return fetch()
+   return refresh()
  }
</script>

useMeta

vue-meta와 상호작용하기 위해서는 Nuxt Bridge에서 동작하는 useNuxt2Meta를 사용할 수 있으며, 이를 통해 vue-meta와 호환되는 방식으로 메타 태그를 조작할 수 있습니다.

<script setup>
- import { useMeta } from '@nuxtjs/composition-api'
  useNuxt2Meta({
    title: 'My Nuxt App',
  })
</script>

또한 computed 값이나 ref를 전달할 수도 있으며, 메타 값은 반응형으로 업데이트됩니다:

<script setup>
const title = ref('my title')
useNuxt2Meta({
  title,
})
title.value = 'new title'
</script>
동일한 컴포넌트 내에서 useNuxt2Meta()와 Options API의 head()를 동시에 사용하지 않도록 주의하세요. 예측 불가능한 동작이 발생할 수 있습니다.

Nuxt Bridge는 또한 useHead composable을 통해 접근할 수 있는 Nuxt 3 호환 메타 구현도 제공합니다.

<script setup>
- import { useMeta } from '@nuxtjs/composition-api'
  useHead({
    title: 'My Nuxt App',
  })
</script>

또한 nuxt.config에서 이를 명시적으로 활성화해야 합니다:

import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  bridge: {
    meta: true,
  },
})

이 useHead composable은 <head>를 조작하기 위해 내부적으로 vue-meta가 아닌 @unhead/vue를 사용합니다. 따라서 기본 Nuxt 2의 head() 속성과 useHead를 동시에 사용하는 것은 권장되지 않으며, 충돌이 발생할 수 있습니다.

이 composable을 사용하는 방법에 대한 더 많은 정보는 Nuxt 3 문서를 참고하세요.

명시적 임포트

Nuxt는 모든 자동 임포트를 #imports 별칭으로 노출하며, 필요하다면 이를 사용해 임포트를 명시적으로 할 수 있습니다:

<script setup lang="ts">
import { computed, ref } from '#imports'

const count = ref(1)
const double = computed(() => count.value * 2)
</script>

자동 임포트 비활성화

composable과 유틸리티의 자동 임포트를 비활성화하려면, nuxt.config 파일에서 imports.autoImport를 false로 설정하면 됩니다.

nuxt.config.ts
export default defineNuxtConfig({
  imports: {
    autoImport: false,
  },
})

이렇게 하면 자동 임포트가 완전히 비활성화되지만, 여전히 #imports에서 명시적 임포트를 사용하는 것은 가능합니다.