netlify.toml Nedir? Build, Redirect ve Context Ayarları Rehberi

netlify. toml, Netlify’nin bir projeyi nasıl build edip deploy edeceğini repository içinde tanımlayan dosya tabanlı yapılandırmadır. Build komutu, publish dizini, deploy context’leri, redirects, headers, Functions dizini ve Netlify Dev ayarları gibi birçok karar bu dosyada tutulabilir. En önemli avantajı, kritik proje ayarlarını dashboard’daki görünmez seçimler olmaktan çıkarıp kodla birlikte version control altında izlenebilir hâle getirmesidir.

Bununla birlikte netlify. toml, Netlify’deki her ayarı kapsayan eksiksiz bir kontrol dosyası değildir. Bazı ayarlar yalnız UI, CLI veya API üzerinden yönetilir. Ayrıca repository’ye commit edildiği için private API key, database password ve benzeri secret değerler bu dosyaya yazılmamalıdır.

Öne Çıkanlar

• netlify.toml normalde repository kökünde bulunur.
• Dosyadaki bir ayar dashboard’daki aynı ayarla çakışırsa netlify.toml önceliklidir.
• [build] bloğu base directory, build command ve publish directory tanımlar.
• Production, Deploy Preview, Branch Deploy, belirli branch ve yerel geliştirme için farklı context ayarları yazılabilir.
• [[redirects]] ve [[headers]] tekrar eden TOML bloklarıdır; doğrudan context-aware değildir.
• [dev] Netlify Dev sunucusunu yapılandırır; yerel environment variables için [context.dev.environment] kullanılmalıdır.
• $VARIABLE yazmak, değeri otomatik olarak TOML içine enjekte etmez.

netlify.toml Nedir ve Neden Kullanılır?

netlify. toml, Netlify projesinin build ve deploy davranışını açıklayan TOML formatlı bir yapılandırma dosyasıdır. Aynı repository’yi başka bir ekip üyesi fork ettiğinde veya yeni bir Netlify projesine bağladığında, build komutu ve routing kuralları gibi kararların yeniden elle girilmesini azaltır.

Dashboard ayarları hızlı başlangıç için kullanışlıdır; ancak ekip büyüdükçe şu sorular ortaya çıkar:

• Build komutu ne zaman ve kim tarafından değiştirildi?
• Preview ortamı neden production’dan farklı çıktı?
• SPA fallback kuralı hangi proje ayarında tutuluyor?
• Functions dizini neden varsayılandan farklı?
• Staging branch’i hangi API ortamını kullanıyor?

Bu kararlar netlify. toml içinde tutulduğunda Git diff, pull request review ve rollback süreçlerine girer. Bir yapılandırma değişikliği uygulama kodu kadar görünür olur.

Yine de her şeyi dosyaya taşımak doğru değildir. Netlify, environment variables için UI kullanımını önerir; çünkü burada scope seçilebilir, değişiklikler audit log’da takip edilebilir ve değerler CLI/API üzerinden güvenli biçimde yönetilebilir. Secret değerleri repository’ye koymak, private repo kullanılsa bile gereksiz risk yaratır.

netlify.toml Dosyası Nereye Konur?

Standart projede dosya repository kökünde bulunur:

``text my-project/ ├── netlify.toml ├── package.json ├── src/ └── public/ ``

Monorepo’da dosya uygulama dizininde de tutulabilir. Bu durumda Netlify’nin base directory veya package directory ayarı, yapılandırmanın nerede aranacağını doğru göstermelidir.

``text monorepo/ ├── apps/ │ ├── web/ │ │ ├── netlify.toml │ │ ├── package.json │ │ └── src/ │ └── admin/ ├── packages/ └── package.json ``

Dosyadaki path’ler varsayılan olarak base directory’ye göre çözülür. Örneğin base directory apps/web ise publish = "dist", repository kökündeki değil apps/web/dist klasörünü ifade eder. “Publish directory bulunamadı” hatalarının önemli bir bölümü bu göreli bağlamın yanlış anlaşılmasından kaynaklanır.

Build ve Publish Ayarları Nasıl Yazılır?

En temel yapı şöyledir:

``toml [build] command = "npm run build" publish = "dist" ``

Burada:

• command, production çıktısını üreten komuttur.
• publish, deploy edilecek nihai dosya dizinidir.
• base, komutun çalışacağı temel dizini değiştirebilir.

Monorepo örneği:

``toml [build] base = "apps/web" command = "npm run build" publish = "dist" ``

Framework adapter kullanan Next. js gibi projelerde publish dizinini statik Vite projesi gibi elle zorlamak gerekmeyebilir. Framework’ün güncel Netlify rehberini esas alın. netlify. toml her projeye aynı şablonu kopyalama aracı değil, gerçek build davranışını açıkça tanımlama aracıdır.

Build ortamına public ve hassas olmayan sabit değer eklemek teknik olarak mümkündür:

``toml [build.environment] NODE_VERSION = "22" APP_MODE = "production" ``

Private değerler burada tutulmamalıdır. API_SECRET = "$API_SECRET" yazmak da UI’daki değeri otomatik olarak TOML içine aktarmayacaktır. Netlify’nin resmî dokümanı, environment variable değerlerinin doğrudan netlify. toml alanlarında interpolation ile kullanılmadığını açıkça belirtir. Böyle bir ihtiyacı build command, local build plugin veya desteklenen özel mekanizmayla çözmek gerekir.

Deploy Context Ayarları Nasıl Çalışır?

Context, bir deploy’un production, pull request preview, non-production branch veya yerel geliştirme amacıyla çalıştığını belirtir. Genel [build] ayarı tüm context’lere uygulanır; daha özel blok aynı property’yi override eder.

```toml [build] command = "npm run build" publish = "dist"

[context. production] command = "npm run build:production"

[context. deploy-preview] command = "npm run build:preview"

[context. branch-deploy] command = "npm run build:staging"

[context. staging] command = "npm run build:staging-strict" ```

Öncelik mantığı sadeleştirilmiş biçimde şöyledir:

1. Dashboard’daki çakışan ayar,
2. Genel netlify. toml ayarı,
3. Deploy türüne özel context,
4. Belirli branch adına özel context.

Örneğin staging branch’i bir Branch Deploy’dur. Hem [context. branch-deploy] hem [context. staging] tanımlıysa, branch adına özel olan staging bloğu daha spesifiktir ve aynı property’de öncelik kazanır.

Environment variables için context blokları:

```toml [context.deploy-preview.environment] PUBLIC_API_ORIGIN = "https://preview-api.example.com"

[context. staging. environment] PUBLIC_API_ORIGIN = "https://staging-api. example. com" ```

Burada yalnız browser’da veya repository’de görünmesinde sakınca olmayan değerler kullanılmalıdır. Production credential’ı, ödeme anahtarı veya database password UI üzerinden dar scope ve doğru context ile tanımlanmalıdır.

Redirects ve Rewrites Nasıl Eklenir?

Her redirect ayrı bir [[redirects]] bloğudur:

``toml [[redirects]] from = "/eski-sayfa" to = "/yeni-sayfa" status = 301 ``

SPA fallback örneği:

``toml [[redirects]] from = "/*" to = "/index.html" status = 200 ``

Proxy rewrite örneği:

``toml [[redirects]] from = "/api/*" to = "https://api.example.com/:splat" status = 200 force = true ``

Kural sırası önemlidir. Geniş /* fallback kuralını özel API veya eski URL yönlendirmelerinden önce koymak, diğer kuralları gölgeleyebilir. Exact kuralları önce, wildcard kurallarını sonra yazın.

force = true, mevcut bir dosya veya route olsa bile kuralı uygulamaya zorlayabilir. Bu davranışı anlamadan kullanmak erişilebilir sayfaların yanlış hedefe gitmesine yol açabilir.

Önemli sınırlama: [[redirects]] ve [[headers]] blokları doğrudan deploy context’e göre override edilen alanlar değildir. Preview ve production için farklı routing gerekiyorsa context’e özel dosya üretimi, build plugin veya daha uygun uygulama routing mekanizması düşünülmelidir.

Headers Nasıl Tanımlanır?

Güvenlik ve cache header’ları [[headers]] bloklarıyla eklenebilir:

``toml [[headers]] for = "/*" [headers.values] X-Content-Type-Options = "nosniff" Referrer-Policy = "strict-origin-when-cross-origin" Permissions-Policy = "camera=(), microphone=(), geolocation=()" ``

Asset cache örneği:

``toml [[headers]] for = "/assets/*" [headers.values] Cache-Control = "public, max-age=31536000, immutable" ``

Uzun cache süresi yalnız filename’i content hash ile değişen asset’lerde güvenlidir. Aynı URL’de içeriği değiştirecekseniz immutable ziyaretçinin eski dosyayı uzun süre görmesine neden olabilir.

Content Security Policy gibi karmaşık header’ları kopyala-yapıştır kullanmayın. Uygulamanın script, font, image ve API kaynaklarına göre test edin. Önce report-only politika kullanmak, production kesintisi yaratmadan gerçek ihtiyaçları görmeye yardımcı olabilir.

Functions Ayarları Nasıl Yönetilir?

Varsayılan Functions dizini base directory altında netlify/functions yoludur. Özel dizin kullanmak isterseniz:

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

Belirli Function grupları için ek dosya veya external package tanımlanabilir:

```toml [functions."report_"] included_files = ["content/.md"]

[functions. api_export] external_node_modules = ["some-native-package"] ```

Bu ayarlar yalnız gerçek bundling ihtiyacı varsa eklenmelidir. Gereksiz included file, Function paketini büyütür; yanlış external module ayarı runtime’da module bulunamamasıyla sonuçlanabilir.

Netlify Dev Ayarları Nasıl Yazılır?

Yerel proxy ve framework dev server ayarı [dev] altında tutulur:

``toml [dev] command = "npm run dev" targetPort = 5173 port = 8888 autoLaunch = false framework = "#custom" ``

• targetPort, Vite veya başka framework dev server portudur.
• port, tarayıcıda açılan Netlify Dev proxy portudur.
• Hem command hem targetPort açıkça verildiğinde framework = "#custom" gerekebilir.

[dev] bloğunda environment property’si yoktur. Yerel context için:

``toml [context.dev.environment] PUBLIC_API_ORIGIN = "http://localhost:9999" ``

Yine burada private secret tutmayın. Yerel private değerler güvenli . env yönetimi veya Netlify project variables üzerinden sağlanmalıdır.

Tam Bir netlify.toml Örneği

Aşağıdaki dosya Vite tabanlı örnek bir SPA için öğretici başlangıçtır:

```toml [build] command = "npm run build" publish = "dist"

[context. production] command = "npm run build"

[context. deploy-preview] command = "npm run build:preview"

[context. staging] command = "npm run build:staging"

[context. dev. environment] PUBLIC_API_ORIGIN = "http://localhost:9999"

[functions] directory = "netlify/functions" node_bundler = "esbuild"

[dev] command = "npm run dev" targetPort = 5173 port = 8888 autoLaunch = false framework = "#custom"

[[redirects]] from = "/api/*" to = "/. netlify/functions/api/:splat" status = 200

[[redirects]] from = "/old-page" to = "/new-page" status = 301

[[redirects]] from = "/*" to = "/index. html" status = 200

[[headers]] for = "/*" [headers. values] X-Content-Type-Options = "nosniff" Referrer-Policy = "strict-origin-when-cross-origin"

[[headers]] for = "/assets/*" [headers. values] Cache-Control = "public, max-age=31536000, immutable" ```

Bu örneği kendi framework ve route yapınıza göre sadeleştirin. SSR framework’üne SPA fallback eklemek veya hash’siz asset’e uzun cache vermek yanlış olabilir.

Dashboard ile netlify.toml Çakışırsa Hangisi Kazanır?

Aynı property hem UI hem netlify. toml içinde tanımlıysa dosya tabanlı ayar önceliklidir. Bu nedenle dashboard’da build command’i değiştirip sonucun neden değişmediğini anlamayan ekipler sıkça sorun yaşar.

Sorun çözme sırasında şu sırayı izleyin:

1. Deploy logunda Netlify’nin hangi config dosyasını bulduğunu görün. 2. Base directory’nin dosyanın konumuyla uyumlu olduğunu doğrulayın. 3. UI ile TOML’daki build/publish değerlerini karşılaştırın. 4. Deploy context’i belirleyin. 5. Branch adına özel override olup olmadığını kontrol edin. 6. Framework adapter’ın bazı ayarları otomatik üretip üretmediğini inceleyin.

Ayarların tek kaynaktan yönetilmesi en temiz yaklaşımdır. UI’da yalnız dosyanın kapsamadığı ya da secret/permission gibi UI için daha uygun kararları tutun.

netlify.toml Nasıl Doğrulanır?

Yerel doğrulama için:

``bash netlify dev netlify build ``

Ardından gerçek Deploy Preview, Branch Deploy ve Production Deploy loglarını karşılaştırın. Sadece TOML syntax’ının geçerli olması yeterli değildir; command, output, routing ve context sonucu da doğrulanmalıdır.

Test matrisi:

Kontrol	Dev	Deploy Preview	Staging branch	Production
Build command	Kaydedilecek	Kaydedilecek	Kaydedilecek	Kaydedilecek
Publish directory	Kaydedilecek	Kaydedilecek	Kaydedilecek	Kaydedilecek
Public env etiketi	dev	preview	staging	production
/old-page	301	301	301	301
/api/health	200 beklenir	Test edilecek	Test edilecek	Test edilecek
/about SPA route	200 beklenir	Test edilecek	Test edilecek	Test edilecek
Security headers	Test edilecek	Test edilecek	Test edilecek	Test edilecek

> Editör notu — zorunlu özgün test: Bu taslaktaki örnek netlify. toml, gerçek bir projede üç deploy context’iyle çalıştırılmadı. Yayından önce temiz bir Vite demo projesinde netlify dev, netlify build, Deploy Preview, staging Branch Deploy ve Production Deploy uygulanmalı; CLI/Node/Vite sürümleri, commit SHA, build command, route status code’ları ve response header’ları kaydedilmelidir. Çalıştırılmayan sonuçlar tabloya eklenmemelidir.

> Görsel notu: UI ayarı → netlify. toml override → context → deploy sonucu akışını gösteren öncelik diyagramı ve dört context’in log ekranları hazırlanmalıdır.

> İç link editör notu: Netlify CLI, deploy türleri, redirects ve environment variables rehberleri yayımlandıktan sonra ilgili bölümlere doğal bağlantı eklenmelidir.

Yaygın netlify.toml Hataları

Dosya bulunmuyor

Dosya repository kökünde değildir veya monorepo base/package directory yanlış ayarlanmıştır. Deploy logunda config path’i kontrol edin.

Publish directory bulunamıyor

Path’in base directory’ye göre çözüldüğünü unutmuş olabilirsiniz. Build’in gerçekten çıktıyı hangi klasöre yazdığını doğrulayın.

Preview production komutunu kullanıyor

Context adı yanlış yazılmış veya property başka, daha özel branch context’i tarafından override edilmiş olabilir.

Environment variable değeri $NAME olarak kalıyor

TOML doğrudan shell interpolation yapmaz. Değerin gerçekten build command içinde mi, uygulama runtime’ında mı kullanılması gerektiğini belirleyin.

SPA fallback API’yi bozuyor

Geniş wildcard kuralı özel API rewrite’ından önce gelmiş olabilir. Kural sırasını değiştirin.

Header yalnız preview’da farklı olsun isteniyor

[[headers]] doğrudan context-aware değildir. Build sırasında context’e özel _headers üretme veya uygulama/runtime katmanında header ayarlama seçeneklerini değerlendirin.

Sık Sorulan Sorular

netlify.toml zorunlu mu?

Hayır. Birçok proje dashboard ve framework algılamasıyla deploy edilebilir. Dosya, ayarları version control altında tutmak ve daha gelişmiş yapılandırma yapmak için kullanılır.

netlify.toml içinde secret saklanır mı?

Saklanmamalıdır. Dosya repository’ye commit edilir. Secret’lar Netlify UI, CLI veya güvenli API/CI secret yönetimiyle tanımlanmalıdır.

UI mı netlify.toml mı öncelikli?

Aynı property çakıştığında netlify. toml ayarı UI’daki karşılığını override eder.

_redirects ile netlify.toml birlikte kullanılabilir mi?

Kullanılabilir; ancak aynı veya çakışan kuralların işlem sırasını dikkatle doğrulamak gerekir. Tek bir kaynak seçmek bakımı kolaylaştırır.

Context ayarları redirects ve headers için de geçerli mi?

[build] ve bazı plugin alanları context-aware’dir. [[redirects]] ve [[headers]] doğrudan context bloğu altında farklılaştırılamaz.

Kaynaklar

• File-based configuration
• Build configuration overview
• Deploy contexts
• Redirects and rewrites
• Custom headers
• Netlify Dev

Sonuç

netlify. toml, build ve deploy kararlarını kodla birlikte yönetmenin en görünür yoludur. Build command ve publish directory’yi açıkça tanımlayın, context override’larını az ve anlaşılır tutun, routing kurallarını özelden genele sıralayın ve private değerleri dosyanın dışında yönetin. En kritik nokta, dosyanın yalnız syntax açısından değil; Dev, Preview, Branch ve Production context’lerinde gerçek sonuçlarla doğrulanmasıdır.

Örnek netlify. toml yapılandırmasını gerçek bir projede test 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.