Nuxt 4 (2026): Yeni Dizin Yapisi ve Nuxt 3'ten Gecis Rehberi

Nuxt 4, Vue tabanli web uygulamalarinin mimarisinde kokllu degisiklikler getirmektedir. Yeni app/ dizin yapisi, tekil veri cekme katmani, varsayilan yuzeysel reaktivite ve bolunmus TypeScript baglami gibi yenilikler, gelistirici ekiplerinden bilinclil bir gecis stratejisi gerektirmektedir. Vue ve Nuxt ekosisteminde calisan profesyoneller icin bu degisikliklerin derinlemesine anlasilmasi, hem gunluk gelistirme sureclerinde hem de teknik mulakat hazirliklarinda buyuk onem tasimaktadir. Bu makale, Nuxt 4'teki her kritik degisikligi ele almakta, pratik kod ornekleri sunmakta ve Nuxt 3'ten gecis icin kapsamli bir kontrol listesi saglamaktadir.

Yeni app/ Dizin Yapisi

Nuxt 4'teki en belirgin degisiklik, tum istemci ve sunucu tarafli uygulama dosyalarinin ozel bir app/ dizinine tasinmasidir. Nuxt 3'te bilesenler, sayfalar, layout'lar, middleware ve plugin'ler dogrudan proje kokunde yer almaktaydi. Nuxt 4 ise uygulama kodunu yapilandirma dosyalarindan, genel kaynaklardan ve sunucu kodundan net bir sekilde ayirmaktadir.

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

Yeni eklenen shared/ dizini, mimarinin onemli bir tamamlayicisidir. Bu dizin, uygulama kodu (app/) ile sunucu kodu (server/) arasinda tip tanimlari, yardimci fonksiyonlar ve sabitlerin paylasilmasina olanak tanir. Nuxt 3'te gelistiriciler, tip tanimlarini her iki tarafta da tekrarlamak veya goreli import yollariyla gecici cozumler uretmek durumundaydi. shared/ dizini bu sorunu yapisal duzeyde cozmekte ve paylasilan kod icin tek bir kaynak noktasi saglamaktadir.

nuxt.config.ts dosyasi proje kokunde kalmaya devam etmekte olup app/ dizinine tasinmamaktadir. Benzer sekilde server/ ve public/ dizinleri de mevcut konumlarini korumaktadir. Bu ayrim, sorumluluk alanlarini net bir sekilde tanimlamaktadir: app/ tarayicida ve SSR sunucusunda islenen kodu icerir, server/ arka uc mantigini barindiri ve shared/ bu iki katman arasinda kopru gorevi gorur.

Nuxt 3'ten Adim Adim Gecis

Nuxt 3'ten Nuxt 4'e gecis sureci birkac asamadan olusmaktadir. Ilk adim, framework'un en son surume guncellenmesi ve bagimliliklarin tekillestirilmesidir.

# Upgrade Nuxt and deduplicate dependencies
npx nuxt upgrade --dedupe

Ardindan resmi codemod calistirilarak dosya yapisi yeni standarda uygun olarak otomatik olarak yeniden duzenlenir. Codemod, dosyalari app/ dizinine tasir, import yollarini gunceller ve yapilandirmayi uyarlar.

# Automate the directory restructuring
npx codemod@latest nuxt/4/file-structure

Yeni dizin yapisina hemen gecemeyen projeler icin Nuxt 4, geriye donuk uyumluluk secenegi sunmaktadir. Yapilandirmada srcDir ve dir.app degerlerinin ayarlanmasi, kademeli gecis sirasinda duz yapinin korunmasina imkan tanir.

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

Ancak bu fallback secenegi gecici bir cozumdur. Nuxt ekibi, app/ dizin yapisina tam gecisi acikca onermektedir; cunku gelecek framework surumleri bu duzene gore optimize edilecektir. Bunun otesinde, Nuxt DevTools ve topluluk modulleri gibi ekosistem araclari da yeni yapiyi varsayilan olarak kabul etmeye baslamistir.

Tekil Veri Cekme Katmani ve Reaktif Anahtarlar

Nuxt 4, useAsyncData ve useFetch composable'larinin calisma seklinde temelden bir degisiklik getirmektedir. Nuxt 3'te ayni veri anahtarinin farkli bilesenlerden cagirilmasi, mukerrer ag isteklerine ve durum tutarsizliklarina yol acabiliyordu. Nuxt 4 ise tekil (singleton) deseni uygulamaktadir: her benzersiz veri anahtari, veriyi kullanan bilesen sayisindan bagimsiz olarak tam olarak bir veri cekme ornegine baglanir.

Buna ek olarak useAsyncData, yeniden cagirma nedenini bildiren bir ctx baglam nesnesiyle birlikte yeni bir getCachedData parametresi almaktadir. Bu sayede onbellek verilerinin ne zaman kullanilacagi ve ne zaman yeni bir istek gerekecegi konusunda hassas kontrol saglanmaktadir.

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

ctx.cause parametresi 'refresh:manual' (gelistiricinin tetikledigi manuel yenileme), 'refresh:hook' (yasam dongusu hook'u tarafindan tetiklenen yenileme) veya 'navigation' (sayfalar arasi gezinme) gibi degerler alabilmektedir. Bu sayede composable, onbellekleme stratejisi hakkinda akilli kararlar verebilir: ornegin gezinme sirasinda her zaman onbellegi kullanmak, ancak manuel yenilemede yeni bir istek zorlamak mumkun hale gelmektedir.

Tekil desen ayni zamanda yaris kosullarini (race conditions) da ortadan kaldirmaktadir. Birden fazla bilesen ayni anda ayni verileri talep ettiginde, Nuxt 4 yalnizca tek bir istek gerceklestirir ve sonucu tum abonelere dagitir. Bu yaklasim ag yukunu azaltmakta ve uygulama genelinde veri tutarliligini saglamaktadir.

Varsayilan Yuzeysel Reaktivite (Shallow Reactivity)

Nuxt 4'teki en etkili degisikliklerden biri, useAsyncData ve useFetch tarafindan dondurulsn verilerde varsayilan olarak yuzeysel reaktiviteye (shallowRef) gecilmesidir. Nuxt 3'te veriler derin reaktivite (ref) ile sarmalanmaktaydi; bu da bir nesnenin ic ice gecmis ozelliklerindeki her degisikligin otomatik olarak bilesen guncellemelerini tetiklemesi anlamina geliyordu. Nuxt 4'te ise yalnizca value degerinin tamamen degistirilmesi yeniden render'a neden olmaktadir.

<script setup lang="ts">
// Data is now a shallowRef by default
const { data: metrics } = await useFetch('/api/dashboard/metrics')

// Direct property mutation won't trigger reactivity
// metrics.value.visits = 100  // Won't trigger re-render

// Replace the entire value to trigger updates
metrics.value = { ...metrics.value, visits: 100 }

// Or opt into deep reactivity for this specific call
const { data: settings } = await useFetch('/api/settings', {
  deep: true,
})
</script>

Bu degisikligin performans uzerinde dogrudan etkisi bulunmaktadir. Derin reaktivite, her ic ice gecmis nesne ve dizi icin proxy olusturmakta, bu da buyuk veri yapilarinda onemli bellek ve islemci yuku yaratmaktadir. Yuzeysel reaktivite bu yuku tamamen ortadan kaldirmakta ve Vue'nun reaktivite sistemi yalnizca en ust duzey referanslari izlemektedir.

Nuxt 3'ten gecis yapan ekipler icin bu durum, useFetch veya useAsyncData ile cekilen verilerin ic ice gecmis ozelliklerini dogrudan degistiren tum kod bolumlerin gozden gecirilmesini gerektirmektedir. Her bu tur mutasyon, degerin tamamen degistirilmesiyle (spread operatoru) veya deep: true secenegi ile derin reaktivitenin acikca etkinlestirilmesiyle degistirilmelidir.

Bolunmus TypeScript Baglami (Context Splitting)

Nuxt 4, tek bir global tsconfig.json yerine TypeScript yapilandirmasini dort ayri baglama bolmektedir. Her baglam kendine ozgu tip cozumleme kurallarina sahiptir ve bu yaklasim, sunucu tiplerinin istemci kodunda gorunmesi veya tersi durumu sorununu ortadan kaldirmaktadir.

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

app baglami, bilesenler, sayfalar ve composable'lar dahil olmak uzere app/ dizinindeki kodu kapsamaktadir. server baglami, Node.js tipleri ve sunucu API'lerine erisimle birlikte server/ dizinindeki dosyalari yonetmektedir. shared baglami, hem app hem de server tarafindan gorulecek sekilde shared/ dizini icin tip destegi saglamaktadir. node baglami ise nuxt.config.ts gibi yapilandirma dosyalarini kapsamaktadir.

Bu ayrim, tip dogrulamasinin calistirilma seklinde bir degisiklik gerektirmektedir. vue-tsc icin -b (proje referanslari derleme modu) bayragi artik zorunlu hale gelmistir.

# Before (Nuxt 3)
nuxt prepare && vue-tsc --noEmit

# After (Nuxt 4)
nuxt prepare && vue-tsc -b --noEmit

-b bayragi olmadan TypeScript derleyicisi projeler arasi referanslari tanimayacak ve eksik tiplere iliskin hatalar bildirecektir. Bu, gecis sirasinda en sik gozden kacirilan degisikliklerden biri olup CI/CD pipeline'larinda hatalara yol acmaktadir.

Normallesmis Bilesen Adlari ve Vue Router v5

Nuxt 4, otomatik olarak iceri aktarilan bilesenlerin adlandirma kurallarini degistirmektedir. Alt dizinlerde yer alan bilesenler artik yalnizca dosya adina degil, tam dizin yoluna dayali adlar almaktadir. Ornegin, components/dashboard/MetricsCard.vue bileseni Nuxt 3'te hem DashboardMetricsCard hem de MetricsCard olarak erisilebiliyordu. Nuxt 4'te yalnizca tam ve normallesmis ad gecerlidir.

Bu degisiklik, <KeepAlive> yapilandirmasini dogrudan etkilemekte olup include veya exclude dizisinde bilesen adlarinin acikca belirtilmesini gerektirmektedir.

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

keepalive, <Transition> ve dinamik bilesenlerde (<component :is="...">) kullanilan bilesen adlarinin yeni normallesmis adlarla uyumlu olup olmadiginin dogrulanmasi gerekmektedir. Aksi takdirde KeepAlive bilesenleri onbelleklemekten vazgecerken animasyonlu gecisler calismayacaktir.

Buna paralel olarak Nuxt 4, gezinme API'si ve koruma mekanizmalarinda (guards) degisiklikler getiren Vue Router v5'i entegre etmektedir. router.resolve() metodu artik ek meta veriler iceren genisletilmis bir nesne dondurmektedir. Gezinme korumalari ise iyilestirilmis parametre tiplemesine sahiptir. Gelismis yonlendirme desenleri kullanan ekiplerin, koruma ve middleware'lerinin yeni API ile uyumlulugunun dogrulamasi gerekmektedir.

Head Yonetimindeki Kirilma Degisiklikleri (Unhead v2)

Nuxt 4, meta etiketleri ve <head> ogeleri yonetiminde kirilma degisiklikleri getiren Unhead v2'ye gecmektedir. Nuxt 3'te etiketlerin tanimlanmasi ve tekillestirilmesi icin kullanilan vmid, hid, children ve body ozellikleri kaldirilmistir.

<script setup lang="ts">
const route = useRoute()
const { data: product } = await useFetch(`/api/products/${route.params.id}`)

// Unhead v2: removed vmid, hid, children, body props
useSeoMeta({
  title: () => product.value?.name ?? 'Product',
  ogTitle: () => product.value?.name ?? 'Product',
  description: () => product.value?.description ?? '',
  ogImage: () => product.value?.imageUrl ?? '',
})
</script>

Bunun yani sira TemplateParamsPlugin ve AliasSortingPlugin gibi bazi Unhead eklentileri artik varsayilan olarak yuklenmemektedir. Proje, meta etiketlerinde sablon parametreleri kullaniyorsa (ornegin %s | Site Adi), bunlarin Nuxt eklentisi olarak acikca kaydedilmesi gerekmektedir.

import { TemplateParamsPlugin, AliasSortingPlugin } from '@unhead/vue/plugins'

export default defineNuxtPlugin({
  setup() {
    const unhead = injectHead()
    unhead.use(TemplateParamsPlugin)
    unhead.use(AliasSortingPlugin)
  },
})

Bu eklentilerin kaydedilmemesi durumunda ortaya cikan belirti oldukca sinsidir: baslik sablonlari islenmez ve kullanici islenmis baslik yerine %s sembollerini iceren ham metni gorur. Bu sorun, gelistirme ortaminda uygulamanin calismasini etkilemeyebilecegi icin tespit edilmesi zordur ve ancak Google Search Console'daki SEO metriklerinin incelenmesiyle fark edilebilir.

Gecis Kontrol Listesi ve Sik Karsilasilan Tuzaklar

Asagida, Nuxt 3'ten Nuxt 4'e gecis yapan ekipler icin kapsamli bir kontrol listesi yer almaktadir. Her madde, uretim ortamina dagitim oncesinde dogrulanmali ve isaretlenmelidir.

1. Nuxt guncellemesi -- npx nuxt upgrade --dedupe komutunun calistirilmasi ve tum bagimliliklarin Nuxt 4 ile uyumlulugunun dogrulanmasi
2. Dizin yeniden yapilandirmasi -- codemod calistirilarak veya manuel olarak dosyalarin app/, shared/ ve server/ dizinlerine tasinmasi
3. Import yollarinin dogrulanmasi -- dosya tasinmasi sonrasinda tum import yollarinin guncellenmis oldugunun kontrol edilmesi
4. Veri cekme composable'larinin guncellenmesi -- tum useAsyncData ve useFetch kullanimlarinin yeni getCachedData API'si ve tekil desen acisindan gozden gecirilmesi
5. Shallow reactivity uyumu -- ic ice gecmis veri ozelliklerini dogrudan degistiren tum noktalarin tespit edilip duzeltilmesi
6. TypeScript yapilandirmasi -- tsconfig.json dosyasinin proje referanslari formatina guncellenmesi ve vue-tsc komutunun -b moduna gecirilmesi
7. Bilesen adlari -- keepalive, <Transition> ve dinamik bilesenlerdeki adlarin yeni normallesmis adlarla uyumunun dogrulanmasi
8. Meta etiketleri (Unhead v2) -- kaldirilmis ozelliklerin (vmid, hid, children, body) cikarilmasi ve gerekli eklentilerin kaydedilmesi
9. E2E testleri -- Vue Router v5 gezinme degisikliklerini kapsayacak sekilde tam bir uctan uca test setinin calistirilmasi
10. CI/CD pipeline'i -- derleme ve tip dogrulama komutlarinin pipeline yapilandirmasinda guncellenmesi

Gecis sirasinda en sik karsilasilan tuzaklar sunlardir:

• Unutulan shallow ref mutasyonlari -- data.value.property = x seklinde ic ice gecmis ozellikleri dogrudan degistiren kod, yeniden render'i tetiklememektedir. Gecis sonrasi en sik bildirilen sorun budur
• Eksik -b bayragi -- vue-tsc komutunda -b bayraginin eksik olmasi, yerel ortamda gorunmeyen ancak CI'da ortaya cikan sahte tip hatalarina neden olmaktadir
• KeepAlive'da normallesmemis bilesen adlari -- KeepAlive, tanimadig adlari sessizce yok sayar ve bu durum, gorunen bir hata olmaksizin onbellekleme kaybina yol acar
• Eksik Unhead eklentileri -- baslik sablonlarinin calismamasi, ancak Google Search Console sonuclarinin analiz edilmesiyle fark edilebilecek bir SEO sorununa donusmektedir

Vue ve Nuxt ekosistemi hakkindaki bilgi birikimini derinlestirmek icin Vue/Nuxt mulakat sorulari ve SSR ve statik olusturma rehberi kaynaklarina basvurulmasi onerilmektedir.

Sonuc

Nuxt 4, framework'un evriminde onemli bir adim olup yazilim gelistirme surecinin her yonunu etkileyen degisiklikler getirmektedir. Gecisten cikarilacak temel sonuclar su sekilde ozetlenebilir:

• Yeni app/ dizin yapisi, uygulama kodunu yapilandirma ve sunucu kaynaklarindan net bir sekilde ayirmakta; shared/ dizini ise istemci ve sunucu arasinda tip tekrarlanmasini ortadan kaldirmaktadir
• Tekil veri cekme katmani, getCachedData deseni ve ctx baglam nesnesi ile onbellekleme stratejisi uzerinde hassas kontrol saglamakta ve mukerrer ag isteklerini engellemektedir
• Varsayilan yuzeysel reaktivite, buyuk veri yapilarinda performansi onemli olcude iyilestirmekte ancak ic ice gecmis ozellikleri degistiren kodun bilinclice uyarlanmasini gerektirmektedir
• Bolunmus TypeScript baglami, istemci, sunucu ve paylasilan kod arasinda siki tip izolasyonu saglayarak bir butun tip hatasi sinifini ortadan kaldirmaktadir
• Normallesmis bilesen adlari ve Vue Router v5 entegrasyonu, KeepAlive yapilandirmasi, animasyonlu gecisler ve gezinme korumalarinin gozden gecirilmesini gerektirmektedir
• Unhead v2, sablon eklentilerinin acikca kaydedilmesini zorunlu kilmakta ve kaldirilmis meta etiketi ozelliklerinin temizlenmesini gerektirmektedir
• Resmi codemod, dizin yapilandirilmasini otomatize etmekte ancak composable'lar, TypeScript ve meta etiketleri gibi diger degisiklikler manuel dogrulama ve uyarlama gerektirmektedir