Новый Composition API

Если заранее перейти с @nuxtjs/composition-api на API, совместимое с Nuxt 3, объём правок при полном переходе на Nuxt 3 останется небольшим.

ssrRef и shallowSsrRef

Эти две функции были заменены на новый композабл, работающий похожим образом внутри: useState.

Главное отличие: нужно явно задать ключ состояния (раньше его для ssrRef и shallowSsrRef подставлял Nuxt), а вызывать useState можно только внутри плагина Nuxt 3 с defineNuxtPlugin или в setup компонента. В «голом» глобальном контексте его использовать нельзя — иначе состояние может смешаться между запросами.

- 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)

Поскольку состояние задаётся ключом, вы можете получить доступ к одному и тому же состоянию из нескольких мест, если используете один и тот же ключ.

Подробнее о композабле — в документации.

ssrPromise

Эта функция удалена: если вы её использовали, понадобится своя замена. Если сценарий с ssrPromise важен — опишите его в обсуждении на GitHub.

onGlobalSetup

Эта функция удалена, но те же задачи решаются через useNuxtApp или useState внутри defineNuxtPlugin. Произвольный код можно выполнять и в setup() корневого layout-компонента.

- 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()

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

Эти два композабла можно заменить на useLazyAsyncData и useLazyFetch (см. useLazyAsyncData и useLazyFetch). Как и в @nuxtjs/composition-api, они не блокируют клиентскую навигацию — отсюда префикс lazy в имени.

Миграция на новые композаблы с useAsync:

<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:

<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 (но не в Nuxt 3) можно использовать useNuxt2Meta — он даёт тот же способ задавать мета-теги, что и vue-meta.

<script setup>
- import { useMeta } from '@nuxtjs/composition-api'
  useNuxt2Meta({
    title: 'Моё приложение Nuxt',
  })
</script>

Вы также можете передавать вычисляемые свойства (computed) или ref, и метаданные будут обновляться реактивно:

<script setup>
const title = ref('мой заголовок')
useNuxt2Meta({
  title,
})
title.value = 'новый заголовок'
</script>

Nuxt Bridge также предоставляет реализацию мета-тегов, совместимую с Nuxt 3, которую можно получить с помощью композабла useHead.

<script setup>
- import { useMeta } from '@nuxtjs/composition-api'
  useHead({
    title: 'Моё приложение Nuxt',
  })
</script>

Вам также необходимо явно включить его в вашем nuxt.config:

import { defineNuxtConfig } from '@nuxt/bridge'

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

Композабл useHead внутри опирается на @unhead/vue, а не на vue-meta, и управляет содержимым <head>. Не смешивайте нативный head() Nuxt 2 с useHead — возможны конфликты.

Подробнее о метаданных см. useSeoMeta и смежные разделы API.

Явные импорты

Nuxt предоставляет доступ к каждому автоматическому импорту с помощью псевдонима #imports, который можно использовать для явного импорта при необходимости:

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

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

Отключение автоматического импорта

Если вы хотите отключить автоматический импорт композаблов и утилит, вы можете установить imports.autoImport в false в файле nuxt.config.

export default defineNuxtConfig({
  imports: {
    autoImport: false,
  },
})

Это полностью отключит автоимпорт, но всё ещё можно использовать явные импорты из #imports.