Экспериментальные возможности

Экспериментальные возможности Nuxt можно включить в конфигурационном файле.

Внутри Nuxt использует @nuxt/schema для определения этих опций. Подробнее — в документации API и в исходном коде.

alwaysRunFetchOnKeyChange

Запускать ли useFetch при смене ключа, даже если задано immediate: false и запрос ещё не выполнялся.

useFetch и useAsyncData при смене ключа всегда выполняются, если immediate: true или запрос уже был запущен.

По умолчанию флаг выключен; при необходимости его можно включить:

export default defineNuxtConfig({
  experimental: {
    alwaysRunFetchOnKeyChange: true,
  },
})

appManifest

Использовать манифесты приложения, чтобы на клиенте учитывать правила маршрутов.

По умолчанию включено; при необходимости можно отключить:

export default defineNuxtConfig({
  experimental: {
    appManifest: false,
  },
})

asyncContext

Включает нативный асинхронный контекст для вложенных композаблов в Nuxt и Nitro. Так можно вызывать композаблы из асинхронных композаблов и реже получать ошибку «Nuxt instance is unavailable».

export default defineNuxtConfig({
  experimental: {
    asyncContext: true,
  },
})

asyncEntry

Генерация асинхронной точки входа для пакета Vue — помогает при поддержке федерации модулей.

export default defineNuxtConfig({
  experimental: {
    asyncEntry: true,
  },
})

externalVue

Выносит vue, @vue/* и vue-router наружу при сборке.

По умолчанию включено; при необходимости можно отключить:

export default defineNuxtConfig({
  experimental: {
    externalVue: false,
  },
})

extractAsyncDataHandlers

Выносит функции-обработчики из вызовов useAsyncData и useLazyAsyncData в отдельные чанки для лучшего code splitting и кэширования.

export default defineNuxtConfig({
  experimental: {
    extractAsyncDataHandlers: true,
  },
})

Встроенные обработчики превращаются в динамически импортируемые чанки:

<!-- До -->
<script setup>
const { data } = await useAsyncData('user', async () => {
  return await $fetch('/api/user')
})
</script>

<!-- После преобразования -->
<script setup>
const { data } = await useAsyncData('user', () =>
  import('/generated-chunk.js').then(r => r.default()),
)
</script>

Так логику получения данных можно вынести в отдельный чанк, при этом код подгрузится при необходимости.

emitRouteChunkError

Вызывает хук app:chunkError при ошибке загрузки чанков Vite/webpack. По умолчанию Nuxt перезагружает новый маршрут при навигации, если чанк не загрузился.

Также по умолчанию выполняется перезагрузка нового маршрута при ошибке чанка при переходе (automatic).

Значение automatic-immediate перезагружает текущий маршрут сразу при ошибке чанка (без ожидания навигации). Это удобно, когда ошибка не связана с переходом, например если не загрузился ленивый компонент. Минус — возможны лишние перезагрузки, если приложению не нужен проблемный чанк.

Автообработку можно отключить (false) или обрабатывать вручную (manual).

export default defineNuxtConfig({
  experimental: {
    emitRouteChunkError: 'automatic', // или 'automatic-immediate', 'manual' или false
  },
})

enforceModuleCompatibility

Должен ли Nuxt выбрасывать ошибку (и не загружаться), если модуль несовместим.

По умолчанию выключено.

export default defineNuxtConfig({
  experimental: {
    enforceModuleCompatibility: true,
  },
})

restoreState

Позволяет восстанавливать состояние приложения из sessionStorage после перезагрузки из-за ошибки чанка или вызова reloadNuxtApp().

Чтобы не ломать гидратацию, применяется только после монтирования Vue-приложения — возможно мерцание при первой загрузке.

export default defineNuxtConfig({
  experimental: {
    restoreState: true,
  },
})

inlineRouteRules

Задаёт правила маршрута на уровне страницы через defineRouteRules.

export default defineNuxtConfig({
  experimental: {
    inlineRouteRules: true,
  },
})

Соответствующие правила строятся по path страницы.

renderJsonPayloads

Рендер JSON payload с поддержкой восстановления сложных типов.

По умолчанию включено; при необходимости можно отключить:

export default defineNuxtConfig({
  experimental: {
    renderJsonPayloads: false,
  },
})

noVueServer

Отключает эндпоинт серверного рендера Vue в Nitro.

export default defineNuxtConfig({
  experimental: {
    noVueServer: true,
  },
})

parseErrorData

Парсить ли error.data при отрисовке серверной страницы ошибки.

По умолчанию включено; при необходимости можно отключить:

export default defineNuxtConfig({
  experimental: {
    parseErrorData: false,
  },
})

payloadExtraction

Извлечение payload страниц, сгенерированных через nuxt generate.

export default defineNuxtConfig({
  experimental: {
    payloadExtraction: true,
  },
})

Извлечение payload работает и для маршрутов с ISR (Incremental Static Regeneration) или SWR (Stale-While-Revalidate): CDN могут кэшировать файлы payload вместе с HTML, что ускоряет клиентскую навигацию по кэшированным маршрутам.

export default defineNuxtConfig({
  experimental: {
    payloadExtraction: true,
  },
  routeRules: {
    // Для этих кэшируемых маршрутов будут сгенерированы файлы payload
    '/products/**': { isr: 3600 },
    '/blog/**': { swr: true },
  },
})

clientFallback

Включает экспериментальный <NuxtClientFallback> для рендера на клиенте при ошибке SSR.

export default defineNuxtConfig({
  experimental: {
    clientFallback: true,
  },
})

crossOriginPrefetch

Предзагрузка с другого origin через Speculation Rules API.

export default defineNuxtConfig({
  experimental: {
    crossOriginPrefetch: true,
  },
})

viewTransition

Интеграция View Transition API с клиентским роутером.

export default defineNuxtConfig({
  experimental: {
    viewTransition: true,
  },
})

writeEarlyHints

Запись early hints при использовании node-сервера.

export default defineNuxtConfig({
  experimental: {
    writeEarlyHints: true,
  },
})

componentIslands

Экспериментальные островные компоненты: <NuxtIsland> и файлы .island.vue.

export default defineNuxtConfig({
  experimental: {
    componentIslands: true, // false или 'local+remote'
  },
})

localLayerAliases

Разрешает алиасы ~, ~~, @ и @@ внутри слоёв относительно корня и исходников слоя.

По умолчанию включено; при необходимости можно отключить:

export default defineNuxtConfig({
  experimental: {
    localLayerAliases: false,
  },
})

typedPages

Экспериментальный типизированный роутер на базе unplugin-vue-router.

export default defineNuxtConfig({
  experimental: {
    typedPages: true,
  },
})

Из коробки типизируются navigateTo, <NuxtLink>, router.push() и другое.

Типизированные параметры на странице: const route = useRoute('route-name').

publicHoistPattern:
  - "unplugin-vue-router"

watcher

Альтернативный watcher для сервиса отслеживания файлов Nuxt.

По умолчанию — chokidar-granular: игнорируются верхнеуровневые каталоги вроде node_modules и .git, исключённые из наблюдения.

Можно указать parcel для @parcel/watcher — часто быстрее на больших проектах или Windows.

Или chokidar, чтобы следить за всеми файлами в srcDir.

export default defineNuxtConfig({
  experimental: {
    watcher: 'chokidar-granular', // также 'chokidar' или 'parcel'
  },
})

sharedPrerenderData

Nuxt автоматически разделяет данные payload между пререндеренными страницами — заметный выигрыш, если на разных страницах useAsyncData / useFetch запрашивают одно и то же.

При необходимости функцию можно отключить.

export default defineNuxtConfig({
  experimental: {
    sharedPrerenderData: false,
  },
})

Важно, чтобы уникальный ключ данных всегда однозначно соответствовал одним и тем же данным. Например, для данных страницы задайте ключ, отражающий эти данные (useFetch сделает это сам).

// Небезопасно на динамической странице (например `[slug].vue`): slug влияет на данные,
// но Nuxt не видит этого, если ключ это не отражает.
const route = useRoute()
const { data } = await useAsyncData(async (_nuxtApp, { signal }) => {
  return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
})
// Нужен ключ, однозначно идентифицирующий загружаемые данные.
const { data } = await useAsyncData(route.params.slug, async (_nuxtApp, { signal }) => {
  return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
})

clientNodeCompat

Nuxt автоматически полифиллит импорты Node.js в клиентской сборке через unenv.

import { Buffer } from 'node:buffer'

globalThis.Buffer ||= Buffer

scanPageMeta

Раскрывает часть метаданных маршрута из definePageMeta на этапе сборки для модулей: alias, name, path, redirect, props, middleware.

Работает со статическими значениями, строками и массивами, не с переменными и условными присваиваниями. Контекст — в исходной задаче.

По умолчанию метаданные сканируются после регистрации всех маршрутов в pages:extend, затем вызывается хук pages:resolved.

При проблемах в проекте функцию можно отключить.

export default defineNuxtConfig({
  experimental: {
    scanPageMeta: false,
  },
})

cookieStore

Поддержка CookieStore: слушать обновления cookie (если браузер поддерживает) и обновлять ref из useCookie.

По умолчанию включено; при необходимости можно отключить:

export default defineNuxtConfig({
  experimental: {
    cookieStore: false,
  },
})

buildCache

Кэширует артефакты сборки Nuxt по хэшу конфигурации и исходников.

Учитываются исходники в пределах srcDir и serverDir для частей Vue/Nitro.

По умолчанию выключено; включение:

export default defineNuxtConfig({
  experimental: {
    buildCache: true,
  },
})

При включении изменения в перечисленных файлах вызывают полную пересборку:

.nuxtrc
.npmrc
package.json
package-lock.json
yarn.lock
pnpm-lock.yaml
tsconfig.json
bun.lock
bun.lockb

Любые изменения в srcDir пересобирают клиентский и серверный Vue-бандлы. Nitro всегда пересобирается (ведётся работа над кэшируемыми артефактами Nitro и их хэшами).

checkOutdatedBuildInterval

Интервал (мс) проверки наличия новой сборки. Не используется, если experimental.appManifest равен false.

Значение false отключает проверку.

export default defineNuxtConfig({
  experimental: {
    checkOutdatedBuildInterval: 3600000, // 1 час, или false
  },
})

extraPageMetaExtractionKeys

Макрос definePageMeta() собирает метаданные страниц на сборке. У Nuxt фиксированный набор ключей для редиректов, алиасов и пользовательских путей.

Эта опция задаёт дополнительные ключи для извлечения при scanPageMeta.

<script lang="ts" setup>
definePageMeta({
  foo: 'bar',
})
</script>

export default defineNuxtConfig({
  experimental: {
    extraPageMetaExtractionKeys: ['foo'],
  },
  hooks: {
    'pages:resolved' (ctx) {
      // ✅ foo доступен
    },
  },
})

Так модули читают дополнительные метаданные из definePageMeta на сборке. В модуле имеет смысл расширить типы NuxtPage.

navigationRepaint

Ждать один кадр анимации перед навигацией, чтобы браузер успел перерисовать интерфейс после действия пользователя.

Может снизить INP на пререндеренных маршрутах.

По умолчанию включено; при необходимости можно отключить:

export default defineNuxtConfig({
  experimental: {
    navigationRepaint: false,
  },
})

normalizeComponentNames

Nuxt подстраивает автогенерируемые имена компонентов Vue под полное имя, как при автоимпорте.

При проблемах функцию можно отключить.

export default defineNuxtConfig({
  experimental: {
    normalizeComponentNames: false,
  },
})

Если имя не задано вручную, Vue берёт имя из файла компонента.

├─ components/
├─── SomeFolder/
├───── MyComponent.vue

Для Vue имя компонента — MyComponent (<KeepAlive>, DevTools). Для автоимпорта нужно SomeFolderMyComponent.

С experimental.normalizeComponentNames эти значения совпадают, и имя соответствует схеме именования Nuxt.

spaLoadingTemplateLocation

Для клиент-only страницы (ssr: false) опционально показывается экран загрузки из ~/spa-loading-template.html.

within вставляет шаблон так:

<div id="__nuxt">
  <!-- шаблон загрузки SPA -->
</div>

body — шаблон рядом с корнем приложения:

<div id="__nuxt"></div>
<!-- шаблон загрузки SPA -->

Снижает белую вспышку при гидратации клиент-only страницы.

browserDevtoolsTiming

Маркеры производительности для хуков Nuxt в инструментах разработчика: вкладка «Производительность» в Chromium — удобно для отладки.

В режиме разработки по умолчанию включено; при необходимости отключите:

export default defineNuxtConfig({
  experimental: {
    browserDevtoolsTiming: false,
  },
})

debugModuleMutation

Логирует изменения nuxt.options в контексте модулей — помогает отлаживать правки конфигурации при инициализации.

По умолчанию включено вместе с debug; при необходимости отключите.

Явное включение:

export default defineNuxtConfig({
  experimental: {
    debugModuleMutation: true,
  },
})

lazyHydration

Стратегии гидратации для <Lazy>: откладывают гидратацию до момента, когда компонент реально нужен.

По умолчанию включено; при необходимости отключите:

export default defineNuxtConfig({
  experimental: {
    lazyHydration: false,
  },
})

templateImportResolution

Отключает разрешение импортов в шаблонах Nuxt относительно модуля, добавившего шаблон.

По умолчанию Nuxt разрешает импорты в шаблонах относительно этого модуля. false отключает поведение — полезно при конфликтах разрешения.

По умолчанию включено; при необходимости отключите:

export default defineNuxtConfig({
  experimental: {
    templateImportResolution: false,
  },
})

templateRouteInjection

Объект маршрута из автоимпортируемого useRoute() синхронизирован с текущей страницей в <NuxtPage>. Это не так для экспортируемого vue-router useRoute и для $route в шаблонах.

При включении опции подмешивается mixin, чтобы объект $route в шаблоне совпадал с управляемым Nuxt useRoute().

По умолчанию включено; при необходимости отключите:

export default defineNuxtConfig({
  experimental: {
    templateRouteInjection: false,
  },
})

decorators

Синтаксис декораторов во всём приложении Nuxt/Nitro на базе esbuild.

Раньше TypeScript поддерживал декораторы через compilerOptions.experimentalDecorators — до стандартизации TC39. Сейчас декораторы — предложение Stage 3, в TS 5.0+ без отдельной настройки (см. https://github.com/microsoft/TypeScript/pull/52582 и https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#decorators).

experimental.decorators включает предложение TC39, а не старую реализацию compilerOptions.experimentalDecorators.

Usage

export default defineNuxtConfig({
  experimental: {
    decorators: true,
  },
})

function something (_method: () => unknown) {
  return () => 'decorated'
}

class SomeClass {
  @something
  public someMethod () {
    return 'initial'
  }
}

const value = new SomeClass().someMethod()
// вернёт 'decorated'

defaults

Значения по умолчанию для ключевых компонентов и композаблов Nuxt.

В будущем, вероятно, переедут, например, в app.config или каталог app/.

export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        componentName: 'NuxtLink',
        prefetch: true,
        prefetchOn: {
          visibility: true,
        },
      },
      useAsyncData: {
        deep: true,
      },
    },
  },
})

purgeCachedData

Очищать ли статические кэши Nuxt и asyncData при навигации по маршрутам.

Nuxt очищает кэш useAsyncData и nuxtApp.static.data — меньше утечек памяти и актуальнее данные; при необходимости отключите.

По умолчанию включено; при необходимости отключите:

export default defineNuxtConfig({
  experimental: {
    purgeCachedData: false,
  },
})

granularCachedData

Вызывать ли и использовать ли результат getCachedData при обновлении данных в useAsyncData и useFetch (через watch, refreshNuxtData() или ручной refresh()).

По умолчанию включено; при необходимости отключите:

export default defineNuxtConfig({
  experimental: {
    granularCachedData: false,
  },
})

headNext

Оптимизации <head>:

• плагин capo.js для более эффективного порядка тегов в <head>
• плагин hash hydration для меньшей нагрузки при первой гидратации

По умолчанию включено; при необходимости отключите:

export default defineNuxtConfig({
  experimental: {
    headNext: false,
  },
})

pendingWhenIdle

Для useAsyncData и useFetch: должен ли pending быть true, пока запрос данных ещё не начался.

По умолчанию выключено; включение:

export default defineNuxtConfig({
  experimental: {
    pendingWhenIdle: true,
  },
})

entryImportMap

По умолчанию Nuxt стабилизирует чанки через import map для entry-чанда.

В начало <head> вставляется import map:

<script type="importmap">{"imports":{"#entry":"/_nuxt/DC5HVSK5.js"}}</script>

В чанках скриптов от Vite импорты идут из #entry: смена entry не инвалидирует остальные неизменённые чанки.

Отключение вручную:

export default defineNuxtConfig({
  experimental: {
    entryImportMap: false,
  },
  // лучше задать целевой браузер для Vite — Nuxt учтёт это
  vite: {
    build: {
      target: 'safari13',
    },
  },
})

typescriptPlugin

Расширенный опыт разработки на TypeScript с модулем @dxup/nuxt.

Улучшенная интеграция TypeScript и инструменты для DX в Nuxt-приложениях.

По умолчанию выключено; включение:

export default defineNuxtConfig({
  experimental: {
    typescriptPlugin: true,
  },
})

viteEnvironmentApi

Environment API Vite 6 для конфигурации сборки и архитектуры плагинов.

При future.compatibilityVersion: 5 включено по умолчанию; можно включить явно для проверки:

export default defineNuxtConfig({
  experimental: {
    viteEnvironmentApi: true,
  },
})

Environment API даёт согласованность dev/prod, точнее настраивает окружения и улучшает производительность.