Netlify Functions Nedir? İlk Serverless Function’ınızı Oluşturun

Netlify Functions, web projenize ayrı bir sunucu kurup yönetmeden server-side kod eklemenizi sağlayan serverless compute özelliğidir. Her Function proje içinde version control’a giren bir dosya olarak tutulur; Netlify build sırasında bunu paketler, deploy sürümüyle birlikte yayınlar ve HTTP isteği veya desteklenen platform event’i geldiğinde geçici bir runtime ortamında çalıştırır. Form doğrulama, webhook, private API çağrısı, veritabanı sorgusu ve AI endpoint’i gibi işlemler için kullanılabilir.

Güncel JavaScript/TypeScript API’sinde Function, Web Platform Request ve Netlify Context alıp Response döndürebilir. Varsayılan dizin netlify/functions, önerilen modern modül uzantıları TypeScript için . mts, JavaScript için . mjs biçimindedir.

Öne Çıkanlar

• Netlify Functions kaynak kodu siteyle birlikte build ve deploy edilir.
• Her deploy kendi immutable Function sürümünü taşır; preview ve production aynı dosyanın farklı sürümlerini çalıştırabilir.
• Function doğrudan varsayılan /.netlify/functions/<name> yolunda veya config.path ile özel URL’de sunulabilir.
• Vite tabanlı modern framework’lerde @netlify/vite-plugin, Next.js ve diğer durumlarda Netlify CLI yerel test için kullanılabilir.
• Private API key browser’a değil Function environment variable’ına konmalıdır.
• Serverless çalışma modeli kalıcı yerel disk, sonsuz süreli process veya ağır stateful iş için uygun değildir.
• Performans ve limitler plan, region, dependency, cold/warm durum ve dış servislere bağlıdır; tek mikro testten SLA sonucu çıkarılmamalıdır.

Netlify Functions Nedir ve Nasıl Çalışır?

Bir Function, belirli bir event oluştuğunda çalıştırılan server-side handler’dır. En yaygın event HTTP isteğidir:

``text Browser / uygulama ↓ Netlify edge ve routing ↓ Function runtime ↓ Database / dış API / Blobs / AI Gateway ↓ Response ``

Function kodu sürekli açık bir sunucuda beklemez. Netlify isteğe göre çalıştırma ortamını sağlar ve trafik hacmine göre ölçeklemeyi yönetir. Bu model sunucu provisioning, işletim sistemi yamaları ve process manager gibi işleri azaltır; fakat runtime süresi, memory, concurrency, package boyutu ve bağlantı davranışı gibi serverless sınırları getirir.

Function’lar deploy sürümüne bağlı ve immutable’dır. Production branch’e yeni Function kodu göndermek, eski Deploy Preview’ın Function sürümünü geriye dönük değiştirmez. Bu özellik review ve rollback açısından yararlıdır; database schema gibi dış state’in aynı şekilde otomatik sürümlenmediğini unutmamak gerekir.

Netlify Functions Hangi Kullanım Senaryolarına Uygundur?

Yaygın örnekler:

• Browser’da saklanmaması gereken API key ile dış servise çağrı,
• İletişim formu validasyonu ve e-posta tetikleme,
• Stripe veya başka sağlayıcı webhook’u,
• Kullanıcı yetkisi kontrol edilen API endpoint’i,
• Netlify Database sorgusu,
• Blobs’a dosya veya JSON yazma,
• AI Gateway üzerinden model çağrısı,
• Sipariş veya kayıt verisini dönüştürme,
• Scheduled ya da background işlerin tetiklenmesi,
• Deploy veya form submission gibi platform event’lerine yanıt.

Function, “backend yazmadan backend” değildir. Backend mantığı yine yazılır; yalnız altyapı yönetimi soyutlanır. Authentication, authorization, validation, idempotency, observability ve veri güvenliği geliştiricinin sorumluluğunda kalır.

Proje Nasıl Hazırlanır?

Mevcut JavaScript/TypeScript projesinde type desteği için:

``bash npm install @netlify/functions ``

Basit klasör yapısı:

``text my-project/ ├── netlify/ │ └── functions/ │ ├── hello.mts │ └── echo.mts ├── src/ ├── package.json └── netlify.toml ``

Varsayılan Function dizini netlify/functions yoludur. Farklı dizin gerekiyorsa:

``toml [functions] directory = "server/functions" ``

TypeScript configuration, Function dizininde, repository kökünde veya base directory’de bulunabilir. Monorepo’da Function’ın hangi package context’inde build edildiğini ve dependency’lerin nerede kurulduğunu ayrıca doğrulayın.

İlk Netlify Function Dosyası Nasıl Oluşturulur?

netlify/functions/hello. mts:

```ts import type { Config, Context } from "@netlify/functions";

export default async (_request: Request, context: Context) => { return Response. json({ message: "Merhaba, Netlify Functions! ", requestId: context. requestId ?? null, timestamp: new Date(). toISOString() }); };

export const config: Config = { path: "/api/hello", method: "GET" }; ```

Bu yapı özel path sayesinde şu adreste çalışmayı amaçlar:

``text https://example.netlify.app/api/hello ``

context. requestId gibi alanların güncel type ve runtime davranışı yayın öncesinde derlenerek doğrulanmalıdır. Bir alan zorunlu değilse null-safe kullanım tercih edin.

Varsayılan name-based URL de bulunabilir:

``text /.netlify/functions/hello ``

Özel path, uygulama URL’lerini platform iç yolundan ayırır ve daha okunabilir API tasarımı sağlar.

Request Verisi Nasıl Okunur ve Doğrulanır?

POST JSON alan bir Function:

```ts import type { Config } from "@netlify/functions";

const MAX_NAME_LENGTH = 80;

export default async (request: Request) => { if (! request. headers. get("content-type")?. includes("application/json")) { return Response. json( { error: "Content-Type application/json olmalı" }, { status: 415 } ); }

let body: unknown;

try { body = await request. json(); } catch { return Response. json({ error: "Geçersiz JSON" }, { status: 400 }); }

if ( typeof body ! == "object" || body === null || ! ("name" in body) || typeof body. name ! == "string" ) { return Response. json({ error: "name alanı gerekli" }, { status: 422 }); }

const name = body. name. trim();

if (! name || name. length > MAX_NAME_LENGTH) { return Response. json({ error: "name uzunluğu geçersiz" }, { status: 422 }); }

return Response. json({ message: Merhaba, ${name} }); };

export const config: Config = { path: "/api/hello", method: "POST" }; ```

Input validation yalnız type kontrolü değildir. Request boyutu, izin verilen alanlar, string uzunluğu, HTML/URL kullanımı ve business rule’lar düşünülmelidir. Kullanıcı girdisini log’a olduğu gibi yazmak PII veya log injection riski yaratabilir.

Function Yerelde Nasıl Test Edilir?

Vite tabanlı proje

Netlify’nin güncel rehberi Vite tabanlı framework’lerde plugin kullanımını öneriyor:

``bash npm install @netlify/vite-plugin ``

vite. config içine plugin eklenir ve normal dev server çalıştırılır. Plugin, Functions ile diğer Netlify primitive’lerini yerelde emüle eder.

Netlify CLI

Next. js veya plugin kapsamı dışında kalan projelerde:

``bash netlify link netlify dev ``

Yerel URL framework ve config’e göre değişir. Test:

``bash curl -i http://localhost:8888/api/hello ``

POST:

``bash curl -i \ -X POST \ -H "Content-Type: application/json" \ -d '{"name":"Ada"}' \ http://localhost:8888/api/hello ``

Hata durumları da test edilmelidir:

``bash curl -i -X POST http://localhost:8888/api/hello curl -i -X POST -H "Content-Type: application/json" -d '{}' http://localhost:8888/api/hello curl -i -X POST -H "Content-Type: application/json" -d 'not-json' http://localhost:8888/api/hello ``

Yerel emülasyon production’ın region, concurrency, cache, TLS ve network koşullarının birebir kopyası değildir. Gerçek deploy testi yine gerekir.

Environment Variable Nasıl Kullanılır?

Dashboard’da SERVER_GREETING gibi dummy variable ekleyin ve yalnız gereken Functions scope’una açın. Production ve Deploy Preview için ayrı değer kullanabilirsiniz.

Function:

```ts import type { Config } from "@netlify/functions";

export default async () => { const greeting = process. env. SERVER_GREETING;

if (! greeting) { return Response. json( { error: "Server configuration is missing" }, { status: 500 } ); }

return Response. json({ message: greeting }); };

export const config: Config = { path: "/api/greeting", method: "GET" }; ```

Gerçek secret’ı response’a veya log’a yazmayın. Sağlık kontrolü yalnız configured: true gibi bir değer döndürebilir.

Vite VITE_ veya Next. js NEXT_PUBLIC_ önekiyle browser’a açılan variable private değildir. Function’a özel API key’i public prefix ile tanımlamayın.

Function Nasıl Deploy Edilir?

Git tabanlı akışta Function source dosyasını repository’ye gönderin:

``bash git add netlify/functions package.json package-lock.json git commit -m "Add hello Netlify Function" git push ``

Netlify build sistemi Function’ı algılar, paketler ve site deploy’uyla birlikte yayınlar. Önce pull request açıp Deploy Preview’da doğrulamak daha güvenlidir.

CLI ile draft deploy:

``bash netlify deploy ``

Production deploy:

``bash netlify deploy --prod ``

Takım release politikası Git merge’e dayanıyorsa yerel --prod komutu bu review zincirini bypass edebilir. Doğrudan production deploy yetkisini sınırlandırın.

Deploy sonrasında:

``bash curl -i https://example.netlify.app/api/hello ``

Kontrol edin:

• HTTP status,
• content-type,
• JSON schema,
• Beklenen method davranışı,
• Preview/production variable farkı,
• Function logu,
• Yanlış route’un 404/405 sonucu.

Function Logları Nasıl İncelenir?

Netlify UI’da Functions alanından deploy ve Function bazında log görülebilir; CLI ile log streaming seçenekleri de bulunur. Loglara şu bilgileri güvenli biçimde eklemek yararlı olabilir:

``ts console.info("hello_request", { route: "/api/hello", method: request.method, contentType: request.headers.get("content-type") }); ``

Şunları loglamayın:

• Authorization header,
• Cookie,
• API key,
• Tam request body,
• E-posta, telefon, adres gibi gereksiz PII,
• Database connection string,
• Ödeme kartı verisi.

Structured log kullanmak, hata sayısı ve route davranışını filtrelemeyi kolaylaştırır. Request ID varsa response header veya log correlation için güvenli biçimde kullanılabilir.

Error handling’de kullanıcıya internal stack trace döndürmeyin:

```ts try { // kontrollü server işlemi } catch (error) { console.error("hello_failed", { errorType: error instanceof Error ? error.name : "unknown" });

return Response.

Güvenlik Kontrolleri Nelerdir?

Production Function için en az şu kontrolleri düşünün:

• Authentication: İsteği kim yapıyor?
• Authorization: Bu kullanıcı bu işlemi yapabilir mi?
• Input validation: Boyut, type ve format doğru mu?
• Rate limiting: Abuse veya maliyet patlaması nasıl sınırlandırılıyor?
• CSRF/CORS: Browser origin ve cookie modeli nedir?
• Secret scope: Key yalnız Function’a mı açık?
• Timeout: Dış API yanıt vermezse ne olacak?
• Retry/idempotency: Aynı webhook iki kez gelirse ne olur?
• Logging: PII ve token sızıyor mu?
• Dependency: Paketler güncel ve gerekli mi?

CORS header eklemek authentication yerine geçmez. Access-Control-Allow-Origin: * yalnız browser politikasını etkiler; endpoint internetten çağrılabilir olmaya devam eder.

Webhook doğrulamasında sağlayıcının imza mekanizmasını kullanın ve ham body gereksinimini doğru uygulayın. Ödeme veya kayıt oluşturan işlemlerde idempotency key saklayın.

Netlify Functions Ne Zaman Doğru Tercih Değildir?

Functions şu ihtiyaçlarda uygun olmayabilir:

• Sürekli açık WebSocket veya uzun ömürlü bağlantı,
• Çok uzun CPU/GPU işi,
• Kalıcı yerel disk,
• Process memory içinde paylaşılan güvenilir state,
• Özel işletim sistemi paketi veya kernel erişimi,
• Çok düşük ve sabit latency gerektiren özel altyapı,
• Belirli private network’e sürekli bağlantı,
• Serverless limitlerinin üzerinde dosya/işlem.

Uzun işler için background/async workload, queue veya harici worker; state için Database/Blobs; kullanıcıya yakın hafif request logic için Edge Functions daha uygun olabilir.

Serverless database bağlantısında her istekte sınırsız yeni connection açmak sorun yaratabilir. Netlify Database veya sağlayıcının serverless uyumlu pooler/HTTP driver yaklaşımını kullanın.

100 İsteklik Zorunlu Test Nasıl Yapılır?

Briefin istediği özgün kanıt için yalnız güvenli, side effect üretmeyen GET endpoint’i kullanılmalıdır. Yerel ve production’da 100 istek; hata oranı ile p50, p95 ve maksimum süre kaydedilebilir.

Basit ölçüm için uygun bir load-test aracı kullanılabilir. Test başlamadan önce platform şartları, rate limit ve kendi projenizin yetkisi doğrulanmalıdır. Üçüncü taraf siteye izinsiz yük testi yapılmamalıdır.

Test matrisi:

Ortam	İstek	Başarılı	4xx	5xx	p50	p95	Max
Local	100	Ölçülmedi	Ölçülmedi	Ölçülmedi	Ölçülmedi	Ölçülmedi	Ölçülmedi
Production cold başlangıç	100	Ölçülmedi	Ölçülmedi	Ölçülmedi	Ölçülmedi	Ölçülmedi	Ölçülmedi
Production warm tekrar	100	Ölçülmedi	Ölçülmedi	Ölçülmedi	Ölçülmedi	Ölçülmedi	Ölçülmedi

Sonuçla birlikte şunlar yazılmalıdır:

• Tarih ve saat,
• Test konumu ve ağ,
• Node/CLI/runtime sürümü,
• Function region,
• Endpoint’in dış servis kullanıp kullanmadığı,
• Concurrency,
• Cold/warm tanımı,
• Kullanılan araç ve komut,
• Örneklem sayısı.

> Editör notu — zorunlu özgün test: Bu taslak hazırlanırken Function deploy edilmedi ve 100 istek testi yapılmadı. Yayından önce yalnız kendi demo projesinde, veri yazmayan endpoint ile kontrollü test çalıştırılmalı; ham sonuç dosyası, log zamanları ve koşullar saklanmalıdır. Ölçülmemiş latency veya hata oranı yazıya eklenmemeli, küçük test platform SLA’sı gibi yorumlanmamalıdır.

> Görsel notu: Function klasör ağacı, Request → Function → service akışı, local terminal, deploy logu ve p50/p95 sonuç grafiği hazırlanmalıdır.

> İç link editör notu: Environment variables, Edge Functions karşılaştırması, Database ve AI Gateway yazıları yayımlandığında ilgili bölümlere doğal bağlantı eklenmelidir.

Yaygın Netlify Functions Hataları

Function 404 veriyor

Dosya yanlış dizinde, deploy’a dahil değil veya config. path beklenen URL’den farklı olabilir. Build logunda Function listesini kontrol edin.

Local çalışıyor, production 500 veriyor

Environment variable, runtime API, dependency veya dış servis erişimi farklı olabilir. Production logunu ve deploy context’i inceleyin.

Method beklenmedik biçimde kabul ediliyor

config. method veya handler içi method kontrolü eksik olabilir. 405 ve Allow header davranışını test edin.

Response JSON görünmüyor

Response. json yerine string dönmüş, content type yanlış veya proxy/SPA fallback route’u Function’ı gölgeliyor olabilir.

Secret browser’da görünüyor

Değer public framework prefix’iyle build bundle’a eklenmiş olabilir. Secret’ı revoke edin, yeni key oluşturun ve Function-only scope’a taşıyın.

Database bağlantıları tükeniyor

Her invocation’da uygun olmayan direct connection açılıyor olabilir. Serverless uyumlu driver/pooler ve connection reuse yaklaşımını inceleyin.

Function yavaş

Büyük dependency, cold start, uzak database, ardışık dış API çağrıları veya cache’siz işlem olabilir. Yalnız Function runtime’a değil tüm request path’e bakın.

Netlify Functions Kontrol Listesi

• [ ] Varsayılan veya özel Functions directory doğrulandı.
• [ ] Handler Request alıp geçerli Response döndürüyor.
• [ ] URL ve method config ile açıkça tanımlı.
• [ ] Input type, uzunluk ve boyut kontrolü var.
• [ ] Secret yalnız server scope’ta.
• [ ] Local success ve hata durumları test edildi.
• [ ] Deploy Preview sandbox servisleri kullanıyor.
• [ ] Production Function logu incelendi.
• [ ] Authentication, authorization ve rate limit kararı var.
• [ ] Timeout, retry ve idempotency ele alındı.
• [ ] 100 istek testi koşullarıyla birlikte raporlandı.
• [ ] Rollback’in dış state’i geri almadığı biliniyor.

Sık Sorulan Sorular

Netlify Functions ücretsiz mi?

Kredi tabanlı planlarda Function compute, GB-saat üzerinden ortak kredi bakiyesini tüketir. Free plan kullanılabilir; güncel oranlar ve limitler yayın tarihinde kontrol edilmelidir.

Netlify Functions hangi dilde yazılır?

Modern API JavaScript ve TypeScript için güçlü destek sunar. Go için Lambda-compatible API kullanılabilir. Güncel runtime ve dil kapsamını resmî dokümandan doğrulayın.

Function URL’si nedir?

Varsayılan name-based yol /. netlify/functions/<name> biçimindedir. config. path ile /api/hello gibi özel route tanımlanabilir.

Function her deploy’da ayrı mı sürümlenir?

Evet. Function site deploy’uyla birlikte immutable sürüm hâlinde yayınlanır; production, branch ve preview deploy’ları kendi Function sürümlerini taşır.

Netlify Function bir Express sunucusu mudur?

Hayır. İstek başına çalışan serverless handler modelidir. Framework uyumluluk katmanları bulunabilir; sürekli açık process varsayılmamalıdır.

Kaynaklar

• Netlify Functions overview
• Get started with Functions
• Functions API reference
• Functions configuration
• Local development
• Environment variables and Functions
• Function logs

Sonuç

Netlify Functions, frontend projesine küçük veya orta ölçekli server-side yetenek eklemek için güçlü bir serverless katmandır. İlk Function’da modern Request/Response API’sini, açık route ve method config’ini, validation ve güvenli environment variable kullanımını birlikte kurun. Local testten sonra Deploy Preview ve production logunu kontrol edin; latency sonucunu da region, ağ, cold/warm durum ve dış servislerle birlikte raporlayın. Serverless sınırlarını aşan stateful veya uzun işlerde farklı compute modeli seçmek daha doğru olabilir.

İlk serverless Function’ınızı oluşturup deploy etmek için [ücretsiz Netlify hesabı oluşturabilirsiniz](https://join. netlify. com/wmkqymu1heo2). Bu bir iş ortaklığı bağlantısıdır; bağlantı üzerinden kayıt olmanız veya ücretli plana geçmeniz halinde Ortak Alan komisyon kazanabilir.