Nuxt mid-level certification launch date announced!

Конфигурация

Узнайте, как перейти с Nuxt 2 на новую конфигурацию Nuxt 3.

nuxt.config

Отправной точкой для вашего приложения Nuxt остается файл nuxt.config.

Конфигурация Nuxt будет загружена с помощью unjs/jiti и unjs/c12.

Миграция

  1. Вам следует мигрировать на новую функцию defineNuxtConfig, которая предоставляет типизированную схему конфигурации.
    export default {
      // ...
    }
    
  2. Если вы использовали router.extendRoutes, вы можете мигрировать на новый хук pages:extend:
    export default {
      router: {
        extendRoutes (routes) {
          //
        }
      }
    }
    
  3. Если вы использовали router.routeNameSplitter, вы можете получить тот же результат, обновив логику генерации имени маршрута в новом хуке pages:extend:
    export default {
      router: {
        routeNameSplitter: '/'
      }
    }
    

ESM Syntax

Nuxt 3 является нативным ESM-фреймворком. Хотя unjs/jiti обеспечивает частичную совместимость при загрузке файла nuxt.config, избегайте любого использования require и module.exports в этом файле.

  1. Измените module.exports на export default
  2. Измените const lib = require('lib') на import lib from 'lib'

Async Configuration

Для обеспечения более предсказуемого поведения загрузки Nuxt синтаксис асинхронной конфигурации устарел. Рассмотрите возможность использования хуков Nuxt для асинхронных операций.

Dotenv

У Nuxt есть встроенная поддержка загрузки файлов .env. Избегайте прямого импорта из nuxt.config.

Modules

Nuxt и модули Nuxt теперь доступны только во время сборки.

Миграция

  1. Переместите все свои buildModules в modules.
  2. Проверьте совместимость модулей с Nuxt 3.
  3. Если у вас есть какие-либо локальные модули, указывающие на директорию, вам следует обновить это, чтобы указать на файл входа:
  export default defineNuxtConfig({
    modules: [
-     '~/modules/my-module'
+     '~/modules/my-module/index'
    ]
  })
Если вы являетесь автором модуля, вы можете ознакомиться с дополнительной информацией о совместимости модулей и нашим руководством для авторов модулей.

Изменения в директориях

Директория static/ (для хранения статических ассетов) была переименована в public/. Вы можете либо переименовать свою директорию static в public, либо сохранить это имя, установив dir.public в вашем nuxt.config.

Узнать больше Docs > Guide > Directory Structure > Public.

TypeScript

Перенести ваше приложение будет гораздо проще, если вы воспользуетесь интеграцией Nuxt с TypeScript. Это не значит, что вам нужно писать приложение на TypeScript, просто Nuxt обеспечит автоматические подсказки типов для вашего редактора.

Подробнее о поддержке TypeScript в Nuxt вы можете прочитать в документации.

Nuxt может проверить тип вашего приложения, используя vue-tsc с помощью команды nuxi typecheck.

Миграция

  1. Создайте файл tsconfig.json со следующим содержимым:
    {
      "extends": "./.nuxt/tsconfig.json"
    }
    
  2. Запустите npx nuxi prepare для генерации .nuxt/tsconfig.json.
  3. Установите Volar, следуя инструкциям в документации.

Изменения во Vue

Существует ряд изменений, касающиеся рекомендуемых лучших практик Vue, а также ряд критических изменений между Vue 2 и 3.

Рекомендуется прочитать Руководство по миграции Vue 3 и, в частности, список изменений.

В настоящее время невозможно использовать сборку для миграции Vue 3 с Nuxt 3.

Vuex

Nuxt больше не предоставляет интеграцию с Vuex. Вместо этого официальная рекомендация Vue - использовать pinia, которая имеет встроенную поддержку Nuxt через модуль Nuxt. Подробнее о pinia здесь.

Простой способ обеспечить глобальное управление состоянием с помощью pinia заключается в следующем:

Установите модуль @pinia/nuxt:

Terminal
yarn add pinia @pinia/nuxt

Включите модуль в конфигурации Nuxt:

nuxt.config.ts
import { defineNuxtConfig } from 'nuxt/config';

export default defineNuxtConfig({
  modules: ['@pinia/nuxt']
})

Создайте директорию store в корне вашего приложения:

store/index.ts
import { defineStore } from 'pinia'

export const useMainStore = defineStore('main', {
  state: () => ({
    counter: 0,
  }),
  actions: {
    increment() {
      // `this` - это инстанс стора
      this.counter++
    },
  },
})

Создайте файл плагина, чтобы глобализировать ваше хранилище:

plugins/pinia.ts
import { useMainStore } from '~/store'

export default defineNuxtPlugin(({ $pinia }) => {
  return {
    provide: {
      store: useMainStore($pinia)
    }
  }
})

Если вы хотите продолжить использовать Vuex, вы можете вручную мигрировать на Vuex 4, следуя этим шагам.

Когда это будет сделано, вам потребуется добавить следующий плагин в ваше приложение Nuxt:

plugins/vuex.ts
import store from '~/store'

export default defineNuxtPlugin(nuxtApp => {
  nuxtApp.vueApp.use(store);
})

Для крупных приложений эта миграция может потребовать много работы. Если обновление Vuex все еще создает препятствия, вам может потребоваться использовать общедоступный модуль: nuxt3-vuex-module, который должен работать из коробки.