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

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

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

asyncContext

В Nuxt и Nitro включена возможность доступа к нативному async-контексту для вложенных композаблов. Это открывает возможность использовать композаблы внутри async-композаблов и снижает вероятность получения ошибки 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: true
  }
})

emitRouteChunkError

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

Если вы установите для этого параметра значение 'automatic-immediate', Nuxt немедленно перезагрузит текущий маршрут, вместо того чтобы ждать перехода. Это полезно при ошибках чанков, которые не вызваны навигацией, например, когда приложению Nuxt не удается загрузить ленивый компонент. Потенциальным недостатком такого поведения является нежелательная перезагрузка, например, когда приложению не нужен фрагмент, вызвавший ошибку.

Вы можете отключить автоматическую обработку, установив значение false, или обрабатывать ошибки чанков вручную, установив значение manual.

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

restoreState

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

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

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

inlineRouteRules

Определите правила маршрута на уровне страницы с помощью defineRouteRules.

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

На основе path страницы будут созданы соответствующие правила маршрутизации.

renderJsonPayloads

Позволяет рендерить полезную нагрузку JSON с поддержкой обновления сложных типов.

Включена по умолчанию.

export default defineNuxtConfig({
  experimental: {
    renderJsonPayloads: true
  }
})

noVueServer

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

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

payloadExtraction

Позволяет извлекать полезную нагрузку страниц, сгенерированных с помощью nuxt generate.

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

clientFallback

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

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

crossOriginPrefetch

Включает cross-origin предварительную загрузку с помощью API Speculation Rules.

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

viewTransition

Включает интеграцию View Transition API с маршрутизатором на стороне клиента.

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

writeEarlyHints

Включает запись ранних подсказок при использовании 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: true
  }
})

typedPages

Включите новый экспериментальный типизированный маршрутизатор с помощью unplugin-vue-router.

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

Из коробки это позволит использовать navigateTo, <NuxtLink>, router.push() и многое другое.

Вы даже можете получить типизированные параметры внутри страницы, используя const route = useRoute('route-name').

watcher

Установите альтернативный watcher, который будет использоваться в качестве watching-сервиса для Nuxt.

По умолчанию Nuxt использует chokidar-granular, который будет игнорировать каталоги верхнего уровня (например, node_modules и .git), которые исключены из просмотра.

Вместо этого параметра можно установить значение parcel, чтобы использовать @parcel/watcher, что может улучшить производительность в больших проектах или на платформах Windows.

Вы также можете установить значение chokidar, чтобы следить за всеми файлами в вашем каталоге исходных текстов.

export default defineNuxtConfig({
  experimental: {
    watcher: 'chokidar-granular' // 'chokidar' или 'parcel' также можно использовать
  }
})

sharedPrerenderData

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

export default defineNuxtConfig({
  experimental: {
    sharedPrerenderData: true
  }
})

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

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

clientNodeCompat

С помощью этой функции Nuxt будет автоматически полифиллить импорты Node.js в клиентской сборке, используя unenv.

import { Buffer } from 'node:buffer'

globalThis.Buffer = globalThis.Buffer || Buffer

scanPageMeta

Эта опция позволяет раскрывать некоторые метаданные маршрута, определенные в definePageMeta, во время сборки для модулей (в частности, alias, name, path, redirect, props and middleware).

Это работает только со статическими данными или строками/массивами, а не с переменными или условными присваиваниями. Дополнительную информацию и контекст см. в оригинальном issue.

Также возможно сканировать метаданные страницы только после того, как все маршруты зарегистрированы в pages:extend. Затем будет вызван другой хук, pages:resolved. Чтобы включить это поведение, установите scanPageMeta: 'after-resolve'.

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

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

cookieStore

Включает поддержку CookieStore для прослушивания обновлений cookie (если это поддерживается браузером) и обновления значений useCookie.

export default defineNuxtConfig({
  experimental: {
    cookieStore: true
  }
})

buildCache

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

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 мог объявлять свои кэшируемые артефакты и их хэши).

extraPageMetaExtractionKeys

The definePageMeta() macro is a useful way to collect build-time meta about pages. Nuxt itself provides a set list of supported keys which is used to power some of the internal features such as redirects, page aliases and custom paths.

This option allows passing additional keys to extract from the page metadata when using scanPageMeta.

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

export default defineNuxtConfig({
  experimental: {
    extraPageMetaExtractionKeys: ['foo'],
  },
  hooks: {
    'pages:resolved' (ctx) {
      // ✅ foo is available
    },
  },
})

This allows modules to access additional metadata from the page metadata in the build context. If you are using this within a module, it's recommended also to augment the NuxtPage types with your keys.

normalizeComponentNames

Убедитесь, что автогенерируемые имена компонентов Vue совпадают с полным именем компонента, которое вы используете для автоимпорта компонента.

export default defineNuxtConfig({
  experimental: {
    normalizeComponentNames: true
  }
})

По умолчанию, если вы не задали это вручную, Vue присвоит компоненту имя, соответствующее имени файла компонента.

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

Что касается Vue, в этом случае имя компонента будет MyComponent. Если бы вы хотели использовать с ним <KeepAlive> или идентифицировать его во Vue DevTools, вам нужно было бы использовать это имя.

Но чтобы автоимпортировать его, вам нужно использовать SomeFolderMyComponent.

Если установить experimental.normalizeComponentNames, эти два значения совпадут, и Vue сгенерирует имя компонента, соответствующее паттерну Nuxt для именования компонентов.

spaLoadingTemplateLocation

When rendering a client-only page (with ssr: false), we optionally render a loading screen (from app/spa-loading-template.html).

It can be set to within, which will render it like this:

<div id="__nuxt">
  <!-- spa loading template -->
</div>

Alternatively, you can render the template alongside the Nuxt app root by setting it to body:

<div id="__nuxt"></div>
<!-- spa loading template -->

This avoids a white flash when hydrating a client-only page.

browserDevtoolsTiming

Enables performance markers for Nuxt hooks in browser devtools. This adds performance markers that you can track in the Performance tab of Chromium-based browsers, which is useful for debugging and optimizing performance.

This is enabled by default in development mode. If you need to disable this feature, it is possible to do so:

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

debugModuleMutation

Records mutations to nuxt.options in module context, helping to debug configuration changes made by modules during the Nuxt initialization phase.

This is enabled by default when debug mode is enabled. If you need to disable this feature, it is possible to do so:

To enable it explicitly:

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

lazyHydration

This enables hydration strategies for <Lazy> components, which improves performance by deferring hydration of components until they're needed.

Lazy hydration is enabled by default, but you can disable this feature:

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

templateImportResolution

Controls how imports in Nuxt templates are resolved. By default, Nuxt attempts to resolve imports in templates relative to the module that added them.

This is enabled by default, so if you're experiencing resolution conflicts in certain environments, you can disable this behavior:

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

decorators

This option enables enabling decorator syntax across your entire Nuxt/Nitro app, powered by esbuild.

For a long time, TypeScript has had support for decorators via compilerOptions.experimentalDecorators. This implementation predated the TC39 standardization process. Now, decorators are a Stage 3 Proposal, and supported without special configuration in TS 5.0+ (see https://github.com/microsoft/TypeScript/pull/52582 and https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#decorators).

Enabling experimental.decorators enables support for the TC39 proposal, NOT for TypeScript's previous compilerOptions.experimentalDecorators implementation.

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()
// this will return 'decorated'

purgeCachedData

Nuxt will automatically purge cached data from useAsyncData and nuxtApp.static.data. This helps prevent memory leaks and ensures fresh data is loaded when needed, but it is possible to disable it:

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

granularCachedData

Whether to call and use the result from getCachedData when refreshing data for useAsyncData and useFetch (whether by watch, refreshNuxtData(), or a manual refresh() call.

export default defineNuxtConfig({
  experimental: {
    granularCachedData: true
  }
})

pendingWhenIdle

If set to false, the pending object returned from useAsyncData, useFetch, useLazyAsyncData and useLazyFetch will be a computed property that is true only when status is also pending.

That means that when immediate: false is passed, pending will be false until the first request is made.

export default defineNuxtConfig({
  experimental: {
    pendingWhenIdle: false
  }
})