2026'da Next.js 16 Middleware: Edge Runtime, Kimlik Dogrulama ve Mulakat Sorulari

Next.js 16 Middleware, her istek sunucuya ulasmadan once calisarak kimlik dogrulama, yerellesirme ve istek manipulasyonu icin ilk savunma hattini olusturur. Middleware'i anlamak, uretim uygulamalari olusturmak icin kritik oneme sahiptir ve frontend mulakat sorularinda sikca karsimiza cikar.

Next.js 16 Middleware Nasil Calisir

Next.js 16'da Middleware, istekleri route handler veya sayfa bilesenine ulasmadan once yakalar. Middleware dosyasi projenin kok dizinine (app/ veya pages/ yanina) yerlestirilmeli ve NextRequest nesnesi alan varsayilan bir fonksiyon export etmelidir.

Edge Runtime kisitlamasi, middleware'in fs veya Buffer gibi Node.js API'lerini kullanamayacagi anlamina gelir. Cloudflare Workers'a benzer sekilde V8 izolasyonlarinda calisir; bu, global dagitimi mumkun kilar ancak mevcut API'leri Web Standartlari ile sinirlar.

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  // Access request headers, cookies, and URL
  const token = request.cookies.get('session')?.value
  const pathname = request.nextUrl.pathname

  // Log for debugging (visible in Vercel logs)
  console.log(`Middleware: ${request.method} ${pathname}`)

  // Continue to the route handler
  return NextResponse.next()
}

// Configure which paths trigger middleware
export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
}

matcher yapilandirmasi, hangi yollarin middleware'i tetikleyecegini tanimlamak icin regex benzeri bir soz dizimi kullanir. Bu olmadan middleware, statik varliklar dahil her istekte calisir.

Next.js Middleware ile Kimlik Dogrulama Kaliplari

Middleware, herhangi bir sayfa kodu calistirilmadan once calistigi icin kimlik dogrulamada mukemmel performans gosterir. Gecerli bir oturumu olmayan kullanici, korunan icerigi bir an bile goremez. Bu, yonlendirmeden once korunan icerigi kisa sureligine gosterebilen istemci tarafi auth kontrollerinden farklidir.

Asagidaki kalip, oturum tokenini dogrular ve kimlik dogrulanmamis kullanicilari yonlendirir. Oturum verilerini cookie'lerde veya header'larda saklayan herhangi bir auth saglayiciyla entegre olur.

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

const protectedPaths = ['/dashboard', '/settings', '/profile']
const authPaths = ['/login', '/signup']

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl
  const sessionToken = request.cookies.get('session')?.value

  // Check if path requires authentication
  const isProtectedPath = protectedPaths.some(path => 
    pathname.startsWith(path)
  )
  const isAuthPath = authPaths.some(path => 
    pathname.startsWith(path)
  )

  // Validate session token (call auth service)
  const isValidSession = sessionToken 
    ? await validateSession(sessionToken)
    : false

  // Redirect unauthenticated users to login
  if (isProtectedPath && !isValidSession) {
    const loginUrl = new URL('/login', request.url)
    loginUrl.searchParams.set('callbackUrl', pathname)
    return NextResponse.redirect(loginUrl)
  }

  // Redirect authenticated users away from auth pages
  if (isAuthPath && isValidSession) {
    return NextResponse.redirect(new URL('/dashboard', request.url))
  }

  return NextResponse.next()
}

async function validateSession(token: string): Promise<boolean> {
  // Call auth API endpoint or decode JWT
  // Edge-compatible: use fetch, not Node.js crypto
  try {
    const response = await fetch('https://api.example.com/validate', {
      headers: { Authorization: `Bearer ${token}` },
    })
    return response.ok
  } catch {
    return false
  }
}

callbackUrl parametresi orijinal hedefi korur, boylece kullanicilar giris yaptiktan sonra ilk istedikleri sayfaya yonlendirilir.

Yol Eslestirme ve Matcher Yapilandirmasi

matcher yapilandirmasi, hangi isteklerin middleware'i tetikleyecegini belirler. Yanlis yapilandirma, performans sorunlarina (middleware'in her statik varlikta calismasi) veya guvenlik aciklarina (korunan yollarin auth kontrolunu tetiklememesi) yol acar.

Next.js 16, uc matcher soz dizimini destekler: string yollar, parametreli yol kaliplari ve negatif lookahead'li regex benzeri kalipler.

// Option 1: Simple string paths
export const config = {
  matcher: ['/dashboard/:path*', '/api/:path*'],
}

// Option 2: Exclude static assets with negative lookahead
export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|public/).*)'],
}

// Option 3: Conditional matching with has/missing
export const config = {
  matcher: [
    {
      source: '/api/:path*',
      has: [{ type: 'header', key: 'Authorization' }],
    },
    {
      source: '/dashboard/:path*',
      missing: [{ type: 'cookie', key: 'session' }],
    },
  ],
}

Secenek 3'teki has ve missing kosullari, middleware calismadan once mantik ekler. Bu, middleware fonksiyonu icinde kontrol etmekten daha verimlidir.

Middleware'de Istek ve Yanit Manipulasyonu

Kimlik dogrulamanin otesinde, middleware istekleri route handler'lara ulasmadan once ve yanitlari istemciye ulasmadan once degistirebilir. Yaygin kullanim ornekleri arasinda guvenlik header'lari ekleme, A/B testi icin URL yeniden yazma ve cografi konum verisi enjekte etme bulunur.

NextResponse sinifi, her degisiklik turu icin metodlar saglar. Yeniden yazmalar (rewrite) tarayici URL'ini degistirmeden hedefi degistirirken, yonlendirmeler her ikisini de gunceller.

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  const response = NextResponse.next()

  // Add security headers to all responses
  response.headers.set('X-Frame-Options', 'DENY')
  response.headers.set('X-Content-Type-Options', 'nosniff')
  response.headers.set(
    'Referrer-Policy', 
    'strict-origin-when-cross-origin'
  )

  // Inject geolocation into request headers for route handlers
  const geo = request.geo
  if (geo?.country) {
    response.headers.set('x-user-country', geo.country)
    response.headers.set('x-user-city', geo.city ?? 'unknown')
  }

  return response
}

Cografi konum verileri (request.geo) Vercel Edge Network tarafindan doldurulur. Kendi sunucunuzda barindirilan dagitimlar, bunu hosting saglayicisi araciligiyla yapilandirmali veya ucuncu taraf bir IP cografi konum hizmeti kullanmalidir.

A/B Testi ve Ozellik Bayraklari icin URL Yeniden Yazma

Middleware yeniden yazmalari, istemci bilmeden cookie'lere, header'lara veya rastgele atamaya dayali olarak farkli sayfalar sunmaya olanak tanir. Bu kalip, A/B testi framework'lerini ve kademeli ozellik yaymalarini destekler.

Yeniden yazma edge'de gerceklesir, bu nedenle her iki varyant da ayni URL'e sahiptir ve uygun oldugunda edge onbelleklemeden yararlanir.

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl

  // Check for existing variant assignment
  let variant = request.cookies.get('ab-variant')?.value

  // Assign variant if not set (50/50 split)
  if (!variant && pathname === '/pricing') {
    variant = Math.random() < 0.5 ? 'control' : 'treatment'
    const response = NextResponse.rewrite(
      new URL(`/pricing/${variant}`, request.url)
    )
    response.cookies.set('ab-variant', variant, {
      maxAge: 60 * 60 * 24 * 30, // 30 days
      httpOnly: true,
    })
    return response
  }

  // Rewrite to assigned variant
  if (variant && pathname === '/pricing') {
    return NextResponse.rewrite(
      new URL(`/pricing/${variant}`, request.url)
    )
  }

  return NextResponse.next()
}

Cookie, varyant atamasini saklar ve kullanicilarin tekrar ziyaretlerde ayni versiyonu gormesini saglar. 30 gunluk son kullanma suresi, deney tutarliligi ile kullanicilari yeni deneylere atama yetenegini dengeler.

Edge Runtime Sinirlmalari ve Cozumleri

Edge Runtime, global dagitim ve hizli soguk baslamalar icin Node.js uyumlulugundan vazgecer. Middleware, Node.js'e ozgu modulleri import edemez; bu, bcrypt, jsonwebtoken (RS256 kullanildiginda) ve TCP soketlerine dayanan veritabani istemcileri gibi kutuphaneleri etkiler.

Next.js Edge Runtime dokumantasyonu desteklenen API'leri listeler. Web Crypto, fetch ve cogu Web Platform API'si calisir. Agir hesaplamalar Node.js'te calisan API route'larina tasinmalidir.

import { jwtVerify } from 'jose' // Edge-compatible JWT library
import type { NextRequest } from 'next/server'

const JWT_SECRET = new TextEncoder().encode(process.env.JWT_SECRET!)

export async function middleware(request: NextRequest) {
  const token = request.cookies.get('token')?.value

  if (!token) {
    return redirectToLogin(request)
  }

  try {
    // jose library works in Edge Runtime
    const { payload } = await jwtVerify(token, JWT_SECRET)
    
    // Token is valid, check expiration
    if (payload.exp && payload.exp < Date.now() / 1000) {
      return redirectToLogin(request)
    }

    return NextResponse.next()
  } catch {
    // Invalid token signature or format
    return redirectToLogin(request)
  }
}

function redirectToLogin(request: NextRequest) {
  const url = new URL('/login', request.url)
  url.searchParams.set('callbackUrl', request.nextUrl.pathname)
  return NextResponse.redirect(url)
}

jose kutuphanesi, Edge uyumlu JWT islemleri saglar. Altta Web Crypto kullanir ve Node.js crypto modulunden kacinir.

Yaygin Next.js Middleware Mulakat Sorulari

Mulakatcilar, istek yasam dongusu, guvenlik kaliplari ve Edge computing sinirlarin anlayisini degerlendirmek icin middleware hakkinda sorular sorar. Bu sorular, Next.js ile calisan senior frontend ve fullstack pozisyonlarinda karsimiza cikar.

Middleware istek yasam dongusunde nerede calisir?

Middleware, istek Next.js sunucusuna ulastiktan sonra ancak herhangi bir route eslesmesi veya sayfa render'i oncesinde calisir. Vercel'de Edge'de, yani kullaniciya en yakin veri merkezinde calisir. Bu konumlandirma, gecersiz isteklerin origin sunucusuna hic ulasmamasi nedeniyle kimlik dogrulama ve yonlendirmeler icin idealdir.

Middleware, API route'larina kiyasla ne yapamaz?

Middleware, Node.js'te degil Edge Runtime'da calisir. Node.js yerlesik modullerini (fs, path, belirli algoritmalarla crypto), TCP tabanli veritabani istemcilerini veya Node.js API'lerine bagli npm paketlerini kullanamaz. Agir hesaplamalar API route'larinda veya Server Components'ta gerceklesmelidir.

Middleware'de engellemeden kimlik dogrulama nasil yapilir?

Kalip, oturum cookie'sini kontrol etmeyi, auth endpoint'ine karsi dogrulamayi veya JWT imzasini dogrulamayi ve gecersizse yonlendirmeyi icerir. Her istegi engellemekten kacinmak icin, middleware'in yalnizca korunan yollarda calismasini saglamak uzere matcher yapilandirmasi kullanilmalidir. Durumsuz JWT dogrulamasi, her istekte harici bir auth servisi cagirmaktan daha hizlidir.

Middleware hata firlatirsa ne olur?

Middleware'deki islenmemis bir hata, istemciye 500 yaniti dondurur. Sayfa hic render edilmez. Middleware mantgini try-catch ile sarmak ve bir fallback yaniti (genellikle NextResponse.next()) dondurmek, tam istek basarisizliklarini onler. Devam etmeden once hatayi loglamak hata ayiklamaya yardimci olur.

Bu kavramlarla daha derin pratik icin, Next.js Middleware ve Auth mulakat sorulari modulu ek senaryolar kapsar.

Development ve Production'da Middleware Hata Ayiklama

Middleware hatalari, kod tarayici DevTools'ta degil edge'de calistigi icin zordur. Development modu, middleware loglarini terminalde gosterir, ancak production uygun loglama altyapisi gerektirir.

Asagidaki yaklasim, hassas verileri aciga cikarmadan sorunlari hata ayiklamak icin yeterli baglamla middleware calismasini loglar.

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  const start = Date.now()
  const requestId = crypto.randomUUID()

  // Log request start
  console.log(JSON.stringify({
    type: 'middleware_request',
    requestId,
    method: request.method,
    path: request.nextUrl.pathname,
    userAgent: request.headers.get('user-agent')?.slice(0, 100),
    country: request.geo?.country,
  }))

  // Process request
  const response = processRequest(request)

  // Log completion
  console.log(JSON.stringify({
    type: 'middleware_response',
    requestId,
    duration: Date.now() - start,
    status: response.status,
  }))

  // Pass request ID to route handlers
  response.headers.set('x-request-id', requestId)
  return response
}

function processRequest(request: NextRequest): NextResponse {
  // Middleware logic here
  return NextResponse.next()
}

Vercel'de bu loglar Functions sekmesinde gorunur. Kendi sunucunuzda barindirilan dagitimlar, loglari Datadog gibi bir servise gondermeli veya hosting platformunun isleyebilecegi yapilandirilmis loglama kullanmalidir.

Middleware Performans En Iyi Uygulamalari

Middleware, eslesen her istekte calisir. Yavas bir middleware fonksiyonu her sayfa yuklemesine gecikme ekler. Amac, cogu istek icin middleware calismasini 5ms'nin altinda tamamlamaktir.

• Async islemleri en aza indirin: Her await gecikme ekler. Mumkun oldugunda dogrulama sonuclarini onbellekleyin.
• Matcher yapilandirmasini kullanin: Middleware mantigi gerektirmeyen statik varliklari ve genel yollari dislayin.
• Her istekte harici cagrilardan kacinin: Bir auth servisi cagirmak yerine JWT'leri yerel olarak dogrulayin. Uygun oldugunda sonuclari cookie'lerde onbellekleyin.
• Bundle'i kucuk tutun: Middleware'in kendi bundle boyutu siniri vardir (Vercel'de 1MB). Yalnizca gerekli olani import edin.

/technologies/react-next adresindeki React Next.js teknoloji sayfasi, middleware bilgisini tamamlayan Server Components ve veri getirme kaliplari gibi ilgili kavramlari kapsar.

Production icin Next.js 16 Middleware Kontrol Listesi

• Middleware'i proje kokune middleware.ts olarak yerlestirin, app/ veya pages/ icine degil
• matcher'i _next/static, _next/image ve genel varliklari middleware calismasindan dislamak icin yapilandirin
• JWT dogrulamasi icin jsonwebtoken yerine jose gibi Edge uyumlu kutuphaneler kullanin
• Girise yonlendirirken callback URL'lerini query parametrelerinde saklayin, boylece kullanicilar hedefledikleri hedefe donebilir
• Tum route'larda tutarli uygulama icin middleware'de guvenlik header'lari ekleyin
• Istekleri sistem uzerinden izlemek icin istek ID'leriyle middleware calismasini loglayin
• Tokenlari yerel olarak dogrulayarak ve kullanici verilerini imzali cookie'lerde onbelleleyerek harici API cagrilarini minimumda tutun