Kurulum ve proje yapısı

Bu Rehber Ne Anlatıyor

Next.js dokümanı güncel ve ayrıntılı. Bu rehber onu tekrar etmiyor. Her derste konuyu kısaca özetleyip Next.js ekibinin ve deneyimli mühendislerin önerilerini, yaygın hataları topluyor. Sürüm: Next.js 16.4 (Ekim 2026), React 19.3.¹

Ön koşul React rehberi. Component, state, Suspense ve Actions'ı orada gördünüz. Burada bunların sunucuyla birleştiği yeri öğreneceksiniz.

Next.js Ne Getirir

React yalnızca arayüz kütüphanesidir. Routing, veri çekme ve sunucuda render için bir framework gerekir. React ekibi yeni uygulamalara Next.js App Router'ı önerdiği framework'ler arasında sayar.²

Next.js'in farkı render modelinde. Çoğu framework bir sayfayı ya tamamen statik ya tamamen dinamik sayar. Next.js bu sınırı component seviyesine indirir: aynı sayfada anında gelen statik bir kabuk (shell) ve sonradan akan dinamik parçalar olabilir.³ Rehberin geri kalanı bu fikrin üzerine kurulu.

İlk Proje

$ pnpm create next-app@latest my-shop --yes

cd my-shop
npm run dev

--yes önerilen varsayılanları seçer:⁴

Turbopack, Next.js 16'dan beri hem next dev hem next build için varsayılan.⁵ 16.4 ile yeni projeler Cache Components açık gelir; sayfalar varsayılan olarak dinamik olur ve neyin cache'leneceğini siz seçersiniz.¹ Bu modeli Cache ve render modeli dersinde göreceksiniz.

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
};

export default nextConfig;

Önemli Dosyalar

AGENTS.md'nin işi ilginç: agent'a eğitim verisine değil, node_modules/next/dist/docs/ altındaki, kurulu sürümle eşleşen dokümana bakmasını söyler.⁶ Ayrıntısı AI agent'larla Next.js dersinde.

app Klasörü ve Özel Dosyalar

App Router'da klasörler URL'yi, özel dosyalar o adreste ne gösterileceğini belirler. Bir klasör ancak içinde page.tsx ya da route.ts olduğunda erişilebilir olur.⁷

Next.js bu dosyaları sabit bir sırayla iç içe koyar: layout > error > loading > not-found > page.⁷ React rehberindeki Suspense ve Error Boundary'yi hatırlayın: loading.tsx bir <Suspense>, error.tsx bir Error Boundary'dir. Next.js onları dosya adından kurar.

Kodu Nereye Koymalı

Next.js yapı konusunda görüş bildirmez, tutarlı olmanızı ister.⁷ İşe yarayan üç kural var:

• Colocation güvenlidir. app/products/ içine product-card.tsx koymak yeni bir adres açmaz; adres yalnızca page.tsx ile açılır.

• _ ile başlayan klasör (private folder) routing'den tamamen çıkar: app/products/_components/.

• Parantezli klasör (route group) URL'ye eklenmez: app/(shop)/cart/page.tsx → /cart. Bölümleri gruplamak ve onlara ayrı layout vermek için kullanılır.

Büyüyen projelerde app/ klasörünü yalnızca routing için tutup kodu features/ altında toplamak yaygın bir tercih. Bu yaklaşımı Klasör Yapısı ve İsimlendirme dersi anlatıyor.

Güncel Kalmak

Next.js sık sürüm çıkarır. Her sürüm güvenlik yaması da içerir. Küçük ve sık güncellemek, büyük ve seyrek güncellemekten kolaydır.⁴

npx next upgrade

Güncelleme, paketle gelen dokümanı da yeni sürüme taşır. Böylece agent'lar her zaman kurulu sürümün dokümanını okur.⁴

Kendin Dene

• my-shop projesini kurun. next.config.ts'te cacheComponents ve partialPrefetching'in açık geldiğini görün.

• app/about/page.tsx oluşturun ve /about'a gidin. Sonra dosyayı app/(marketing)/about/page.tsx'e taşıyın; adres değişti mi?

• app/about/_components/team.tsx oluşturun. /about/_components/team adresine gidince ne oluyor?

• AGENTS.md'yi açın ve agent'ı hangi klasöre yönlendirdiğini okuyun.

Detaylı Öğrenmek İçin

• Resmi doküman: Next.js Learn kursu; App Router ile adım adım bir panel uygulaması kurar.⁸

• Resmi doküman: "Rendering Philosophy" sayfası; statik ile dinamiği neden bir yelpaze olarak gördüklerini ve bunun hosting'e etkisini anlatır.³

• Video: Next.js Conf 2025 açılış konuşması; Guillermo Rauch, Sam Selikoff ve Jimmy Lai Next.js 16'yı tanıtıyor.⁹

• Resmi doküman: Next.js 16 duyurusu; Turbopack, proxy.ts ve Cache Components'in ilk hâli.⁵