Netlify CLI ve Netlify Dev Nasıl Kullanılır? Yerel Geliştirme Rehberi

Netlify CLI, proje oluşturma ve bağlama, production’a yakın build alma, Functions ve redirects davranışını yerelde test etme, environment variables yönetme ve deploy başlatma işlemlerini terminalden yapmanızı sağlayan komut satırı aracıdır. netlify dev, framework dev server’ı ile Netlify primitive’lerini aynı yerel ortamda çalıştırır; netlify build ise Netlify build pipeline’ına daha yakın bir production build doğrulaması sunar.

Vite tabanlı yeni projelerde @netlify/vite-plugin bazı Netlify özelliklerini doğrudan Vite dev server içinde emüle edebilir. Bu, Netlify CLI’nin gereksiz olduğu anlamına gelmez. Proje linkleme, environment yönetimi, log, build ve deploy akışları için CLI hâlâ güçlü bir araçtır.

Öne Çıkanlar

• CLI global veya proje bazlı çalıştırılabilir; sürüm her testte kaydedilmelidir.
• netlify login browser üzerinden hesabı yetkilendirir; access token terminal görüntüsünde paylaşılmamalıdır.
• netlify link, yerel klasörü mevcut Netlify projesiyle eşleştirir.
• netlify dev, Functions, redirects, headers ve environment context’ini yerelde test etmeyi kolaylaştırır.
• netlify build, yalnız framework build’inden farklı olarak Netlify yapılandırmasını da uygular.
• netlify deploy draft/preview URL; netlify deploy --prod production deploy oluşturabilir.
• Yerel emülasyon production’ın domain, region, cache ve üçüncü taraf callback davranışının tam kopyası değildir.

1. Netlify CLI Nedir ve Ne Zaman Kullanılır?

Dashboard hızlı kurulum için yeterlidir; CLI ise tekrarlanabilir ve gözlemlenebilir bir terminal akışı sağlar. Özellikle şu durumlarda yararlıdır:

• Mevcut yerel projeyi Netlify hesabına bağlamak,
• CI’dan önce Netlify build davranışını görmek,
• Function ve Edge Function’ı yerelde çağırmak,
• _redirects ve netlify.toml kurallarını test etmek,
• Environment variable’ları listelemek veya güncellemek,
• Git entegrasyonundan bağımsız draft deploy oluşturmak,
• Build logu ve deploy URL’sini script içinde kullanmak.

CLI kullanmak Git tabanlı continuous deployment’ın alternatifi olmak zorunda değildir. Geliştirici yerelde netlify dev ve netlify build kullanırken production release’i Git merge ile yönetebilir.

2. CLI Nasıl Kurulur ve Kimlik Doğrulama Nasıl Yapılır?

Global kurulum için:

``bash npm install -g netlify-cli ``

Kurulumu doğrulayın:

``bash netlify --version netlify status ``

Global paket istemiyorsanız uygun package runner ile proje bağlamında da çalıştırabilirsiniz. Takım içinde farklı CLI sürümlerinin davranış farkı yaratmasını önlemek için sürümü dokümante edin veya proje dev dependency’si olarak sabitleyin.

Hesaba giriş:

``bash netlify login ``

Komut browser’da Netlify authorization ekranı açar. Giriş sonrası terminalde account bilgisi görünebilir. Ekran görüntüsü paylaşırken e-posta, team slug, site ID ve token gibi değerleri gerektiği ölçüde redakte edin.

Headless CI ortamında interactive login yerine güvenli CI secret’ı kullanılabilir. Token’ı komut satırına açıkça yazmak shell history’ye girebilir; CI secret store ve dar yetkili credential tercih edin.

Çıkış:

``bash netlify logout ``

Ortak bilgisayar veya geçici geliştirme ortamında oturumun kapandığını doğrulayın.

3. Mevcut Proje netlify link ile Nasıl Bağlanır?

Yerel klasörde:

``bash cd my-project netlify link ``

CLI mevcut team ve projeler arasında seçim yaptırabilir. Proje henüz yoksa netlify init ile yeni proje ve Git continuous deployment akışı kurulabilir.

Bağlantı sonrasında yerel . netlify klasöründe site ilişkilendirme bilgisi tutulabilir. Bu klasör genellikle Git’e eklenmez:

``gitignore .netlify/ ``

Doğru projeye bağlı olduğunuzu kontrol edin:

``bash netlify status ``

Aynı klasörün yanlış production projesine linklenmesi, --prod kullanıldığında ciddi hata yaratabilir. Deploy öncesinde site adı, team ve site ID’yi gözden geçirin.

Birden fazla müşteri projesi veya environment ile çalışıyorsanız terminal prompt’unda aktif proje adını görünür kılmak ve production komutlarını script arkasına almak faydalıdır.

4. netlify dev ile Yerel Ortam Nasıl Çalıştırılır?

Bağlı proje klasöründe:

``bash netlify dev ``

CLI framework’ü algılayıp uygun dev command ve portu çalıştırabilir. Ardından Netlify katmanı için yerel bir URL verir. Bu URL üzerinden framework sayfaları, Functions, redirects ve headers birlikte test edilir.

netlify. toml içinde dev ayarı gerekebilir:

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

Burada:

• targetPort, framework dev server portudur.
• port, Netlify Dev proxy’nin dışarı açtığı porttur.
• Browser, doğrudan Vite portu yerine Netlify Dev URL’sinden açılmalıdır; aksi hâlde Function ve redirect emülasyonu atlanabilir.

Framework auto-detection yanlış command seçerse dosya tabanlı yapılandırmayla açıkça tanımlayın. Port zaten kullanılıyorsa çalışan process’i kapatın veya farklı port belirleyin.

5. Functions Yerelde Nasıl Test Edilir?

Varsayılan Function dizini:

``text netlify/functions/ └── hello.mts ``

Basit Function:

``ts export default async () => { return Response.json({ message: "Merhaba", source: "netlify-function" }); }; ``

netlify dev çalışırken yaygın Function URL biçimi:

``text http://localhost:8888/.netlify/functions/hello ``

Test:

``bash curl -i http://localhost:8888/.netlify/functions/hello ``

Framework veya Function config ile özel path tanımlanmışsa URL değişebilir. Production’da da aynı status code, content type ve response shape doğrulanmalıdır.

Yerel testte input validation, method kontrolü ve hata yanıtı da denenmelidir:

```ts export default async (request: Request) => { if (request.method !== "GET") { return Response.json( { error: "Method not allowed" }, { status: 405, headers: { Allow: "GET" } } ); }

return Response. json({ ok: true }); }; ```

Bu kod örneği taslak hazırlanırken çalıştırılmamıştır; yayın öncesi güncel runtime’da doğrulanmalıdır.

6. Redirects ve Headers Yerelde Nasıl Test Edilir?

public/_redirects örneği:

``text /old-page /new-page 301 /api/ /.netlify/functions/api/:splat 200 / /index.html 200 ``

netlify dev çalışırken:

``bash curl -I http://localhost:8888/old-page curl -i http://localhost:8888/api/status curl -I http://localhost:8888/about ``

Kural sırası önemlidir. Geniş SPA fallback, API rewrite kuralından önce gelirse API isteğini index. html dosyasına gönderebilir. Exact ve özel kuralları wildcard’dan önce tutun.

Headers netlify. toml içinde test edilebilir:

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

Yerel sonuç production edge davranışıyla yeniden karşılaştırılmalıdır.

7. Environment Variables Yerelde Nasıl Yönetilir?

CLI komutlarıyla proje değişkenleri görüntülenebilir ve yönetilebilir. Güncel komut seçeneklerini netlify env --help ile doğrulayın:

``bash netlify env:list netlify env:get API_ORIGIN ``

Yeni dummy değer eklemek için güncel CLI söz dizimi kullanılmalıdır:

``bash netlify env:set DEMO_MODE true ``

Gerçek secret değerini terminal transcript’ine veya ekran görüntüsüne yazmayın. CLI output’u redakte edin.

Yerel . env dosyası da framework tarafından okunabilir; fakat Netlify project variables ile . env arasındaki öncelik ve context davranışı farklı olabilir. netlify dev altında hangi kaynağın yüklendiğini test edin.

Client framework uyarısı:

• Vite: VITE_ önekli değer browser’a açılır.
• Next.js: NEXT_PUBLIC_ browser’a açılır.
• Create React App: REACT_APP_ browser’a açılır.

Bu public prefix’lere private key koymayın.

8. netlify build ile Production Build Nasıl Doğrulanır?

Framework’ün npm run build komutu yalnız uygulama build’ini çalıştırabilir. netlify build, Netlify build pipeline’ının yapılandırmasını, context’i ve plugin/Function adımlarını daha yakından simüle eder:

``bash netlify build ``

Belirli context davranışını test etmek için güncel CLI option’larını kontrol edin. Build çıktısında şunları kaydedin:

• CLI sürümü,
• Build context,
• Base ve publish directory,
• Framework ve plugin algılaması,
• Functions bundling,
• Redirect/header işleme,
• Environment variable scope,
• Toplam süre ve exit code.

Yerel build başarılı olsa bile production cloud build; işletim sistemi, resource limit, region, network ve injected variable açısından farklı olabilir. Git deploy logu son doğrulama noktasıdır.

9. Draft ve Production Deploy Nasıl Yapılır?

Önce draft deploy:

``bash netlify deploy ``

CLI publish directory sorabilir veya netlify. toml değerini kullanabilir. Çıktıda draft deploy URL’si bulunur. Bu URL’yi test edin ve hangi source commit/build’den geldiğini kaydedin.

Production deploy:

``bash netlify deploy --prod ``

Bu komut ana production domain’i güncelleyebilir. Çalıştırmadan önce:

• Doğru siteye linkli misiniz?
• Yerel çalışma ağacı temiz mi?
• Production build gerçekten alındı mı?
• Hangi publish directory gönderiliyor?
• Environment context doğru mu?
• Git tabanlı release politikasını bypass ediyor musunuz?

sorularını yanıtlayın.

Takımlarda doğrudan --prod yetkisini sınırlamak veya production deploy’u yalnız CI/Git merge üzerinden yapmak daha güvenli olabilir.

10. Netlify CLI ile Yerel ve Production Farkları

Alan	Yerel	Production
Domain	localhost	netlify.app/custom domain
TLS	Yerel proxy davranışı	Gerçek HTTPS sertifikası
Region	Geliştirici makinesi	Function/edge altyapısı
Cache	Emülasyon/sınırlı	Dağıtık CDN cache
Environment	Local + project vars	Deploy context scope
Üçüncü taraf callback	localhost desteklemeyebilir	Public URL
Performans	Makine/ağ etkisi	Gerçek platform ve kullanıcı konumu
Log	Terminal	Netlify logs/observability

Local parity hedeflenir; tam eşitlik varsayılmaz. Özellikle cookie domain, OAuth callback, CORS, caching ve latency production’da yeniden test edilmelidir.

11. Yaygın CLI Hataları ve Çözümleri

Not logged in

netlify login çalıştırın ve doğru account/team yetkisini doğrulayın. CI’da token secret’ının mevcut olduğundan emin olun.

Yanlış siteye deploy

netlify status ile site adını kontrol edin. Gerekirse link’i kaldırıp doğru projeye yeniden bağlayın. Production komutundan önce otomatik doğrulama script’i kullanın.

Port kullanımda

[dev] port veya framework portunu değiştirin. Aynı projenin eski dev process’inin açık olmadığını kontrol edin.

Function 404

Functions directory, dosya export biçimi ve URL path’i kontrol edilmelidir. Build logunda Function’ın bulunduğunu doğrulayın.

Environment variable görünmüyor

Scope/context uyuşmuyor, dev server değişiklikten önce başlamış veya public prefix yanlış olabilir. Değeri loglamak yerine varlık ve context etiketiyle doğrulayın.

Yerel redirect çalışıyor, production’da çalışmıyor

_redirects dosyası publish directory’ye kopyalanmamış olabilir. Deploy dosya ağacını ve netlify. toml önceliğini kontrol edin.

Global CLI eski

``bash npm update -g netlify-cli netlify --version ``

Komutlar release’lerle değişebileceği için yayın günü yeniden çalıştırın.

Zorunlu Terminal Test Günlüğü

Adım	Komut	Sürüm/çıktı	Süre
Kurulum	netlify --version	Kaydedilecek	Ölçülmedi
Login	netlify login	Redakte edilecek	Ölçülmedi
Link	netlify link	Site adı maskeli	Ölçülmedi
Dev	netlify dev	Local URL	Ölçülmedi
Function	curl .../hello	Status/body	Ölçülmedi
Build	netlify build	Exit code	Ölçülmedi
Draft	netlify deploy	Draft URL redakte	Ölçülmedi
Prod	netlify deploy --prod	Test site URL	Ölçülmedi

> Editör notu — zorunlu özgün kanıt: Bu taslak hazırlanırken komutlar temiz bir ortamda sırasıyla çalıştırılmadı. Yayından önce geçici demo hesabı ve proje kullanılmalı; OS, Node, package manager ve Netlify CLI sürümü; başlangıç/bitiş zamanı; exit code ve redakte URL’ler kaydedilmelidir. Gerçek token veya secret hiçbir görselde bulunmamalıdır.

> Görsel notu: Install → login → link → dev → build → draft deploy → production deploy akışını gösteren diyagram ve redakte terminal transcript’i hazırlanmalıdır.

> İç link editör notu: netlify. toml, Functions ve environment variables yazıları yayına girdiğinde ilgili bölümlere bağlantı eklenmelidir.

Sık Sorulan Sorular

Netlify CLI olmadan deploy yapılabilir mi?

Evet. Dashboard Git bağlantısı, Netlify Drop ve API gibi seçenekler vardır. CLI terminal tabanlı yerel test ve deploy kontrolü sağlar.

netlify dev ile Vite’ın npm run dev komutu aynı mı?

Hayır. Vite dev server frontend geliştirme sunar; netlify dev Netlify Functions, redirects, headers ve project variables gibi platform davranışlarını proxy katmanında birleştirebilir. Yeni Vite plugin bazı primitive’leri doğrudan Vite içinde emüle edebilir.

netlify build production ile birebir aynı mı?

Production’a daha yakın yapılandırma doğrulaması sağlar; cloud runtime, region, network, cache ve secret injection farkları kalabilir.

netlify deploy production’ı günceller mi?

Varsayılan komut draft deploy üretir. --prod production deploy oluşturur; çalıştırmadan önce aktif site ve publish directory kesin olarak doğrulanmalıdır.

CLI token’ı repository’ye konur mu?

Hayır. CI secret store veya platformun güvenli variable alanı kullanılmalıdır. Token sızarsa iptal edilip yenilenmelidir.

Kaynaklar

• Get started with Netlify CLI
• Local development with Netlify CLI
• Build configuration
• Environment variables
• Get started with Functions
• Netlify CLI reference

Sonuç

Netlify CLI, dashboard ayarlarını terminalde tekrarlanabilir bir geliştirme akışına dönüştürür. netlify link ile doğru projeyi eşleştirin, netlify dev ile Function ve routing davranışını yerelde deneyin, netlify build ile production yapılandırmasını doğrulayın ve önce draft deploy alın. Local ortamı production’ın tam kopyası saymayın; custom domain, cache, region ve third-party callback’leri gerçek deploy’da yeniden test edin.

Netlify CLI ve Netlify Dev komutlarını bir demo projede uygulamak için [ücretsiz hesap 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.