Nuxt 4 nel 2026: nuova struttura di directory e migrazione da Nuxt 3

Nuxt 4 rappresenta il più significativo aggiornamento del framework Vue.js dalla versione 3, introducendo una nuova struttura di directory, miglioramenti alla reattività e un sistema di tipi più rigoroso. Con il rilascio stabile nel 2026, il framework punta a semplificare lo sviluppo di applicazioni moderne senza sacrificare la retrocompatibilità. Questa guida analizza ogni novità rilevante e fornisce un percorso di migrazione concreto da Nuxt 3.

La nuova struttura di directory: la cartella app/

Il cambiamento più visibile in Nuxt 4 è la riorganizzazione della struttura del progetto. Tutto il codice relativo all'applicazione client — componenti, pagine, composables, middleware — viene ora raggruppato all'interno di una cartella app/ dedicata, separando nettamente il codice applicativo dalla configurazione e dal codice server.

my-nuxt-app/
├─ app/
│  ├─ assets/
│  ├─ components/
│  ├─ composables/
│  ├─ layouts/
│  ├─ middleware/
│  ├─ pages/
│  ├─ plugins/
│  ├─ utils/
│  ├─ app.vue
│  ├─ app.config.ts
│  └─ error.vue
├─ content/
├─ public/
├─ shared/
├─ server/
└─ nuxt.config.ts

Questa ristrutturazione non è puramente estetica. La separazione tra app/, server/ e shared/ porta vantaggi concreti in termini di manutenibilità del progetto. Il codice condiviso tra client e server trova posto nella cartella shared/, eliminando ambiguità su dove posizionare utility e tipi utilizzati in entrambi i contesti. Per chi lavora su progetti di grandi dimensioni, questa organizzazione riduce significativamente il rischio di importare accidentalmente codice server nel bundle client.

Migrazione da Nuxt 3: il percorso pratico

La migrazione a Nuxt 4 inizia con l'aggiornamento del framework all'ultima versione disponibile. Il comando dedicato gestisce automaticamente le dipendenze e la deduplica dei pacchetti:

npx nuxt upgrade --dedupe

Per la ristrutturazione dei file, il team Nuxt ha predisposto un codemod ufficiale che automatizza lo spostamento dei file nella nuova struttura:

npx codemod@latest nuxt/4/file-structure

Il codemod sposta automaticamente componenti, pagine, composables e gli altri file applicativi nella cartella app/, aggiornando i percorsi di importazione dove necessario. Per i progetti che necessitano di mantenere temporaneamente la struttura precedente, è possibile configurare esplicitamente il comportamento:

export default defineNuxtConfig({
  srcDir: '.',
  dir: { app: 'app' },
})

Questa configurazione consente un periodo di transizione in cui la struttura legacy rimane funzionante mentre il team adotta progressivamente il nuovo layout. È comunque consigliato completare la migrazione il prima possibile per beneficiare di tutti i miglioramenti del framework.

Data fetching e caching evoluto

Il sistema di data fetching in Nuxt 4 introduce miglioramenti sostanziali alla gestione della cache. La nuova API getCachedData offre un controllo granulare su quando i dati devono essere recuperati nuovamente e quando è possibile servire la versione in cache.

export function useProductData(productId: string) {
  return useAsyncData(
    `product-${productId}`,
    () => $fetch(`/api/products/${productId}`),
    {
      getCachedData: (key, nuxtApp, ctx) => {
        if (ctx.cause === 'refresh:manual') return undefined
        return nuxtApp.payload.data[key]
      },
    },
  )
}

Il parametro ctx.cause fornisce informazioni sul motivo per cui è stata richiesta una nuova fetch: navigazione, refresh manuale o idratazione. Questo permette di implementare strategie di caching sofisticate — ad esempio, servire sempre dati dalla cache durante la navigazione ma forzare un refresh quando l'utente esegue un pull-to-refresh. Per chi si prepara a domande di colloquio Vue/Nuxt, comprendere queste meccaniche di caching rappresenta un argomento sempre più rilevante.

Reattività shallow: prestazioni migliorate di default

Nuxt 4 adotta la reattività shallow come comportamento predefinito per useAsyncData e useFetch. In pratica, solo il livello superiore dell'oggetto restituito è reattivo, evitando il costo computazionale della conversione profonda che in Nuxt 3 veniva applicata a ogni proprietà annidata.

<script setup lang="ts">
const { data: metrics } = await useFetch('/api/dashboard/metrics')
metrics.value = { ...metrics.value, visits: 100 }
const { data: settings } = await useFetch('/api/settings', {
  deep: true,
})
</script>

Con la reattività shallow, la sostituzione dell'intero valore tramite spread operator ({ ...metrics.value, visits: 100 }) è il pattern corretto per aggiornare i dati. Per i casi in cui la reattività profonda è effettivamente necessaria — ad esempio per form complessi con binding bidirezionale su proprietà annidate — l'opzione deep: true la riattiva esplicitamente. Questa modifica porta miglioramenti misurabili nelle applicazioni con grandi volumi di dati, riducendo il carico sul sistema di reattività di Vue.

Sistema di tipi TypeScript rinnovato

Nuxt 4 introduce un sistema TypeScript basato su project references, suddividendo la configurazione in contesti separati per app, server, shared e node. Questa separazione garantisce che il type-checking sia più preciso e che il codice server non possa accidentalmente accedere a tipi esclusivi del client, e viceversa.

{
  "files": [],
  "references": [
    { "path": "./.nuxt/tsconfig.app.json" },
    { "path": "./.nuxt/tsconfig.server.json" },
    { "path": "./.nuxt/tsconfig.shared.json" },
    { "path": "./.nuxt/tsconfig.node.json" }
  ]
}

Per eseguire il type-checking in modo coerente con questa nuova struttura, il comando cambia rispetto a Nuxt 3:

nuxt prepare && vue-tsc -b --noEmit

Il flag -b attiva la modalità build di TypeScript, che rispetta i project references e verifica ciascun contesto separatamente. Questo approccio intercetta errori che in precedenza sfuggivano al controllo — come l'utilizzo di document in un composable condiviso che viene eseguito anche server-side. Per approfondire il rendering server-side e le sue implicazioni, la guida SSR e generazione statica fornisce un contesto complementare.

Gestione avanzata del keep-alive

Il componente NuxtPage in Nuxt 4 offre un supporto più maturo per KeepAlive, consentendo di specificare esattamente quali componenti devono mantenere il proprio stato durante la navigazione:

<!-- app/pages/dashboard.vue -->
<template>
  <NuxtPage :keepalive="{
    include: ['DashboardMetricsCard', 'DashboardRecentActivity'],
  }" />
</template>

Invece di mantenere in memoria tutte le pagine visitate, è possibile definire una lista esplicita di componenti da preservare. Questa granularità è particolarmente utile nelle dashboard con widget che eseguono fetch costosi: i dati rimangono in memoria durante la navigazione tra le sottopagine, senza dover ricaricare tutto a ogni cambio di rotta. Al contempo, le pagine non incluse nella lista vengono correttamente distrutte, liberando risorse.

SEO e Unhead v2

La gestione dei meta tag evolve con l'integrazione di Unhead v2, che adotta un approccio basato su getter reattivi anziché su valori calcolati (computed). Questo modello risulta più esplicito e prevedibile:

<script setup lang="ts">
const route = useRoute()
const { data: product } = await useFetch(`/api/products/${route.params.id}`)
useSeoMeta({
  title: () => product.value?.name ?? 'Product',
  ogTitle: () => product.value?.name ?? 'Product',
  description: () => product.value?.description ?? '',
  ogImage: () => product.value?.imageUrl ?? '',
})
</script>

I getter (arrow function) garantiscono che i meta tag si aggiornino automaticamente quando i dati del prodotto vengono caricati, senza bisogno di watcher espliciti. Unhead v2, inoltre, rimuove alcuni plugin dal bundle di default per ridurre le dimensioni. Per riattivare funzionalità come il template params o l'ordinamento degli alias, è necessario registrare i plugin manualmente:

import { TemplateParamsPlugin, AliasSortingPlugin } from '@unhead/vue/plugins'
export default defineNuxtPlugin({
  setup() {
    const unhead = injectHead()
    unhead.use(TemplateParamsPlugin)
    unhead.use(AliasSortingPlugin)
  },
})

Questa modifica segue il principio di opt-in: ogni funzionalità aggiuntiva viene inclusa esplicitamente, mantenendo il bundle base il più leggero possibile.

Flag di compatibilità e migrazione graduale

Nuxt 4 non richiede un aggiornamento "tutto o niente". Il framework mette a disposizione un sistema di flag di compatibilità nel file nuxt.config.ts che permette di attivare singolarmente i nuovi comportamenti. La strategia consigliata prevede di:

1. Aggiornare Nuxt 3 all'ultima versione minor disponibile.
2. Attivare i flag di compatibilità uno alla volta, verificando che l'applicazione funzioni correttamente dopo ciascuno.
3. Eseguire il codemod per la ristrutturazione dei file.
4. Aggiornare la configurazione TypeScript ai project references.
5. Verificare il type-checking con vue-tsc -b.

Questo approccio incrementale riduce drasticamente il rischio di regressioni e permette ai team di distribuire il lavoro di migrazione su più sprint. Ogni flag può essere testato in isolamento, rendendo il debugging molto più semplice rispetto a una migrazione monolitica.

Conclusione

Nuxt 4 consolida la direzione intrapresa con Nuxt 3, portando a maturazione concetti come la separazione dei contesti, la reattività ottimizzata e il type-checking rigoroso. La nuova struttura di directory con la cartella app/ non è solo un cambiamento organizzativo: è il fondamento per un'architettura più scalabile e manutenibile. Grazie al sistema di flag di compatibilità e ai codemod ufficiali, la migrazione da Nuxt 3 può avvenire in modo graduale e controllato, senza interruzioni al flusso di lavoro del team. Per chi costruisce applicazioni Vue.js di produzione, l'adozione di Nuxt 4 rappresenta un investimento sulla qualità e sulla longevità del codice.