# Gemini CLI ile SvelteKit projeleri: pratik rehber

Adres: https://agentvera.dev/blog/gemini-cli-ile-sveltekit/ · Yayın: 2026-11-01

Gemini CLI ile SvelteKit uygulamalarında route, load, form action ve test işlerini yönetin. GEMINI.md kurulumu, çalışma döngüsü ve doğrulama ipuçları.

**Kısaca:**

- Gemini CLI’yi SvelteKit’te GEMINI.md ile yönlendirerek route, load ve action değişikliklerini hızlandırırsınız.
- Küçük adımlarla planlama, test çalıştırma ve diff inceleme döngüsü ajanın SvelteKit’e özgü hatalarını azaltır.
- Paralel ajanlar için git worktree ve ayrı terminaller kullanmak aynı proje üzerinde çakışmayı önler.

Gemini CLI’yi SvelteKit proje klasöründe `gemini` komutuyla başlattığınızda ajan dosya ağacını, package.json betiklerini ve GEMINI.md talimatlarını okuyarak route, load, form action ve test işlerinde size yardımcı olur. Bu rehber, ajanın SvelteKit’e özgü davranışlarını denetlemek ve üretken bir döngü kurmak için pratik adımları anlatır. Gemini CLI hakkında genel bilgi için [Gemini CLI](/ajanlar/gemini-cli/) sayfasına, ilk adımlar için [Gemini CLI nasıl kullanılır?](/blog/gemini-cli-nasil-kullanilir/) rehberine bakabilirsiniz.

## Gemini CLI neden SvelteKit işlerine uygun?

SvelteKit, dosya tabanlı routing sayesinde ajanın proje yapısını hızlı kavramasını sağlar. `src/routes` altındaki `+page.svelte`, `+page.ts`, `+page.server.ts` ve `+server.ts` dosyaları bir arayüz sözleşmesi gibidir; ajan, server ve client kodunu ayırt edebilir. Örneğin bir liste sayfası isteğinde load fonksiyonunun `+page.server.ts` içinde mi yoksa `+page.ts` içinde mi olması gerektiğini GEMINI.md’deki kurallara göre değerlendirir. Form action’larının `actions` exportu, `$app/forms` ve `invalidateAll` kullanımı gibi SvelteKit’in kendine özgü kalıplarını öğrenir. Ayrıca `npm run check`, Vitest ve Playwright gibi araçlarla değişikliğin doğruluğunu test etmeye yatkındır. Bu sayede ajan yalnızca kod yazmaz; route bütünlüğünü ve tip güvenliğini de gözetir. Svelte compiler’ının anlık önerileri ajanın hatalarını erken yakalamasına yardımcı olur; `svelte-check` çıktısı üzerinden düzeltme önerileri isteyebilirsiniz. Buna ek olarak SvelteKit’in server/client ayrımını netleştiren `+page` ve `+server` dosyaları, ajanın hangi kodu SSR sırasında çalıştıracağını, hangi kodu yalnızca tarayıcıda kullanacağını daha kolay belirlemesini sağlar.

## Proje kurulumu ve GEMINI.md

Ajan başlatılmadan önce projede net bir GEMINI.md bulunması en büyük farkı yaratır. Bu dosyaya yalnızca genel kurallar değil, SvelteKit projesinin somut komutlarını ve dizin varsayımlarını yazın. `package.json` içindeki script’lere ek olarak GEMINI.md’de lint, format ve test araçlarının nasıl kullanılacağını belirtin. Örneğin projede ESLint ve Prettier varsa, ajanın her değişiklik sonrası `npm run lint` ve `npm run format` çalıştırmasını isteyin. Ayrıca hangi paket yöneticisinin kullanıldığını (npm, pnpm, yarn) ve SvelteKit’in hangi adaptor ile deploy edildiğini not edin; bu, `adapter-node` veya `adapter-static` arasındaki farklı runtime varsayımlarını ortadan kaldırır. GEMINI.md, ajanın aşağıdaki örnekteki gibi net talimatlarla çalışmasını sağlar:

```markdown
# SvelteKit projesi için GEMINI.md

## Komutlar
- Dev: npm run dev
- Derleme: npm run build
- Tip kontrolü: npm run check
- Lint: npm run lint
- Birim test: npm run test:unit
- Uçtan uca test: npm run test:e2e
- Format: npm run format

## Dizin kuralları
- Sayfalar src/routes altındadır; her route için +page.svelte, +page.ts ve/veya +page.server.ts kullanın.
- Ortak bileşenler src/lib/components altında, server-only yardımcılar yalnızca src/lib/server altında olmalı.
- Statik varlıklar static/ altında tutulur; import etmek için $lib veya $app yollarını kullanın.

## SvelteKit'e özgü kurallar
- Veri çekme önceliği +page.server.ts veya +server.ts olmalı; client'ta fetch kullanmaktan kaçının.
- Form gönderimleri +page.server.ts içindeki actions ile yönetilir; fail() ve redirect() @sveltejs/kit'ten, enhance $app/forms'dan import edilir.
- Browser API'leri yalnızca onMount içinde veya browser kontrollü koşullarda kullanın; SSR sırasında window/document erişmeyin.
- Sunucuya özel ortam değişkenleri $env/static/private veya $env/dynamic/private ile, client'a açılacaklar $env/static/public veya $env/dynamic/public ile alınmalıdır.
- Mevcut adaptor ve route yapısını değiştirmeden çalışın.
- State yönetimi için Svelte stores kullanın; custom store'ları src/lib/stores altına koyun.
- `setContext` ve `getContext` yalnızca kurucu (constructor) içinde eşleştirilmelidir.

## Test
- Vitest için test dosyaları src/lib/__tests__ veya route'a yakın olabilir.
- Playwright testleri tests/ altında; route etkileşimleri için data-testid kullanmayı tercih edin.
- E2E testlerinden önce `npm run build` yapmayı unutmayın.
```

Bu dosya kısa ama nettir. Ajan, komutları doğru çalıştırmak için package.json’a bakar; GEMINI.md ise yanlış katmana kod yazmasını engeller. Örneğin `src/lib/api.ts` içindeki fetch çağrısını client tarafına açmak yerine, ajan `src/lib/server` altında tutmayı öğrenir. GEMINI.md yoksa SvelteKit’e özgü bu tür kararlar tahmine kalır ve sık sık SSR hataları veya bundle boyutu artışı yaşanır.

## Çalışma döngüsü: planla, küçük adımla, test, diff

Gemini CLI ile en verimli döngü, büyük bir isteği tek seferde vermek yerine görevi parçalara bölmektir. Önce ajanın plan yapmasını isteyin; ardından yalnızca planı uygulamasını, testleri çalıştırmasını ve diff çıktısını göstermesini söyleyin. Her adımdan sonra `git diff` ile değişiklikleri inceleyin. Özellikle `+page.server.ts` ve `+page.ts` arasındaki taşımalarda serialization hatalarını kontrol edin. Prompt yazımı için genel kalıpları [Kodlama ajanları için prompt nasıl yazılır?](/blog/kodlama-ajanlari-icin-prompt-yazmak/) yazısında bulabilirsiniz.

Tipik SvelteKit görevleri için örnek promptlar:

- "src/routes/checkout/+page.server.ts içine `actions.default` ekle; form verilerini bir schema ile doğrula, hata varsa fail(400, { errors }) döndür, başarılıysa redirect(303, '/success') yap."
- "Mevcut src/routes/products/+page.ts içindeki load fonksiyonunu +page.server.ts’e taşı; fetch’i server tarafında yap ve dönen veriyi döndür. Client bundle’a API URL’si sızmasın."
- "src/lib/server/products.ts oluştur ve ürün listeleme sorgusunu oraya taşı; +page.server.ts load fonksiyonu bu fonksiyonu çağırsın. Unit test ekle."
- "Vitest ile src/lib/utils/price.spec.ts yaz; fiyat formatlama ve kdv hesaplama fonksiyonlarını test et. npm run test:unit çalıştır ve başarısız testleri düzelt."
- "Playwright testi ekle: /login sayfasında boş form gönderilince hata mesajı görünüyor mu ve form action fail durumları doğru mu kontrol et."
- "src/routes/api/products/+server.ts oluştur; GET isteğinde ürünleri JSON döndür, limit ve offset query parametrelerini destekle. Hata durumunda 400 veya 500 döndür."
- "Mevcut src/routes/dashboard/+layout.ts içindeki kullanıcı kontrolünü +layout.server.ts’e taşı; redirect kullanarak giriş yapmamış kullanıcıları /login’e yönlendir."

Bu promptlar ajanın işi anlamasını kolaylaştırır; her seferinde yalnızca bir katmanı veya bir route’u hedefleyin. Planlama aşamasında ajana "ilk olarak hangi dosyaları değiştireceğini ve neden" sorun; onay verdiğinizde uygulamaya geçsin. Uygulama sonrası `npm run check` çalıştırmasını ve hataları düzeltmesini isteyin. Böylece döngü 5-10 dakikada tamamlanır ve geri dönüşler kısa olur.

## SvelteKit’te güçlü olduğu işler ve dikkat edilecekler

Ajan, yeni route ekleme, load fonksiyonu yazma, form action oluşturma, +server.ts endpoint dönüştürme ve mevcut kodun server/client ayrımını düzeltme gibi iyi tanımlanmış işlerde hızlıdır. Örneğin bir ürün listesi sayfası için `+page.server.ts`, load ve `+page.svelte` üçlüsünü birlikte oluşturabilir. Test yazmak da güçlü olduğu alanlardandır; Vitest betiği eklemek için izole fonksiyonları tespit eder. Aynı şekilde Svelte 5 runes API’si (`$state`, `$derived`) kullanımı istenirse ajan bu dönüşümü uygulayabilir, ancak bu tür kapsamlı geçişlerde manuel inceleme şarttır.

Dikkat edilmesi gereken yerler SvelteKit’e özgüdür:

- Server-only kodun client’a sızması: `$lib/server` dışında kalan importlar yanlışlıkla client bundle’a girebilir. Ajanın her değişiklik sonrası `npm run build` çalıştırmasını isteyin.
- SSR varsayımı: Ajan bazen `window` veya `document` kullanabilir; bu, tarayıcıda değil server’da çalışan load sırasında patlar. `onMount` veya `browser` kontrolü eklemesini hatırlatın.
- Form action dönüş tipleri: `fail` ve `redirect` importları karışabilir; action’un döndürdüğü `errors` nesnesinin sayfada doğru okunması gerekir.
- `invalidateAll` veya `invalidate` kullanımı: Ajan bazen güncel veri için `invalidateAll`'ı atlar; form sonrası listeyi güncellemek istiyorsanız bunu prompt’a ekleyin.
- Adapter ve environment değişkenleri: Ajan, varsayılan adapter-node dışında bir yapıyı varsayabilir. GEMINI.md’de mevcut adapter’ı belirtin ve ortam değişkeni yönetimini netleştirin.
- `$app/navigation` ve `$app/stores` importları: Ajan bazen `page` store’unu server tarafında kullanmaya çalışır; bu yalnızca client’ta geçerlidir. Sunucu tarafında `locals` veya `url` parametresini kullanmasını isteyin.
- Svelte component’lerinde reaktivite: Ajan, bir değişkene yeniden atama yapması gerektiğinde `let` kullanmayı unutabilir veya yanlış yerde `$:` bloğu oluşturabilir. Basit bir kullanıcı arayüzü değişikliğinde bile diff’i gözden geçirin.
- `+layout` dosyalarındaki load fonksiyonlarında dönen veri türü: Layout load’ları, child sayfalar için de çalışır; ajan bazen bu veriyi gereksiz yere yeniden fetch eder. Gereksiz request’leri önlemek için `setContext` veya `data` geçişini yönlendirin.

## SvelteKit’te test ve doğrulama

Gemini CLI’ya her zaman "testleri çalıştır, çıktıyı rapor et" komutunu verin. SvelteKit’te `npm run check` ile tip hatalarını, `npm run test:unit` ile Vitest birim testlerini, `npx playwright test` ile uçtan uca testleri doğrularsınız. Aşağıdaki tablo, hangi katmanda hangi doğrulamanın anlamlı olduğunu gösterir.

| SvelteKit katmanı | Doğrulama komutu | Ajanın kontrol etmesi gereken |
| --- | --- | --- |
| `+page.ts` load | `npm run test:unit` | Veri dönüşümü ve error/redirect yolları |
| `+page.server.ts` action | `npm run test:unit` | fail/redirect dönüşleri ve validation |
| `+server.ts` endpoint | `npm run test:unit` veya `npx playwright test` | Durum kodları ve JSON yanıt |
| Svelte bileşeni | `npx playwright test` | Kullanıcı etkileşimi ve DOM durumu |

Ajan test çıktısını yorumlayıp düzeltir; ancak testlerin gerçekten çalıştığını doğrulamak için komut çıktısını isteyin. Playwright testlerinde ajan, selector yerine `data-testid` eklemeyi öğrenmelidir. GEMINI.md’ye "Playwright testleri için data-testid kullan" notunu eklemek seçici hatalarını azaltır. Vitest için ajanın `src/lib` altındaki saf fonksiyonlara odaklanmasını sağlayın; Svelte component testleri istiyorsanız `@testing-library/svelte` gibi bir kütüphane kullanılıp kullanılmadığını GEMINI.md’ye yazın. Ayrıca ajanın test dosyalarını doğru konumda oluşturduğundan emin olun; Vitest config dosyasında `include` pattern’ini kontrol edin. Son olarak, tüm testler geçtikten sonra `npm run build` çalıştırarak production build’de SSR hataları olmadığını doğrulayın.

## Aynı projede birden fazla ajan: AgentVera

Birden fazla Gemini CLI oturumunu aynı SvelteKit projesinde çalıştırmak istediğinizde AgentVera kullanışlıdır. AgentVera masaüstü uygulaması, gerçek komut satırı ajanlarını tek pencerede yan yana çalıştırır; her ajan kendi git worktree’sinde ilerleyebildiği için iki farklı route üzerinde aynı anda çalışmak dosyaları ezmez. Bir ajanın turu bitince ikinci model kodunu inceler ve bulguları dosya:satır olarak gösterir; bu, `+page.server.ts`'ye yanlışlıkla client-only kod sızmasını yakalamakta iyidir. Checkpoint’ler sayesinde hatalı bir route değişikliği tek tıkla geri alınabilir ve oturum adım adım izlenebilir. Günlük token bütçesi ise uzun test döngülerinin kontrolden çıkmasını önler.

## Sonuç

Gemini CLI’yi SvelteKit’te etkili kullanmanın anahtarı, GEMINI.md ile proje kurallarını netleştirmek, küçük adımlarla plan yapmak ve her değişikliği test ile doğrulamaktır. Böylece route, load, form action ve endpoint işleri hızlanır; düzeltme yükü azalır. Ajanı bir asistan olarak değil, yönlendirmeye ihtiyaç duyan bir geliştirici gibi düşünün; net talimatlar ve kapsamlı test altyapısı onun en büyük gücünü ortaya çıkarır. Zaman içinde GEMINI.md’yi projenin alışkanlıklarına göre güncelleyin; böylece ajan her yeni oturumda daha isabetli kod üretir. SvelteKit’in dosya tabanlı mimarisi ve güçlü test araçları, Gemini CLI ile birleştiğinde rutin geliştirme görevlerini büyük ölçüde hızlandırır.

## Sık sorulanlar

**Gemini CLI SvelteKit projesinde nasıl başlatılır?** Proje klasöründe gemini komutu çalıştırılır. Ajan, GEMINI.md dosyasındaki talimatları ve package.json’daki komutları okuyarak SvelteKit kurallarına göre çalışır. İlk komut genellikle plan isteyen kısa bir görev olmalıdır.

**GEMINI.md’de SvelteKit için neler bulunmalı?** Build, test, lint komutları; src/routes klasör yapısı; +page, +server, load ve form action kuralları; state yönetimi; Vitest ve Playwright kullanımı gibi projeye özgü talimatlar yer almalıdır.

**Gemini CLI SvelteKit’te hangi görevlerde güvenilir?** Yeni route ekleme, load fonksiyonu yazma, form action, API endpoint ve test senaryoları gibi iyi tanımlanmış işlerde güvenilirdir. Karmaşık state akışları veya SSR/CSR geçişlerinde çıktıyı gözden geçirmek gerekir.

**Gemini CLI ile test ve doğrulama nasıl yapılır?** Ajan her değişiklikten sonra npm run test veya npm run test:unit çalıştırabilir. Playwright için npx playwright test kullanılır ve ajan çıktıyı yorumlayıp düzeltme önerir; diff incelemesi şarttır.

---

**AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/