Nuxt 4 Architecture Patterns

Добавьте экспертизу Nuxt 4 в Claude Code. Реализуйте безопасную гидратацию, SSR-безопасную загрузку данных и продвинутые правила маршрутов Nitro для высокопроизводительных приложений Nuxt.

Инструменты разработчика ★ 172,008 GitHub (172,008 ★)

Nuxt 4 Patterns предоставляет Claude специализированные знания для создания, отладки и оптимизации современных приложений Nuxt. Он обеспечивает согласованность гидратации между сервером и клиентом, реализует эффективную загрузку данных с помощью useFetch и useAsyncData, а также настраивает сложные правила маршрутов Nitro, такие как SWR и ISR. Следуя этим шаблонам, разработчики могут значительно повысить производительность страниц, SEO и общую надежность своих гибридно-рендерящихся приложений, избегая распространенных ошибок, таких как несовпадение гидратации и чрезмерный размер полезной нагрузки.

Ключевые особенности

01SSR-безопасная загрузка данных с помощью useFetch и useAsyncData

02Ленивая загрузка и продвинутые стратегии ленивой гидратации

03Оптимизация размера полезной нагрузки и лучшие практики управления состоянием

04Безопасность гидратации и методы предотвращения несоответствий

05Настройка правил маршрутов Nitro для SWR, ISR и предварительного рендеринга

06172 008 звёзд на GitHub

Варианты использования

01Отладка ошибок гидратации между серверным HTML и состоянием клиента

02Реализация сложных стратегий рендеринга для блогов, каталогов и панелей управления

03Оптимизация начальной загрузки страницы с помощью интеллектуального разделения компонентов и предварительной загрузки

name	nuxt4-patterns
description	Nuxt 4 app patterns for hydration safety, performance, route rules, lazy loading, and SSR-safe data fetching with useFetch and useAsyncData.
origin	ECC

Nuxt 4 Patterns

Use when building or debugging Nuxt 4 apps with SSR, hybrid rendering, route rules, or page-level data fetching.

When to Activate

Hydration mismatches between server HTML and client state
Route-level rendering decisions such as prerender, SWR, ISR, or client-only sections
Performance work around lazy loading, lazy hydration, or payload size
Page or component data fetching with useFetch, useAsyncData, or $fetch
Nuxt routing issues tied to route params, middleware, or SSR/client differences

Hydration Safety

Keep the first render deterministic. Do not put Date.now(), Math.random(), browser-only APIs, or storage reads directly into SSR-rendered template state.
Move browser-only logic behind onMounted(), import.meta.client, ClientOnly, or a .client.vue component when the server cannot produce the same markup.
Use Nuxt's useRoute() composable, not the one from vue-router.
Do not use route.fullPath to drive SSR-rendered markup. URL fragments are client-only, which can create hydration mismatches.
Treat ssr: false as an escape hatch for truly browser-only areas, not a default fix for mismatches.

Data Fetching

Prefer await useFetch() for SSR-safe API reads in pages and components. It forwards server-fetched data into the Nuxt payload and avoids a second fetch on hydration.
Use useAsyncData() when the fetcher is not a simple $fetch() call, when you need a custom key, or when you are composing multiple async sources.
Give useAsyncData() a stable key for cache reuse and predictable refresh behavior.
Keep useAsyncData() handlers side-effect free. They can run during SSR and hydration.
Use $fetch() for user-triggered writes or client-only actions, not top-level page data that should be hydrated from SSR.
Use lazy: true, useLazyFetch(), or useLazyAsyncData() for non-critical data that should not block navigation. Handle status === 'pending' in the UI.
Use server: false only for data that is not needed for SEO or the first paint.
Trim payload size with pick and prefer shallower payloads when deep reactivity is unnecessary.

const route = useRoute()

const { data: article, status, error, refresh } = await useAsyncData(
  () => `article:${route.params.slug}`,
  () => $fetch(`/api/articles/${route.params.slug}`),
)

const { data: comments } = await useFetch(`/api/articles/${route.params.slug}/comments`, {
  lazy: true,
  server: false,
})

Route Rules

Prefer routeRules in nuxt.config.ts for rendering and caching strategy:

export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },
    '/products/**': { swr: 3600 },
    '/blog/**': { isr: true },
    '/admin/**': { ssr: false },
    '/api/**': { cache: { maxAge: 60 * 60 } },
  },
})

prerender: static HTML at build time
swr: serve cached content and revalidate in the background
isr: incremental static regeneration on supported platforms
ssr: false: client-rendered route
cache or redirect: Nitro-level response behavior

Pick route rules per route group, not globally. Marketing pages, catalogs, dashboards, and APIs usually need different strategies.

Lazy Loading and Performance

Nuxt already code-splits pages by route. Keep route boundaries meaningful before micro-optimizing component splits.
Use the Lazy prefix to dynamically import non-critical components.
Conditionally render lazy components with v-if so the chunk is not loaded until the UI actually needs it.
Use lazy hydration for below-the-fold or non-critical interactive UI.

<template>
  <LazyRecommendations v-if="showRecommendations" />
  <LazyProductGallery hydrate-on-visible />
</template>

For custom strategies, use defineLazyHydrationComponent() with a visibility or idle strategy.
Nuxt lazy hydration works on single-file components. Passing new props to a lazily hydrated component will trigger hydration immediately.
Use NuxtLink for internal navigation so Nuxt can prefetch route components and generated payloads.

Review Checklist

First SSR render and hydrated client render produce the same markup
Page data uses useFetch or useAsyncData, not top-level $fetch
Non-critical data is lazy and has explicit loading UI
Route rules match the page's SEO and freshness requirements
Heavy interactive islands are lazy-loaded or lazily hydrated

🧩 Что это

Навык Nuxt 4 Architecture Patterns — это набор проверенных практик и рекомендаций для разработки на Nuxt 4. Он помогает избежать типичных ошибок при серверном рендеринге (SSR), гибридном рендеринге, оптимизации производительности и организации получения данных. Навык ориентирован на разработчиков, которые уже знакомы с основами Nuxt и хотят глубже разобраться в тонкостях гидратации, маршрутизации, ленивой загрузки и кэширования.

⚙️ Как работает

🛡️ Безопасность гидратации (Hydration Safety)

Гидратация — это процесс, при котором Vue «оживляет» статический HTML, сгенерированный на сервере, добавляя интерактивность на клиенте. Если разметка сервера и клиента не совпадает, возникает ошибка гидратации. Чтобы её избежать:

Не используйте в шаблонах SSR значения, которые могут отличаться на сервере и клиенте: Date.now(), Math.random(), чтение localStorage, вызов browser-only API. Всё это должно быть вынесено в onMounted() или обёрнуто в ClientOnly / .client.vue компонент.
Используйте useRoute() из Nuxt, а не из vue-router. Не полагайтесь на route.fullPath в SSR-разметке — фрагменты URL (#hash) доступны только на клиенте.
Опция ssr: false — это крайнее средство для truly browser-only зон, а не универсальное решение проблем гидратации.

📦 Получение данных (Data Fetching)

Для загрузки данных на страницах и в компонентах используйте встроенные композаблы:

useFetch() — предпочтительный способ для простых API-запросов. Данные, полученные на сервере, автоматически передаются в payload и не запрашиваются повторно при гидратации.
useAsyncData() — когда нужен кастомный ключ, композиция нескольких источников или нестандартный fetcher (например, вызов GraphQL). Всегда задавайте стабильный ключ для кэширования и предсказуемого обновления.
$fetch() — используйте только для действий по инициативе пользователя (запись, отправка формы) или клиентских вызовов, не для данных, которые должны гидратироваться из SSR.
Ленивая загрузка: lazy: true, useLazyFetch(), useLazyAsyncData() — для некритичных данных, которые не должны блокировать навигацию. Обязательно обрабатывайте состояние status === 'pending' в UI.
server: false — только для данных, не нужных для SEO или первого отображения.
Уменьшайте размер payload с помощью pick и предпочитайте плоские структуры, если глубокая реактивность не требуется.

Пример типичного паттерна:

const route = useRoute()
const { data: article, status, error, refresh } = await useAsyncData(
  `article:${route.params.slug}`,
  () => $fetch(`/api/articles/${route.params.slug}`)
)
const { data: comments } = await useFetch(
  `/api/articles/${route.params.slug}/comments`,
  { lazy: true, server: false }
)

🗺️ Правила маршрутов (Route Rules)

Вместо глобальных настроек рендеринга используйте routeRules в nuxt.config.ts. Это позволяет задать стратегию для каждой группы маршрутов:

export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },
    '/products/**': { swr: 3600 },
    '/blog/**': { isr: true },
    '/admin/**': { ssr: false },
    '/api/**': { cache: { maxAge: 60 * 60 } }
  }
})

prerender — статический HTML на этапе сборки.
swr — кэшированный контент с фоновой ревалидацией.
isr — инкрементальная статическая регенерация (на поддерживаемых платформах).
ssr: false — клиентский рендеринг для данного маршрута.
cache / redirect — низкоуровневые ответы Nitro.

Подбирайте правила под тип страницы: маркетинговые, каталоги, дашборды, API — у каждого свои требования к свежести и SEO.

🚀 Ленивая загрузка и производительность

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

Префикс Lazy — динамический импорт некритичных компонентов. Используйте v-if, чтобы чанк загружался только когда UI действительно нужен.
Ленивая гидратация — для компонентов «ниже сгиба» или неинтерактивных: hydrate-on-visible, hydrate-on-idle.
defineLazyHydrationComponent() — для кастомных стратегий (видимость, бездействие).
NuxtLink — для внутренней навигации: Nuxt автоматически предзагружает компоненты маршрута и payload.

Пример:

`template`
  <LazyRecommendations v-if="showRecommendations" />
  <LazyProductGallery hydrate-on-visible />

✅ Когда использовать

Этот навык пригодится в следующих ситуациях:

Гидратационные ошибки — несоответствие HTML сервера и клиента (mismatch).
Настройка рендеринга — нужно решить, какие страницы prerender, SWR, ISR или полностью клиентские.
Оптимизация производительности — ленивая загрузка, ленивая гидратация, уменьшение размера payload.
Получение данных — выбор между useFetch, useAsyncData, $fetch, настройка кэширования и обработка состояний загрузки.
Проблемы с маршрутизацией — параметры маршрута, middleware, различия SSR/клиент.

💡 Важно знать

ssr: false — не панацея. Используйте его только для truly browser-only зон, иначе вы теряете преимущества SSR (SEO, скорость первого отображения).
Стабильные ключи для useAsyncData — обязательны для предсказуемого кэширования и обновления. Используйте шаблонные строки с параметрами маршрута.
Nuxt уже код-сплитит страницы — не создавайте микро-оптимизации до того, как убедитесь, что границы маршрутов оптимальны.
Ленивая гидратация срабатывает при передаче новых пропсов — учитывайте это при проектировании компонентов.
Правила маршрутов применяются к группам, а не глобально — это даёт гибкость и предсказуемость.

Установка одной командой.

npx skillfish add affaan-m/everything-claude-code nuxt4-patterns

Источник: https://mcpmarket.com/tools/skills/nuxt-4-architecture-patterns