Nuxt 4: что это, как работает и как начать

Nuxt — полнофункциональный фреймворк поверх Vue для сайтов и веб-приложений. Он даёт файловую маршрутизацию, серверный рендеринг, генерацию статических страниц, серверные API и единый процесс сборки. На 1 октября 2026 года актуальная стабильная ветка — Nuxt 4; официальная документация уже описывает Nuxt 5 как разрабатываемую версию, поэтому начинать новый production-проект на ней пока не стоит.

Когда Nuxt полезен

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

• страницы, которые поисковый робот и пользователь получают уже с HTML;
• статическая генерация контентных страниц;
• смешанный режим: часть маршрутов статическая, часть рендерится на сервере;
• API-обработчики рядом с интерфейсом;
• автоматические импорты компонентов и composables;
• единая конфигурация метаданных, middleware и развёртывания.

Для небольшого клиентского виджета или одностраничного кабинета Nuxt может быть избыточен: обычного Vue с Vite иногда достаточно. Nuxt особенно полезен для контентных сайтов, магазинов, личных кабинетов с публичной частью и приложений, где одновременно важны SEO, скорость первого ответа и серверная логика.

Как Nuxt формирует страницу

Nuxt работает с серверным движком Nitro, который собирает приложение для Node.js, serverless- и edge-сред. Конкретный preset и ограничения нужно выбирать под платформу размещения, а не после завершения разработки.

Что изменилось в Nuxt 4

Главное заметное изменение — структура проекта. Клиентский код по умолчанию находится в каталоге app/, серверный — в корневом server/, а общий для обеих сред код можно хранить в shared/. Согласно официальному руководству по переходу на Nuxt 4, старую структуру Nuxt 3 фреймворк во многих случаях распознаёт для обратной совместимости, но новые проекты лучше строить по актуальной схеме.

app/
  components/
  composables/
  layouts/
  pages/
  plugins/
  app.vue
public/
server/
  api/
shared/
nuxt.config.ts
package.json

В Nuxt 4 алиас ~/ по умолчанию указывает на каталог приложения app/. Каталоги server/, public/, modules/ и layers/ остаются в корне. Это важно при переносе конфигурации Tailwind, ESLint, тестов и собственных модулей.

Как создать новый проект

Актуальная инструкция Nuxt 4 требует Node.js 22.x или новее и рекомендует активную LTS-версию. Проверьте версию:

node --version
npm create nuxt@latest my-app
cd my-app
npm install
npm run dev

После запуска откройте адрес, показанный в терминале. Менеджер пакетов можно заменить на pnpm, Yarn, Bun или Deno, но в одном проекте лучше придерживаться одного lock-файла.

Минимальный пример страницы и API

Файл app/pages/index.vue создаёт маршрут /:

<script setup lang="ts">
const { data } = await useFetch('/api/status')
</script>

<template>
  <main>
    <h1>Nuxt 4 работает</h1>
    <p>{{ data?.message }}</p>
  </main>
</template>

Файл server/api/status.get.ts создаёт серверный обработчик:

export default defineEventHandler(() => ({
  message: 'Ответ получен от Nitro'
}))

useFetch учитывает серверный рендеринг и переносит полученные данные в payload страницы, чтобы браузер не делал ненужный повторный запрос при гидратации.

Маршруты, данные и SEO

Файл app/pages/catalog/[slug].vue создаст динамический маршрут. Параметр доступен через useRoute(). Для метаданных используйте useSeoMeta(), а не ручное изменение document.title: так заголовок и описание попадут в серверный HTML.

const route = useRoute()
const { data: item } = await useFetch(`/api/items/${route.params.slug}`)

useSeoMeta({
  title: () => item.value?.title ?? 'Каталог',
  description: () => item.value?.description ?? ''
})

SSR сам по себе не гарантирует хорошие позиции: остаются требования к содержанию, canonical, status-кодам, скорости, внутренним ссылкам и отсутствию дублей. Nuxt лишь даёт инструменты для корректной реализации.

Как перейти с Nuxt 3

1. Зафиксируйте рабочую ветку и обновите тесты.
2. Запустите npx nuxt upgrade и проверьте changelog зависимостей.
3. Для перехода на ветку 4 установите nuxt@^4.0.0.
4. Перенесите клиентские каталоги в app/ вручную или примените официальный codemod npx codemod@latest nuxt/4/file-structure.
5. Оставьте server/, public/, shared/, modules/ и layers/ в корне.
6. Обновите пути в конфигурации линтера, CSS-фреймворка, тестов и CI.
7. Проверьте SSR, клиентскую навигацию, API, ошибки и production-сборку.

Команда обновления не заменяет тестирование. Особое внимание уделите коду, который полагался на глобальный window.__NUXT__, старые алиасы и смешение серверных и клиентских импортов.

Что изучить начинающему

Перед Nuxt полезно уверенно знать JavaScript, основы TypeScript, компоненты Vue, реактивность и Composition API. Затем последовательно изучайте маршрутизацию, получение данных, состояние, middleware, Nitro и развёртывание. Не начинайте с десятка модулей: сначала соберите небольшой проект на встроенных возможностях и измерьте, чего действительно не хватает.

Итог: Nuxt 4 подходит, когда Vue-приложению нужны готовая архитектура, серверный рендеринг или статическая генерация и серверные обработчики. Для нового проекта используйте Node.js 22+, актуальную структуру app/ и проверяйте команды по официальной документации Nuxt 4.