Nuxt 4 in 2026: Nieuwe Directorystructuur en Migratie vanuit Nuxt 3

Nuxt 4 markeert een belangrijk keerpunt in de evolutie van het Vue.js-ecosysteem. Na jaren van iteratieve verbeteringen introduceert deze major release een fundamenteel herziene directorystructuur, verbeterde TypeScript-integratie en een gestroomlijnde developer experience. Voor ontwikkelteams die momenteel Nuxt 3 in productie draaien, brengt de migratie naar Nuxt 4 zowel kansen als uitdagingen met zich mee. Dit artikel biedt een diepgaande analyse van alle belangrijke wijzigingen, de nieuwe mappenstructuur en een praktische migratiegids om de overstap zo soepel mogelijk te laten verlopen.

De nieuwe directorystructuur van Nuxt 4

De meest zichtbare verandering in Nuxt 4 is de introductie van een dedicated app/-directory. Waar Nuxt 3 alle applicatiecode in de root van het project plaatste, scheidt Nuxt 4 client-side applicatiecode expliciet van serverconfiguratie, gedeelde utilities en publieke assets. Deze architecturale beslissing verbetert de leesbaarheid van grote projecten aanzienlijk en maakt de scheiding tussen server- en clientcode onmiskenbaar.

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

De shared/-directory is een volledig nieuwe toevoeging. Deze map biedt een plek voor code die zowel door de client als de server wordt gebruikt, denk aan types, constanten en validatieschema's. In Nuxt 3 was het gebruikelijk om dergelijke gedeelde code in de root te plaatsen of te dupliceren tussen client en server. Nuxt 4 lost dit probleem structureel op.

De server/-directory behoudt zijn positie buiten de app/-map, wat de architecturale grens tussen frontend en backend benadrukt. API-routes, server-middleware en database-interacties blijven hier georganiseerd.

Migratie starten: van Nuxt 3 naar Nuxt 4

Het migratieproces begint met het upgraden van de Nuxt-dependency naar de nieuwste versie. Het Nuxt-team heeft een dedicated upgrade-commando beschikbaar gesteld dat niet alleen de dependency bijwerkt, maar ook deduplicatie van afhankelijkheden uitvoert om versieconflicten te voorkomen.

npx nuxt upgrade --dedupe

Na de upgrade kan de automatische codemod worden uitgevoerd om de bestandsstructuur aan te passen aan de nieuwe conventies. Deze codemod verplaatst bestanden naar de juiste locaties binnen de nieuwe app/-directory en past imports dienovereenkomstig aan.

npx codemod@latest nuxt/4/file-structure

De codemod behandelt het zware werk, maar handmatige controle blijft noodzakelijk. Aangepaste pad-aliassen, dynamische imports en configuratiebestanden vereisen mogelijk handmatige aanpassingen. Het is raadzaam om na het uitvoeren van de codemod het project grondig te testen en alle gebroken imports te herstellen.

Voor teams die de migratie geleidelijk willen uitvoeren, biedt Nuxt 4 een configuratieoptie om de nieuwe directorystructuur te activeren zonder alle bestanden direct te verplaatsen.

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

Deze configuratie stelt ontwikkelaars in staat om de nieuwe structuur stap voor stap te adopteren, wat het risico op regressies minimaliseert bij grotere codebases.

Data fetching en caching: de getCachedData-verbetering

Nuxt 4 introduceert verfijnde controle over data caching via de getCachedData-callback. Deze functie ontvangt nu een extra ctx-parameter die informatie bevat over de reden van de data-aanvraag. Hiermee kunnen ontwikkelaars onderscheid maken tussen navigatie, handmatige refreshes en initialisatie, en per scenario bepalen of gecachte data moet worden geretourneerd of verse data moet worden opgehaald.

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]
      },
    },
  )
}

In het bovenstaande voorbeeld wordt gecachte data geretourneerd voor normale navigatie, maar bij een handmatige refresh (bijvoorbeeld via refreshNuxtData()) wordt altijd verse data opgehaald. Dit patroon is bijzonder waardevol voor dashboards en real-time toepassingen waar gebruikers expliciete controle over dataverversing verwachten.

Shallow reactivity als standaard

Een subtiele maar impactvolle wijziging in Nuxt 4 is de overstap naar shallow reactivity als standaard voor useAsyncData en useFetch. In Nuxt 3 waren de geretourneerde data-objecten standaard deep reactive, wat betekende dat elke geneste eigenschap automatisch reactief werd. Dit gedrag veroorzaakte onnodige re-renders en geheugenoverhead bij grote datasets.

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

Met shallow reactivity moet het gehele object worden vervangen om een reactieve update te triggeren, in plaats van individuele properties aan te passen. Voor scenario's waar deep reactivity nodig is, kan de deep: true-optie expliciet worden meegegeven. Deze wijziging dwingt ontwikkelaars om bewustere keuzes te maken over reactivity-patronen en resulteert in betere performance bij de meeste use cases.

TypeScript-integratie en project references

Nuxt 4 herdefinieert de TypeScript-configuratie door gebruik te maken van project references. In plaats van een monolithisch tsconfig.json-bestand genereert Nuxt nu aparte configuraties voor app-, server-, shared- en node-contexten. Dit resulteert in nauwkeurigere type-checking per context en voorkomt dat server-types per ongeluk beschikbaar zijn in clientcode.

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

De type-checking workflow verandert eveneens. Het vue-tsc-commando werkt nu in build-modus, wat snellere incrementele type-checks mogelijk maakt bij grotere projecten.

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

Ontwikkelteams die CI/CD-pipelines gebruiken, dienen deze wijziging door te voeren in hun buildscripts. De -b-vlag activeert de build-modus van TypeScript, die optimaal gebruik maakt van project references voor parallelle type-checking.

KeepAlive en componentcaching

De <NuxtPage>-component ondersteunt in Nuxt 4 een verbeterde keepalive-configuratie. Ontwikkelaars kunnen nu specifiek aangeven welke componenten in het geheugen bewaard moeten blijven bij routewisselingen, in plaats van alle of geen componenten te cachen.

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

Dit selectieve caching-mechanisme is vooral waardevol voor dashboardapplicaties waar bepaalde secties dure API-calls maken die niet bij elke navigatie herhaald hoeven te worden, terwijl andere secties altijd verse data moeten tonen.

SEO-optimalisatie met Unhead v2

Nuxt 4 integreert Unhead v2, een ingrijpende update van de head-managementbibliotheek. De belangrijkste verandering is dat head-plugins niet langer automatisch worden geladen. Ontwikkelaars moeten nu expliciet kiezen welke plugins ze willen gebruiken, wat de bundelgrootte verkleint voor projecten die geen geavanceerde head-features nodig hebben.

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

De useSeoMeta-composable accepteert nu getter-functies als waarden, waardoor meta-tags automatisch worden bijgewerkt wanneer de onderliggende data verandert. Dit is een verbetering ten opzichte van Nuxt 3, waar handmatige watchers nodig waren voor dynamische meta-tags.

Voor projecten die template-parameters of alias-sorting nodig hebben, moeten de bijbehorende plugins handmatig worden geregistreerd via een Nuxt-plugin.

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

Breaking changes en aandachtspunten

Naast de directorystructuur bevat Nuxt 4 diverse breaking changes die aandacht vereisen tijdens de migratie. De <NuxtLink>-component verwijdert de trailing slash standaard niet meer, wat gevolgen kan hebben voor SEO-configuraties die afhankelijk zijn van consistente URL-patronen. Ontwikkelaars moeten hun routeRules herzien om ongewenste duplicatie van pagina's te voorkomen.

De standaard errorhandling is eveneens gewijzigd. In Nuxt 3 werden bepaalde fouten stilzwijgend afgevangen, terwijl Nuxt 4 strenger omgaat met onafgevangen errors in composables en middleware. Dit kan leiden tot nieuwe foutmeldingen in bestaande code die eerder probleemloos leek te functioneren.

Modules die afhankelijk zijn van interne Nuxt-API's moeten mogelijk worden bijgewerkt. Het Nuxt-team publiceert een compatibiliteitsmatrix voor populaire modules, maar minder bekende of interne modules vereisen handmatige controle.

Voor teams die hun kennis van het Nuxt-ecosysteem willen verdiepen, biedt de Vue/Nuxt-interviewvragen sectie uitgebreide oefenvragen die ook de Nuxt 4-concepten behandelen. Daarnaast geeft de SSR- en statische generatiegids waardevolle context over rendering-strategieën die direct van toepassing zijn op Nuxt 4.

Conclusie

Nuxt 4 vertegenwoordigt een doordachte evolutie van het framework die de nadruk legt op schaalbaarheid, performance en developer experience. De nieuwe directorystructuur met de app/- en shared/-mappen brengt een welkome organisatorische verbetering voor middelgrote tot grote projecten. De verschuiving naar shallow reactivity als standaard, verbeterde TypeScript-ondersteuning via project references en de granulaire caching-mogelijkheden via getCachedData maken het framework klaar voor de eisen van moderne webapplicaties in 2026. Dankzij de geleidelijke migratiepaden en automatische codemods kunnen ontwikkelteams de overstap plannen op een tempo dat past bij hun projectcyclus, zonder de druk van een alles-of-niets-migratie.