Nuxt 4.3

Nuxt 4.3 добавляет мощные возможности для макетов, кэширования и developer experience, а также заметные улучшения производительности.

📣 Новости

Продлённая поддержка v3

В начале месяца я открыл обсуждение, чтобы узнать, как прошёл переход с v3 на v4. Приятно было услышать, что у большинства всё прошло хорошо.

При этом мы хотим, чтобы никто не остался за бортом. Поэтому мы продолжим выпускать обновления безопасности и критические исправления после ранее объявленной даты end-of-life 31 января 2026 года: Nuxt v3 достигнет end-of-life 31 июля 2026 года.

Подготовка к Nuxt 5

Мы как никогда близки к релизам Nuxt v5 и Nitro v3. В ближайшие недели ветка main репозитория Nuxt начнёт получать первые коммиты для Nuxt 5. При этом работа идёт как обычно.

• Продолжайте отправлять pull request в ветку main
• Мы будем переносить изменения в ветки 4.x и 3.x

Следите за руководством по обновлению — мы добавим детали о том, как уже сейчас можно начать миграцию проектов к Nuxt v4 с future.compatibilityVersion: 5.

🗂️ Макеты в route rules

Но хватит о будущем. Сегодня для вас много полезного!

Во-первых, макеты теперь можно задавать прямо в route rules через новое свойство appLayout (#31092). Это даёт централизованный декларативный способ управлять макетами без разбросанных вызовов definePageMeta по страницам.

export default defineNuxtConfig({
  routeRules: {
    '/admin/**': { appLayout: 'admin' },
    '/dashboard/**': { appLayout: 'dashboard' },
    '/auth/**': { appLayout: 'minimal' }
  }
})

Это удобно для:

• Админ-панелей с общим макетом для многих маршрутов
• Маркетинговых страниц с макетом, отличным от основного приложения

📦 ISR/SWR Payload Extraction

Извлечение payload теперь работает с правилами ISR (incremental static regeneration), SWR (stale-while-revalidate) и cache в route rules (#33467). Раньше файлы _payload.json создавались только для пререндеренных страниц.

Это значит:

• При клиентской навигации на ISR/SWR-страницы можно использовать кэшированный payload
• CDN (Vercel, Netlify, Cloudflare) могут кэшировать payload вместе с HTML
• Меньше запросов при навигации — данные можно подгружать из кэшированного payload

export default defineNuxtConfig({
  routeRules: {
    '/products/**': { 
      isr: 3600, // Ревалидация каждый час
    }
  }
})

🧹 Payload extraction в dev-режиме

В связи с вышесказанным, извлечение payload теперь работает и в режиме разработки (#30784). Так проще тестировать и отлаживать поведение payload без production-сборки.

🚫 Отключение модулей из слоёв

При расширении Nuxt layers теперь можно отключать ненужные модули (#33883). Достаточно передать в опции модуля false:

export default defineNuxtConfig({
  extends: ['../shared-layer'],
  // отключить @nuxt/image из слоя
  image: false,
})

🏷️ Route groups в page meta

Route groups (папки в скобках, например (protected)/) теперь доступны в page meta (#33460). Так проще проверять принадлежность маршрута к группе в middleware или везде, где есть доступ к маршруту.

<script setup lang="ts">
// В meta этой страницы будет: { groups: ['protected'] }
useRoute().meta.groups
</script>

export default defineNuxtRouteMiddleware((to) => {
  if (to.meta.groups?.includes('protected') && !isAuthenticated()) {
    return navigateTo('/login')
  }
})

Так получается аккуратная конвенция для авторизации на уровне маршрутов без definePageMeta на каждой защищённой странице.

🎨 Пропсы макета в setPageLayout

Комозабл setPageLayout теперь принимает второй аргумент для передачи пропсов в макет (#33805):

export default defineNuxtRouteMiddleware((to) => {
  setPageLayout('admin', {
    sidebar: true,
    theme: 'dark'
  })
})

<script setup lang="ts">
defineProps<{
  sidebar?: boolean
  theme?: 'light' | 'dark'
}>()
</script>

🔧 Алиас #server

Новый алиас #server даёт аккуратный импорт внутри серверной директории (#33870), по аналогии с #shared:

// Было: относительные пути
import { helper } from '../../../../utils/helper'

// Стало: предсказуемо и чисто
import { helper } from '#server/utils/helper'

Алиас защищён: импорт кода из #server из клиентского или shared-контекста невозможен.

🪟 Перетаскиваемый Error Overlay

Оверлей ошибок в режиме разработки из Nuxt 4.2 теперь можно перетаскивать и сворачивать (#33695). Можно:

• Перетащить в любой угол экрана (привязка к краям)
• Свернуть в небольшую кнопку-таблетку, чтобы продолжать работать
• Позиция и свёрнутое состояние сохраняются между перезагрузками страницы

Это улучшает комфорт, когда вы правите баги и не хотите, чтобы оверлей перекрывал вид.

⚙️ Асинхронные конструкторы плагинов

Авторы модулей теперь могут использовать async-функции при добавлении build-плагинов (#33619):

export default defineNuxtModule({
  async setup() {
    // Ленивая загрузка только при необходимости
    addVitePlugin(() => import('my-cool-plugin').then(r => r.default()))
    
    // Webpack-плагин не нужен при использовании Vite
    addWebpackPlugin(() => import('my-cool-plugin/webpack').then(r => r.default()))
  }
})

Так реализуется настоящая ленивая загрузка build-плагинов без лишней загрузки кода, когда плагины не нужны.

🚀 Улучшения производительности

В этом релизе несколько оптимизаций для ускорения сборки:

• Фильтры хуков — внутренние плагины используют фильтры, чтобы не вызывать хуки без необходимости (#33898)
• Оптимизация SSR-стилей — плагин nuxt:ssr-styles стал заметно быстрее (#33862, #33865)
• Трансформ алиасов слоёв — пропускается при использовании Vite (он делает это нативно) (#33864)
• Компиляция route rules — route rules компилируются в клиентский чанк через rou3, что убирает необходимость в radix3 в клиентском бандле и запросы манифеста приложения (#33920)

🎨 Inline-стили для Webpack/Rspack

Возможность inlineStyles теперь работает со сборщиками webpack и rspack (#33966), не только с Vite. Это даёт инлайнинг критического CSS для лучших Core Web Vitals независимо от выбора бандлера.

⚠️ Устаревания

statusCode → status, statusMessage → statusText

В рамках подготовки к Nitro v3 и H3 v2 мы переходим на соглашения Web API (#33912). Старые свойства пока работают, но помечены устаревшими перед v5:

- throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+ throw createError({ status: 404, statusText: 'Not Found' })

🐛 Исправления ошибок

Важные исправления в этом релизе:

• Исправлена дедупликация head-компонентов с атрибутом key (#33958, #33963)
• Исправлена нереактивность свойств async data в Options API (#34119)
• Исправлен небезопасный разбор чисел в useCookie при decode (#34007)
• Исправлено отсутствие перерисовки NuxtPage при отключённых макетах у вложенного NuxtLayout (#34078)
• Исправлено декодирование pathname на клиенте для не-ASCII алиасов маршрутов (#34043)
• Исправлен ремаунт suspense при навигации после pending-состояния (#33991)
• Исправлено копирование в буфер обмена в error overlay (#33873)
• Включён allowArbitraryExtensions по умолчанию в конфиге TypeScript (#34084)
• Добавлен noUncheckedIndexedAccess в server tsconfig для более строгой типизации (#33985)

export default defineNuxtConfig({
  nitro: {
    typescript: {
      tsConfig: {
        compilerOptions: {
          noUncheckedIndexedAccess: false
        }
      }
    }
  }
})

📚 Документация

• Улучшены гайды для авторов модулей с более ясной структурой (#33803)
• Добавлены инструкции по настройке MCP для Claude Desktop (#33914)
• Добавлена документация по директории layers (#33967)
• Добавлены примеры с менеджером пакетов Deno (#34070)
• Уточнены ограничения контекста проверки типов для серверных маршрутов (#33964)

🎉 Nuxt 3.21.0

Вместе с v4.3.0 выходит Nuxt v3.21.0 с теми же улучшениями, перенесёнными в ветку 3.x. В релиз входят:

• Те же возможности: макеты в route rules, ISR payload extraction, пропсы макета в setPageLayout, алиас #server, перетаскиваемый error overlay и др.
• Все улучшения производительности: оптимизация SSR-стилей, фильтры хуков, компиляция route rules
• Отключение модулей: отключение модулей слоя через опцию false
• Критические исправления: реактивность async data в Options API, разбор чисел в useCookie, дедупликация head-компонентов и др.

✅ Обновление

Рекомендуем обновиться так:

npx nuxt upgrade --dedupe

# или при обновлении до v3.21
npx nuxt@latest upgrade --dedupe --channel=v3

Команда дедуплицирует lockfile и поможет подтянуть обновления зависимостей Nuxt, в том числе из экосистемы unjs.

👉 Полные release notes

Спасибо всем контрибьюторам этого релиза! 💚