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

> Analisi approfondita delle novità di Nuxt 4 nel 2026: struttura app/, data fetching con cache evoluto, reattività shallow, TypeScript rigoroso e guida alla migrazione graduale da Nuxt 3.

- Published: 2026-05-01
- Updated: 2026-05-01
- Author: SharpSkill
- Tags: nuxt, vue, migration, typescript, tutorial
- Reading time: 10 min

---

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.

> **Migrazione automatizzata disponibile**
>
> Nuxt 4 è progettato per essere adottato gradualmente: la maggior parte delle modifiche può essere attivata già in Nuxt 3.x tramite flag di compatibilità, permettendo una transizione progressiva senza riscritture complete.

## 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.

```text
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:

```bash
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:

```bash
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:

```typescript
// nuxt.config.ts
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.

```typescript
// app/composables/useProductData.ts
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](/technologies/vue-nuxt/interview-questions/nuxt-fundamentals), 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.

```typescript
// app/pages/dashboard.vue
<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.

```json
{
  "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:

```bash
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](/blog/vue-nuxt/nuxt-3-ssr-static-generation) 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:

```vue
<!-- 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:

```typescript
// app/pages/product/[id].vue
<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:

```typescript
// app/plugins/unhead.ts
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.

> **Supporto per Nuxt 3**
>
> Nuxt 3 continua a ricevere aggiornamenti di sicurezza e correzioni critiche fino al 31 luglio 2026. Dopo tale data, Nuxt 3 diventerà non supportato. Pianificare la migrazione in anticipo evita di mantenere applicazioni in produzione su un framework a fine vita.

## 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.

---

Source: SharpSkill (https://sharpskill.dev), tech interview preparation for your real stack.
HTML version of this page: https://sharpskill.dev/it/blog/vue-nuxt/nuxt-4-directory-structure-migration