Новый Composition API

Nuxt Bridge реализует компосаблы, совместимые с Nuxt 3.

Переход с @nuxtjs/composition-api на API, совместимый с Nuxt 3, уменьшит объём правок при миграции на Nuxt 3.

ssrRef и shallowSsrRef

Обе функции заменены композаблом useState, работающим аналогично.

Отличия: нужно задать ключ состояния (раньше Nuxt генерировал его для ssrRef и shallowSsrRef) и вызывать только внутри плагина Nuxt 3 (defineNuxtPlugin) или экземпляра компонента. (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)

Благодаря ключу одно и то же состояние доступно из разных мест при одинаковом ключе.

Подробнее: документация Nuxt 3.

ssrPromise

Функция удалена; при необходимости реализуйте альтернативу. Кейсы для ssrPromise можно обсудить в репозитории.

onGlobalSetup

Функция удалена. Вместо неё используйте useNuxtApp или useState внутри defineNuxtPlugin, либо выполняйте код в 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 его не будет. Лучше искать другой способ доступа к нужным данным (при необходимости — feature request или обсуждение).

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, см. документацию Nuxt 3. Как и старые композаблы, они не блокируют навигацию на клиенте («lazy» в названии).

API другой, несмотря на похожие имена. Не меняйте переменные снаружи композабла (как иногда делали со старым useFetch).
Для useLazyFetch должен быть настроен Nitro.

Миграция с 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 используйте useNuxt2Meta — он работает в Nuxt Bridge (но не в Nuxt 3) и управляет мета-тегами в формате, совместимом с 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 = 'new title'
</script>
Не используйте в одном компоненте одновременно useNuxt2Meta() и Options API head() — поведение может быть непредсказуемым.

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 — возможны конфликты.

Подробнее: документация Nuxt 3.

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

Nuxt экспортирует автоимпорты через алиас #imports для явного импорта при необходимости:

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

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

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

Чтобы отключить автоимпорт композаблов и утилит, задайте в nuxt.config: imports.autoImport: false.

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

Автоимпорты будут полностью отключены; явные импорты из #imports по-прежнему доступны.