Las características experimentales de Nuxt se pueden habilitar en el archivo de configuración de Nuxt.

Internamente, Nuxt utiliza @nuxt/schema para definir estas características experimentales. Puedes consultar la documentación de la API o el código fuente para más información.

asyncContext

Habilita el contexto asíncrono nativo para que sea accesible para composables anidados en Nuxt y en Nitro. Esto abre la posibilidad de usar composables dentro de composables asíncronos y reduce la posibilidad de obtener el error Nuxt instance is unavailable.

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

asyncEntry

Habilita la generación de un punto de entrada asíncrono para el paquete de Vue, ayudando al soporte de federación de módulos.

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

externalVue

Externaliza vue, @vue/* y vue-router al construir.

Habilitado por defecto.

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

treeshakeClientOnly

Elimina del paquete del servidor los contenidos de los componentes solo para cliente.

Habilitado por defecto.

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

emitRouteChunkError

Emite el hook app:chunkError cuando hay un error al cargar fragmentos de vite/webpack. El comportamiento predeterminado es realizar una recarga de la nueva ruta al navegar a una nueva ruta cuando un fragmento no se carga.

Si configuras esto como 'automatic-immediate', Nuxt recargará la ruta actual inmediatamente, en lugar de esperar una navegación. Esto es útil para errores de fragmentos que no son provocados por la navegación, por ejemplo, cuando tu aplicación Nuxt no puede cargar un componente perezoso. Un posible inconveniente de este comportamiento son las recargas no deseadas, por ejemplo, cuando tu aplicación no necesita el fragmento que causó el error.

Puedes deshabilitar el manejo automático configurándolo como false, o manejar los errores de fragmentos manualmente configurándolo como manual.

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

restoreState

Permite que el estado de la aplicación Nuxt se restaure desde sessionStorage al recargar la página después de un error de fragmento o una llamada manual a reloadNuxtApp().

Para evitar errores de hidratación, se aplicará solo después de que la aplicación Vue haya sido montada, lo que significa que puede haber un parpadeo en la carga inicial.

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

inlineRouteRules

Define reglas de ruta a nivel de página usando defineRouteRules.

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

Se crearán reglas de ruta coincidentes, basadas en el path de la página.

renderJsonPayloads

Permite la representación de cargas útiles JSON con soporte para revivir tipos complejos.

Habilitado por defecto.

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

noVueServer

Desactiva el endpoint del renderizador del servidor Vue dentro de Nitro.

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

payloadExtraction

Habilita la extracción de cargas útiles de páginas generadas con nuxt generate.

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

clientFallback

Habilita el componente experimental <NuxtClientFallback> para renderizar contenido en el cliente si hay un error en SSR.

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

crossOriginPrefetch

Habilita la precarga de origen cruzado usando la API de Reglas de Especulación.

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

viewTransition

Habilita la integración de la API de Transición de Vista con el enrutador del lado del cliente.

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

writeEarlyHints

Habilita la escritura de pistas tempranas al usar el servidor node.

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

componentIslands

Habilita el soporte experimental de islas de componentes con <NuxtIsland> y archivos .island.vue.

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

configSchema

Habilita el soporte de esquema de configuración.

Habilitado por defecto.

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

polyfillVueUseHead

Agrega una capa de compatibilidad para módulos, plugins o código de usuario que dependa de la antigua API @vueuse/head.

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

respectNoSSRHeader

Permite deshabilitar las respuestas SSR de Nuxt configurando el encabezado x-nuxt-no-ssr.

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

localLayerAliases

Resuelve los alias ~, ~~, @ y @@ ubicados dentro de capas con respecto a sus directorios de origen y raíz.

Habilitado por defecto.

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

typedPages

Habilita el nuevo enrutador tipado experimental usando unplugin-vue-router.

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

De forma predeterminada, esto habilitará el uso tipado de navigateTo, <NuxtLink>, router.push() y más.

Incluso puedes obtener parámetros tipados dentro de una página usando const route = useRoute('route-name').

watcher

Configura un observador alternativo que se usará como el servicio de observación para Nuxt.

Nuxt usa chokidar-granular por defecto, que ignorará directorios de nivel superior (como node_modules y .git) que están excluidos de la observación.

Puedes configurar esto en su lugar a parcel para usar @parcel/watcher, lo que puede mejorar el rendimiento en proyectos grandes o en plataformas Windows.

También puedes configurarlo a chokidar para observar todos los archivos en tu directorio fuente.

export default defineNuxtConfig({
  experimental: {
    watcher: 'chokidar-granular' // 'chokidar' o 'parcel' también son opciones
  }
})

sharedPrerenderData

Habilitar esta característica comparte automáticamente los datos de carga entre páginas que son prerenderizadas. Esto puede resultar en una mejora significativa del rendimiento al prerenderizar sitios que usan useAsyncData o useFetch y obtienen los mismos datos en diferentes páginas.

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

Es particularmente importante al habilitar esta característica asegurarse de que cualquier clave única de tus datos siempre sea resoluble a los mismos datos. Por ejemplo, si estás usando useAsyncData para obtener datos relacionados con una página en particular, deberías proporcionar una clave que coincida de manera única con esos datos. (useFetch debería hacer esto automáticamente por ti.)

// Esto sería inseguro en una página dinámica (por ejemplo, `[slug].vue`) porque el slug de la ruta hace una diferencia
// en los datos obtenidos, pero Nuxt no puede saber eso porque no se refleja en la clave.
const route = useRoute()
const { data } = await useAsyncData(async () => {
  return await $fetch(`/api/my-page/${route.params.slug}`)
})
// En su lugar, deberías usar una clave que identifique de manera única los datos obtenidos.
const { data } = await useAsyncData(route.params.slug, async () => {
  return await $fetch(`/api/my-page/${route.params.slug}`)
})

clientNodeCompat

Con esta característica, Nuxt rellenará automáticamente las importaciones de Node.js en la compilación del cliente usando unenv.

import { Buffer } from 'node:buffer'

globalThis.Buffer = globalThis.Buffer || Buffer

scanPageMeta

Esta opción permite exponer algunos metadatos de ruta definidos en definePageMeta en tiempo de compilación a módulos (específicamente alias, name, path, redirect, props y middleware).

Esto solo funciona con cadenas o arreglos estáticos en lugar de variables o asignación condicional. Consulta el problema original para más información y contexto.

También es posible escanear metadatos de página solo después de que todas las rutas hayan sido registradas en pages:extend. Luego se llamará a otro hook, pages:resolved. Para habilitar este comportamiento, configura scanPageMeta: 'after-resolve'.

Puedes deshabilitar esta característica si causa problemas en tu proyecto.

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

cookieStore

Habilita el soporte de CookieStore para escuchar actualizaciones de cookies (si es compatible con el navegador) y actualizar los valores de referencia de useCookie.

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

buildCache

Almacena en caché los artefactos de compilación de Nuxt basados en un hash de la configuración y los archivos fuente.

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

Cuando está habilitado, los cambios en los siguientes archivos desencadenarán una reconstrucción completa:

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

Además, cualquier cambio en los archivos dentro de srcDir desencadenará una reconstrucción del paquete cliente/servidor de Vue. Nitro siempre se reconstruirá (aunque se está trabajando para permitir que Nitro anuncie sus artefactos almacenables en caché y sus hashes).

extraPageMetaExtractionKeys

El macro definePageMeta() es una forma útil de recopilar metadatos de compilación sobre las páginas. Nuxt en sí proporciona una lista establecida de claves compatibles que se utiliza para potenciar algunas de las características internas como redirecciones, alias de página y rutas personalizadas.

Esta opción permite pasar claves adicionales para extraer de los metadatos de la página al usar scanPageMeta.

definePageMeta({
  foo: 'bar'
})

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

Esto permite a los módulos acceder a metadatos adicionales de los metadatos de la página en el contexto de compilación. Si estás usando esto dentro de un módulo, se recomienda también aumentar los tipos NuxtPage con tus claves.

normalizeComponentNames

Asegura que los nombres de componentes Vue generados automáticamente coincidan con el nombre completo del componente que usarías para importar automáticamente el componente.

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

Por defecto, si no lo has configurado manualmente, Vue asignará un nombre de componente que coincida con el nombre del archivo del componente.

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

En este caso, el nombre del componente sería MyComponent, en lo que respecta a Vue. Si quisieras usar <KeepAlive> con él, o identificarlo en las DevTools de Vue, necesitarías usar este componente.

Pero para importarlo automáticamente, necesitarías usar SomeFolderMyComponent.

Al configurar experimental.normalizeComponentNames, estos dos valores coinciden, y Vue generará un nombre de componente que coincida con el patrón de Nuxt para nombrar componentes.

spaLoadingTemplateLocation

Al renderizar una página solo para cliente (con ssr: false), opcionalmente renderizamos una pantalla de carga (desde app/spa-loading-template.html).

Se puede configurar a within, lo que lo renderizará así:

<div id="__nuxt">
  <!-- plantilla de carga spa -->
</div>

Alternativamente, puedes renderizar la plantilla junto al raíz de la aplicación Nuxt configurándolo a body:

<div id="__nuxt"></div>
<!-- plantilla de carga spa -->

Esto evita un destello blanco al hidratar una página solo para cliente.

browserDevtoolsTiming

Habilita marcadores de rendimiento para hooks de Nuxt en las herramientas de desarrollo del navegador. Esto agrega marcadores de rendimiento que puedes rastrear en la pestaña de Rendimiento de navegadores basados en Chromium, lo cual es útil para depurar y optimizar el rendimiento.

Esto está habilitado por defecto en modo de desarrollo. Si necesitas deshabilitar esta característica, es posible hacerlo:

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

debugModuleMutation

Registra mutaciones a nuxt.options en el contexto del módulo, ayudando a depurar cambios de configuración realizados por módulos durante la fase de inicialización de Nuxt.

Esto está habilitado por defecto cuando el modo debug está habilitado. Si necesitas deshabilitar esta característica, es posible hacerlo:

Para habilitarlo explícitamente:

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

lazyHydration

Esto habilita estrategias de hidratación para componentes <Lazy>, lo que mejora el rendimiento al diferir la hidratación de componentes hasta que sean necesarios.

La hidratación perezosa está habilitada por defecto, pero puedes deshabilitar esta característica:

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

templateImportResolution

Controla cómo se resuelven las importaciones en las plantillas de Nuxt. Por defecto, Nuxt intenta resolver las importaciones en plantillas relativas al módulo que las agregó.

Esto está habilitado por defecto, por lo que si estás experimentando conflictos de resolución en ciertos entornos, puedes deshabilitar este comportamiento:

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

decorators

Esta opción habilita la sintaxis de decoradores en toda tu aplicación Nuxt/Nitro, impulsada por esbuild.

Durante mucho tiempo, TypeScript ha tenido soporte para decoradores a través de compilerOptions.experimentalDecorators. Esta implementación precedió al proceso de estandarización de TC39. Ahora, los decoradores son una Propuesta de Etapa 3, y son compatibles sin configuración especial en TS 5.0+ (ver https://github.com/microsoft/TypeScript/pull/52582 y https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#decorators).

Habilitar experimental.decorators habilita el soporte para la propuesta de TC39, NO para la implementación anterior de compilerOptions.experimentalDecorators de TypeScript.

Uso

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

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

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

const value = new SomeClass().someMethod()
// esto devolverá 'decorated'

purgeCachedData

Nuxt purgará automáticamente los datos en caché de useAsyncData y nuxtApp.static.data. Esto ayuda a prevenir fugas de memoria y asegura que se carguen datos frescos cuando sea necesario, pero es posible deshabilitarlo:

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

granularCachedData

Si se debe llamar y usar el resultado de getCachedData al actualizar datos para useAsyncData y useFetch (ya sea por watch, refreshNuxtData(), o una llamada manual a refresh()).

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

pendingWhenIdle

Si se establece en false, el objeto pending devuelto por useAsyncData, useFetch, useLazyAsyncData y useLazyFetch será una propiedad computada que es true solo cuando status también está pendiente.

Eso significa que cuando se pasa immediate: false, pending será false hasta que se realice la primera solicitud.

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