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

> Nuxt 4 ile gelen yeni app/ dizin yapisi, Nuxt 3'ten adim adim gecis sureci, singleton veri cekme katmani, shallow reactivity, TypeScript context splitting, Vue Router v5 entegrasyonu, Unhead v2 degisiklikleri ve kapsamli gecis kontrol listesi.

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

---

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.

> **Otomatik Gecis Araci**
>
> Nuxt 4, dizin yapisini otomatik olarak yeniden duzenleyen resmi bir codemod sunmaktadir. Manuel gecise baslamadan once `npx codemod@latest nuxt/4/file-structure` komutunu calistirmak, yapisal degisikliklerin buyuk bolumunu otomatize eder. Ancak composable'larin guncellenmesi, TypeScript yapilandirmasi ve meta etiket yonetimi gibi adimlar manuel mudahale gerektirmektedir.

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

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

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

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

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

```typescript
// app/composables/useProductData.ts
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.

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

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

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

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

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

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

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](/technologies/vue-nuxt/interview-questions/nuxt-fundamentals) ve [SSR ve statik olusturma rehberi](/blog/vue-nuxt/nuxt-3-ssr-static-generation) 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

---

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