Os recursos experimentais do Nuxt podem ser habilitados no arquivo de configuração do Nuxt.

Internamente, o Nuxt usa @nuxt/schema para definir esses recursos experimentais. Você pode consultar a documentação da API ou o código-fonte para mais informações.

asyncContext

Habilite o contexto assíncrono nativo para ser acessível para composables aninhados no Nuxt e no Nitro. Isso abre a possibilidade de usar composables dentro de composables assíncronos e reduz a chance de obter o erro Nuxt instance is unavailable.

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

asyncEntry

Habilita a geração de um ponto de entrada assíncrono para o pacote Vue, auxiliando o suporte à federação de módulos.

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

externalVue

Externaliza vue, @vue/* e vue-router durante a construção.

Habilitado por padrão.

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

treeshakeClientOnly

Remove o conteúdo dos componentes apenas para cliente do pacote do servidor.

Habilitado por padrão.

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

emitRouteChunkError

Emite o hook app:chunkError quando há um erro ao carregar chunks do vite/webpack. O comportamento padrão é realizar um recarregamento da nova rota na navegação para uma nova rota quando um chunk falha ao carregar.

Se você definir isso como 'automatic-immediate', o Nuxt recarregará a rota atual imediatamente, em vez de esperar por uma navegação. Isso é útil para erros de chunk que não são acionados por navegação, por exemplo, quando seu aplicativo Nuxt falha ao carregar um componente lazy. Uma desvantagem potencial desse comportamento são recarregamentos indesejados, por exemplo, quando seu aplicativo não precisa do chunk que causou o erro.

Você pode desativar o tratamento automático definindo isso como false, ou lidar com erros de chunk manualmente definindo como manual.

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

restoreState

Permite que o estado do aplicativo Nuxt seja restaurado a partir do sessionStorage ao recarregar a página após um erro de chunk ou chamada manual de reloadNuxtApp().

Para evitar erros de hidratação, ele será aplicado apenas após o aplicativo Vue ter sido montado, o que significa que pode haver um piscar na carga inicial.

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

inlineRouteRules

Defina regras de rota no nível da página usando defineRouteRules.

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

Regras de rota correspondentes serão criadas, com base no path da página.

renderJsonPayloads

Permite a renderização de payloads JSON com suporte para reviver tipos complexos.

Habilitado por padrão.

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

noVueServer

Desativa o endpoint do renderizador do servidor Vue dentro do Nitro.

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

payloadExtraction

Habilita a extração de payloads de páginas geradas com nuxt generate.

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

clientFallback

Habilita o componente experimental <NuxtClientFallback> para renderizar conteúdo no cliente se houver um erro no SSR.

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

crossOriginPrefetch

Habilita o prefetch cross-origin usando a API de Regras de Especulação.

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

viewTransition

Habilita a integração da API de Transição de Visualização com o roteador do lado do cliente.

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

writeEarlyHints

Habilita a escrita de dicas antecipadas ao usar o servidor node.

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

componentIslands

Habilita o suporte experimental a ilhas de componentes com <NuxtIsland> e arquivos .island.vue.

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

configSchema

Habilita o suporte ao esquema de configuração.

Habilitado por padrão.

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

polyfillVueUseHead

Adiciona uma camada de compatibilidade para módulos, plugins ou código do usuário que dependem da antiga API @vueuse/head.

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

respectNoSSRHeader

Permite desativar respostas SSR do Nuxt definindo o cabeçalho x-nuxt-no-ssr.

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

localLayerAliases

Resolve aliases ~, ~~, @ e @@ localizados dentro de camadas em relação às suas fontes e diretórios raiz.

Habilitado por padrão.

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

typedPages

Habilite o novo roteador tipado experimental usando unplugin-vue-router.

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

Pronto para uso, isso habilitará o uso tipado de navigateTo, <NuxtLink>, router.push() e mais.

Você pode até obter parâmetros tipados dentro de uma página usando const route = useRoute('route-name').

watcher

Defina um observador alternativo que será usado como o serviço de observação para o Nuxt.

O Nuxt usa chokidar-granular por padrão, que ignorará diretórios de nível superior (como node_modules e .git) que são excluídos da observação.

Você pode definir isso como parcel para usar @parcel/watcher, o que pode melhorar o desempenho em projetos grandes ou em plataformas Windows.

Você também pode definir isso como chokidar para observar todos os arquivos no seu diretório de origem.

export default defineNuxtConfig({
  experimental: {
    watcher: 'chokidar-granular' // 'chokidar' ou 'parcel' também são opções
  }
})

sharedPrerenderData

Habilitar este recurso compartilha automaticamente os dados de payload entre páginas que são pré-renderizadas. Isso pode resultar em uma melhoria significativa de desempenho ao pré-renderizar sites que usam useAsyncData ou useFetch e buscam os mesmos dados em diferentes páginas.

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

É particularmente importante ao habilitar este recurso garantir que qualquer chave única dos seus dados seja sempre resolvível para os mesmos dados. Por exemplo, se você estiver usando useAsyncData para buscar dados relacionados a uma página específica, você deve fornecer uma chave que corresponda exclusivamente a esses dados. (useFetch deve fazer isso automaticamente para você.)

// Isso seria inseguro em uma página dinâmica (por exemplo, `[slug].vue`) porque o slug da rota faz diferença
// para os dados buscados, mas o Nuxt não pode saber disso porque não está refletido na chave.
const route = useRoute()
const { data } = await useAsyncData(async () => {
  return await $fetch(`/api/my-page/${route.params.slug}`)
})
// Em vez disso, você deve usar uma chave que identifique exclusivamente os dados buscados.
const { data } = await useAsyncData(route.params.slug, async () => {
  return await $fetch(`/api/my-page/${route.params.slug}`)
})

clientNodeCompat

Com este recurso, o Nuxt preencherá automaticamente as importações do Node.js na construção do cliente usando unenv.

import { Buffer } from 'node:buffer'

globalThis.Buffer = globalThis.Buffer || Buffer

scanPageMeta

Esta opção permite expor alguns metadados de rota definidos em definePageMeta em tempo de construção para módulos (especificamente alias, name, path, redirect, props e middleware).

Isso só funciona com strings/arrays estáticos em vez de variáveis ou atribuição condicional. Veja issue original para mais informações e contexto.

Também é possível escanear metadados de página apenas após todas as rotas terem sido registradas em pages:extend. Então, outro hook, pages:resolved será chamado. Para habilitar esse comportamento, defina scanPageMeta: 'after-resolve'.

Você pode desativar esse recurso se ele causar problemas em seu projeto.

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

cookieStore

Habilita o suporte ao CookieStore para ouvir atualizações de cookies (se suportado pelo navegador) e atualizar valores de referência useCookie.

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

buildCache

Armazena em cache artefatos de construção do Nuxt com base em um hash da configuração e dos arquivos de origem.

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

Quando habilitado, alterações nos seguintes arquivos acionarão uma reconstrução completa:

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

Além disso, quaisquer alterações em arquivos dentro de srcDir acionarão uma reconstrução do pacote cliente/servidor Vue. O Nitro sempre será reconstruído (embora o trabalho esteja em andamento para permitir que o Nitro anuncie seus artefatos em cache e seus hashes).

extraPageMetaExtractionKeys

O macro definePageMeta() é uma maneira útil de coletar metadados de construção sobre páginas. O próprio Nuxt fornece uma lista definida de chaves suportadas que é usada para alimentar alguns dos recursos internos, como redirecionamentos, aliases de página e caminhos personalizados.

Esta opção permite passar chaves adicionais para extrair dos metadados da página ao usar scanPageMeta.

definePageMeta({
  foo: 'bar'
})

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

Isso permite que módulos acessem metadados adicionais dos metadados da página no contexto de construção. Se você estiver usando isso dentro de um módulo, é recomendado também aumentar os tipos NuxtPage com suas chaves.

normalizeComponentNames

Garante que os nomes dos componentes Vue gerados automaticamente correspondam ao nome completo do componente que você usaria para importar automaticamente o componente.

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

Por padrão, se você não definiu manualmente, o Vue atribuirá um nome de componente que corresponde ao nome do arquivo do componente.

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

Neste caso, o nome do componente seria MyComponent, no que diz respeito ao Vue. Se você quisesse usar <KeepAlive> com ele, ou identificá-lo nas DevTools do Vue, você precisaria usar este componente.

Mas para importá-lo automaticamente, você precisaria usar SomeFolderMyComponent.

Ao definir experimental.normalizeComponentNames, esses dois valores correspondem, e o Vue gerará um nome de componente que corresponde ao padrão Nuxt para nomeação de componentes.

spaLoadingTemplateLocation

Ao renderizar uma página apenas para cliente (com ssr: false), opcionalmente renderizamos uma tela de carregamento (de app/spa-loading-template.html).

Pode ser definido como within, que o renderizará assim:

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

Alternativamente, você pode renderizar o template ao lado da raiz do aplicativo Nuxt definindo-o como body:

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

Isso evita um flash branco ao hidratar uma página apenas para cliente.

browserDevtoolsTiming

Habilita marcadores de desempenho para hooks do Nuxt nas devtools do navegador. Isso adiciona marcadores de desempenho que você pode rastrear na aba de Desempenho de navegadores baseados em Chromium, o que é útil para depurar e otimizar o desempenho.

Isso é habilitado por padrão no modo de desenvolvimento. Se você precisar desativar esse recurso, é possível fazê-lo:

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

debugModuleMutation

Registra mutações em nuxt.options no contexto do módulo, ajudando a depurar alterações de configuração feitas por módulos durante a fase de inicialização do Nuxt.

Isso é habilitado por padrão quando o modo debug está ativado. Se você precisar desativar esse recurso, é possível fazê-lo:

Para habilitá-lo explicitamente:

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

lazyHydration

Isso habilita estratégias de hidratação para componentes <Lazy>, o que melhora o desempenho adiando a hidratação dos componentes até que sejam necessários.

A hidratação lazy é habilitada por padrão, mas você pode desativar esse recurso:

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

templateImportResolution

Controla como as importações em templates do Nuxt são resolvidas. Por padrão, o Nuxt tenta resolver importações em templates relativas ao módulo que as adicionou.

Isso é habilitado por padrão, então se você estiver enfrentando conflitos de resolução em certos ambientes, você pode desativar esse comportamento:

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

decorators

Esta opção habilita a sintaxe de decoradores em todo o seu aplicativo Nuxt/Nitro, alimentado por esbuild.

Por muito tempo, o TypeScript teve suporte para decoradores via compilerOptions.experimentalDecorators. Esta implementação precedeu o processo de padronização do TC39. Agora, os decoradores são uma Proposta de Estágio 3, e suportados sem configuração especial no TS 5.0+ (veja https://github.com/microsoft/TypeScript/pull/52582 e https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#decorators).

Habilitar experimental.decorators habilita o suporte para a proposta TC39, NÃO para a implementação anterior compilerOptions.experimentalDecorators do 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()
// isso retornará 'decorated'

purgeCachedData

O Nuxt purgará automaticamente dados em cache de useAsyncData e nuxtApp.static.data. Isso ajuda a prevenir vazamentos de memória e garante que dados frescos sejam carregados quando necessário, mas é possível desativá-lo:

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

granularCachedData

Se deve chamar e usar o resultado de getCachedData ao atualizar dados para useAsyncData e useFetch (seja por watch, refreshNuxtData(), ou uma chamada manual de refresh()).

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

pendingWhenIdle

Se definido como false, o objeto pending retornado de useAsyncData, useFetch, useLazyAsyncData e useLazyFetch será uma propriedade computada que é true apenas quando status também está pendente.

Isso significa que quando immediate: false é passado, pending será false até que a primeira solicitação seja feita.

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