Инструкция по миграции с Nuxt 3 на Nuxt 4

Введение

Переход между основными версиями фреймворков — всегда важная задача, особенно когда обновление приносит изменения в архитектуре или поведении базовых функций. Nuxt 4 — это новый виток развития любимого многими разработчиками фреймворка для серверного рендеринга на Vue. Если вы уже работали с Nuxt 3, знакомы с его преимуществами и мечтаете получить еще больше производительности, расширяемости и современного опыта разработки — переход на Nuxt 4 будет логичным шагом. Здесь я подробно рассказываю, как провести миграцию проекта, на что обратить внимание и какие подводные камни можно встретить на пути. По ходу статьи я буду показывать примеры кода и объяснять, как их адаптировать под новую версию.

Подготовка и предварительные шаги

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

Оценка текущего состояния проекта

• Проверьте, какие зависимости используете в проекте. Убедитесь, что критичные пакеты (например, сторонние модули) поддерживают Nuxt 4.
• Оцените кастомные плагины, middleware и настройки конфигов — возможно, потребуется внести изменение в синтаксис или способ подключения.
• Сделайте резервную копию репозитория — создайте отдельную ветку для миграции.

Обновление зависимостей

В первую очередь требуется обновить пакет nuxt и связанные зависимости.

# Обновляем Nuxt до 4 версии
npm install nuxt@latest

# Или, используя Yarn
yarn add nuxt@latest

Когда завершите — обновите также все официальные модули (например, @nuxt/image, @nuxt/content), если они используются. Проверьте страницу npm для каждого модуля: у них могли появиться версии, поддерживающие только Nuxt 4.

Ключевые отличия между Nuxt 3 и Nuxt 4

Прежде чем приступать к коду, давайте рассмотрим, что изменилось:

• Появление новых хуков жизненного цикла и изменения в подходах к middleware.
• Улучшенная поддержка TypeScript, возможны изменения в типах и способах написания деклараций.
• Изменения в API для использования серверных функций (например, комбинация useAsyncData и серверных методов).

Переход с Nuxt 3 на Nuxt 4 – это важный шаг для поддержания актуальности вашего проекта и использования новых возможностей фреймворка. Однако, миграция может быть сложной задачей, требующей внимательного изучения изменений и адаптации кода. Если вы хотите детальнее погрузиться в мир Nuxt, освоить все его тонкости и стать настоящим профессионалом — приходите на наш большой курс Nuxt - fullstack Vue фреймворк. На курсе 129 уроков и 13 упражнений, AI-тренажеры для безлимитной практики с кодом и задачами 24/7, решение задач с живым ревью наставника, еженедельные встречи с менторами.

Миграция конфигурационного файла nuxt.config

Файл конфигурации преобразуется проще всего, если вы сравните его с официальным шаблоном Nuxt 4.

Пример из Nuxt 3

// nuxt.config.ts в Nuxt 3
export default defineNuxtConfig({
  modules: ['@nuxtjs/tailwindcss'],
  runtimeConfig: {
    public: {
      apiBase: '/api'
    }
  }
})

Как это выглядит в Nuxt 4

// nuxt.config.ts в Nuxt 4
export default defineNuxtConfig({
  modules: [
    '@nuxtjs/tailwindcss', // Модуль подключен без изменений
  ],
  runtimeConfig: {
    public: {
      apiBase: '/api'
    }
  },
  // Например, добавлены новые опции, связанные с build или experimental флагами
  experimental: {
    componentIslands: true
  }
})
// Обратите внимание: старый синтаксис работает, однако появилась поддержка новых секций и глубже прорефакторена типизация

Проверьте, появились ли новые experimental или устаревшие опции — загрузите официальную документацию и сравните настройки.

Миграция страниц, компонентов и хуков

Теперь покажу, как нужно обновлять страницы, компоненты и хуки. В большинстве случаев синтаксис компонентов остается тем же, но появляются мелкие изменения.

Использование хуков жизненного цикла

В Nuxt 3 и Nuxt 4 хуки жизненного цикла похожи, но добавлены новые возможности или изменен порядок вызова.

// Пример - работы с хуками в Nuxt 4
<script setup>
onMounted(() => {
  // Ваш код отработает после монтирования компонента
  console.log('Component is mounted')
})
</script>

Обратите внимание: хуки вроде onServerPrefetch или onBeforeMount необходимы реже, их применение теперь ближе к классическому Vue 3.

Серверные функции и данные

В Nuxt 3 очень часто использовались функции useAsyncData для асинхронной загрузки на сервере.

Nuxt 3:

<script setup>
const { data, pending, error } = await useAsyncData('posts', () => $fetch('/api/posts'))
</script>

Nuxt 4:

<script setup>
const { data, pending, error } = await useAsyncData('posts', () => $fetch('/api/posts'))
// Этот код остался актуальным, но теперь стал поддерживать типизацию шире и работает с новыми server-only методами.
</script>

Новое в Middleware

Middleware в Nuxt 3 и Nuxt 4 все так же регистрируются через каталог middleware.

Пример глобального middleware для авторизации

Nuxt 3:

// middleware/auth.global.ts
export default defineNuxtRouteMiddleware((to, from) => {
  // Проверка аутентификации
})

Nuxt 4:

// middleware/auth.global.ts
export default defineNuxtRouteMiddleware((to, from) => {
  // Проверка осталась прежней, но теперь сохранился порядок вызова global
})

Почти ничего не изменилось, но в Nuxt 4 middleware работают эффективнее и с улучшенной типизацией.

Миграция серверных API (server/api)

В Nuxt 3 API-ендпоинты писали так:

// server/api/hello.get.ts
export default defineEventHandler(() => {
  return { hello: 'world' }
})

В Nuxt 4 такой же код продолжает работать. Но добавлены новые возможности по типизации и взаимосвязи с runtimeConfig. Например, теперь проще получить значения из конфига Nuxt прямо внутри handler:

// server/api/hello.get.ts
export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event) // Теперь вы получаете доступ к runtimeConfig
  return { hello: 'world' }
})

Миграция модулей и плагинов

Многие сторонние Nuxt-модули требуют обновления для поддержки Nuxt 4. Проверьте доступные версии модулей.

Пример перехода с Nuxt 3 TailwindCSS

npm install @nuxtjs/tailwindcss@latest

Проверьте документацию модуля — возможно, в конфиге модуля были изменены параметры или структуры (например, путь к Tailwind-конфигу, включение/отключение JIT).

Миграция собственных плагинов

Плагины, регистрируемые в папке plugins, могут потребовать переписывания, если изменился способ их инъекции в приложение.

Nuxt 3:

// plugins/myPlugin.ts
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.provide('myPlugin', myFunction)
})

Nuxt 4:

// plugins/myPlugin.ts
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.provide('myPlugin', myFunction)
})
// В Nuxt 4 осталось точно так же. Однако типизация nuxtApp теперь улучшилась, что облегчает работу в TypeScript

Актуализация интеграции с Vue и экосистемой

Nuxt 4 теперь официально поддерживает Vue 3 последней версии. Если у вас кастомные компоненты, следите, что используемая вами версия Vue-плагинов (например, Pinia или VueUse) совместима с актуальным Vue.

• Обновите все плагины npm install pinia@latest vueuse@latest
• Проверьте код на наличие устаревших методов Vue (например, переход с Options API на Composition API не обязателен, но рекомендуется)

Работа с генерацией статических сайтов и SSR

В Nuxt 4 изменился подход к статической генерации:

Nuxt 3:

// nuxt.config.ts
export default defineNuxtConfig({
  ssr: false, // SPA
  target: 'static'
})

Nuxt 4:

// nuxt.config.ts
export default defineNuxtConfig({
  ssr: true, // SSR включен по умолчанию
  nitro: {
    preset: 'vercel'
  }
})
// target устарел, используйте настройки Nitro Presets для деплоя в облака

В генерации статических сайтов теперь все управление идет через Nitro Engine. Рекомендуется обновить скрипты деплоя.

Проверка всего проекта и тестирование

После внесения изменений запустите проект в режиме разработки:

npm run dev

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

Запустите сборку для production, чтобы убедиться в отсутствии ошибок:

npm run build
npm run preview

Если используете end-to-end тесты — обязательно прогоните их. Возможны несовместимости на уровне рендеринга, которые можно выявить только тестированием.

Подводные камни и часто встречающиеся трудности

• Многие популярные сторонние модули могут не иметь моментальной поддержки Nuxt 4 (ожидайте своевременных обновлений).
• Если использовались кастомные полифиллы или override серверных API — надо убедиться, что архитектура Nitro их поддерживает.
• Любые глубокие кастомизации (например, собственные build-хуки или webpack модификации) потребуют адаптации.
• Будьте осторожны при миграции TypeScript-типов для Nuxt App — часть глобальных типов может быть переименована или вынесена в отдельные пакеты.

Заключение

Миграция на Nuxt 4 проходит максимально гладко, если заранее оценить совместимость используемых зависимостей, адаптировать конфиги и компоненты к новым подходам, и уделить достаточно внимания тестированию. В этой инструкции я показал, как проходит переход на ключевых этапах: обновления зависимостей, настройки core-файлов, пересмотра модулей и плагинов, смены подходов SSR и генерации. Не забывайте читать changelog и официальные гайды Nuxt — они помогут избежать неожиданных проблем.

Успешная миграция с Nuxt 3 на Nuxt 4 требует не только знания новых API, но и понимания изменений в архитектуре и подходах к разработке. Чтобы миграция прошла безболезненно и эффективно, необходима практика и поддержка опытных разработчиков. На курсе Nuxt - fullstack Vue фреймворк вы научитесь мигрировать проекты с Nuxt 3 на Nuxt 4, используя лучшие практики и избегая распространенных ошибок. В первых 3 модулях уже доступно бесплатное содержание — начните погружаться в мир Nuxt прямо сегодня.

Частозадаваемые технические вопросы по теме статьи и ответы на них

Как перейти на новый Nuxt, если много кастомных Webpack-плагинов?

В Nuxt 4 стандартная система сборки основывается на Vite или Nitro, а поддержка Webpack минимальна. Если ваши плагины незаменимы, проверьте, поддерживаются ли они Vite — многие плагины можно переписать под плагин для Vite. Для редких случаев можно явно включить режим webpack через настройку сборки, но рекомендуется по возможности мигрировать на Vite-плагины.

Что делать, если мой модуль для Nuxt еще не поддерживает четвертую версию?

Проверьте репозиторий/issue tracker этого модуля — часто разработчики указывают ветку или forк, совместимый с Nuxt 4. Если форка нет, попробуйте временно отказаться от модуля или реализовать нужную функциональность вручную, опираясь на документацию по внутренним API Nuxt 4.

Есть ли способ частично мигрировать проект или переключаться между версиями?

Нет, Nuxt не поддерживает одновременный запуск разных мажорных версий в одном проекте. Перевести только часть кода не получится, но вы можете перенести проект в новую ветку, постепенно переписывать функционал и тестировать части по отдельности.

Как правильно обновлять TypeScript-типизацию после миграции?

После обновления Nuxt установите все последние типы зависимостей, сотрите устаревшие @types пакеты. Проверьте, что типы, импортируемые из nuxt, соответственно переносятся (часть глобальных объявлений вынесена в отдельные пакеты, например #nuxt/schema).

Как перейти на новую систему environment переменных в Nuxt 4?

В Nuxt 4 рекомендуется использовать runtimeConfig. Для передачи переменных окружения используйте секции public и private в nuxt.config.ts. Все переменные передавайте в runtimeConfig из-прод файла или через process.env прямо на сервере. Прямое использование process.env по всей кодовой базе не приветствуется — замените его на обращения через useRuntimeConfig внутри компонентов и серверных обработчиков.