Van Nuxt 3 naar Nuxt 4: wat verandert er?

Een nieuwe hoofdversie klinkt als veel werk. Bij Nuxt 4 valt dat mee: de meeste verschillen zijn klein. Een paar raken wel bijna elke site. Dit zijn ze, en dit is de volgorde waarin ik upgrade.

De map app/

Je code staat nu standaard in de map app/: pages, components, composables, layouts, middleware, plugins en app.vue. De mappen server/, public/ en shared/ blijven in de root.

Je hoeft niet meteen te verhuizen. Heeft je project geen map app/, dan gebruikt Nuxt de oude indeling. Verhuis je wel, let dan op de alias ~. Die wijst daarna naar app/, dus een import als ~/server/utils werkt niet meer.

Data ophalen werkt anders

Hier zit de meeste kans op fouten. Vier dingen veranderen in useAsyncData en useFetch:

• Aanroepen met dezelfde key delen nu dezelfde data, error en status. Geef ze dan ook dezelfde opties, zoals transform en deep.
• data is een shallowRef. Vervang je het hele object, dan werkt alles zoals eerst. Pas je iets diep in de data aan, zoals data.value.items.push(), dan ververst je scherm niet meer. Wil je dat toch, zet dan deep: true.
• data en error beginnen als undefined, niet meer als null. Een check als data.value === null is daarna nooit meer waar.
• Verdwijnt het laatste component dat de data gebruikt, dan ruimt Nuxt die data op. Komt het component terug, dan wordt de data opnieuw opgehaald.

Tags in je head

Unhead, dat de tags in je head maakt, is nu versie 2. Oude opties als hid, vmid en children zijn weg. Zoek ze op in je project voordat je upgradet.

In deze volgorde upgrade ik

1. Zet Nuxt 3 en je modules op de laatste versie. Los eerst de waarschuwingen op die er nu al zijn.
2. Zet alvast future: { compatibilityVersion: 4 } in je config. Dat kan vanaf Nuxt 3.12. Je draait dan met het gedrag van Nuxt 4, maar kunt nog terug.
3. Test de pagina’s die data ophalen. Zoek in je code op === null, op .push( en op keys die je op meer plekken gebruikt.
4. Upgrade met npx nuxt upgrade --dedupe. Wat overblijft, pakt de codemod op: npx codemod@latest nuxt/4/migration-recipe.
5. Verhuis als laatste naar app/, in een aparte commit. Dan staan in die diff alleen verplaatste bestanden.

Zit je daarna op Nuxt 4.2 of hoger, dan werkt dezelfde truc voor de volgende versie. Met compatibilityVersion: 5 test je nu al wat Nuxt 5 verandert.