Tarayıcı Projesinde Kütüphaneler ve CDN

Claude Code'dan tarayıcıda satranç yapmasını istiyorsunuz. Sayfayı açıyorsunuz: tahta yerinde, taşlar dizilmiş, piyon fareyi uysalca takip ediyor. Oyun oynanabilir gibi. Ama denemek için piyonu üç kare ileri sürükleyince orada kalıyor. Sonra siyahlarla arka arkaya iki hamle yapmayı deniyorsunuz. Sayfa yine itiraz etmiyor.

Bu iki hamleye kadar proje neredeyse hazır görünüyordu. Şimdi asıl eksiğin ortaya çıktığını görüyorsunuz: kuralları denetleyen yok. Ajandan piyonun böyle ilerlemesini engellemesini isteyebilirsiniz. Ardından hamle sırası, şah, rok ve piyonun terfisi konularını da çözmeniz gerekecek. Her düzeltmeden sonra şu soru kalır: başka hangi koşulu unuttunuz?

Tam bu noktada durup bu iş için hazır kod aramak iyi bir fikir. Satranç kuralları chess.js kütüphanesinde zaten uygulanmış. Ona bir hamle verip kurallara uygun olup olmadığını sorabilirsiniz. Böylece kendi kodunuz anlaşılır bir bağlantı kurar: tahtadaki hamleyi alır, kütüphaneye denetletir ve taşların doğru konumunu gösterir.

Geriye kütüphaneyi tarayıcıya ulaştırıp sayfanın çalışmasına dahil etmek kalıyor. Bunun bir yolu, CDN üzerinden bir bağlantıyla yüklemek. Aşağıda bunun nasıl işlediğine ve koddaki bir bağlantının piyonun artık istediği yere gidemeyeceği anlamına neden gelmediğine bakacağız.

Kütüphane Ne Yapar?

Kütüphane, zaten yazılmış olanı baştan yazmamak için projenize eklediğiniz başka birinin kodudur. chess.js tam da böyle bir örnek: her taşın nasıl hareket ettiğini, şah ve rok kurallarını bilir; mevcut konumdan yapılabilecek tüm hamleleri sıralayabilir ve oyunun bitip bitmediğini söyleyebilir.

Burada bir tuzağa düşmek kolay: kütüphaneyi ekleyip oyunun çalışmasını beklemek. Öyle çalışmaz. Kütüphane kuralları ve oyun konumunu belleğinde tutar; hiçbir şey çizmez, sayfada bir tahta olduğundan bile haberi yoktur.

Olağan bir hamlede neler olduğuna bakalım. Piyonu e2'den e5'e sürüklüyorsunuz. Arayüz sürüklemeyi algılıyor, bağlayıcı kod kütüphaneye "Bu hamle geçerli mi?" diye soruyor, kütüphane "hayır" yanıtını veriyor ve bağlayıcı kod taşı e2'ye geri götürüyor. Bu soruyu kimse sormazsa piyon e5'te kalır: sayfanın onu orada çizmesine hiçbir şey engel olmaz.

Her iki olasılık da aynı adımla biter: bağlayıcı kod kütüphanedeki konumu gösterir. Geçerli hamleden sonra konum yenidir, geçersiz hamleden sonra değişmez; bu yüzden taş ilk karesine döner.

Buradan görev isteğinin nasıl yazılacağına dair bir sonuç çıkarabiliriz. "chess.js'yi bağla" isteği kelimesi kelimesine yerine getirilebilir: bir yükleme satırı eklenir ve hepsi bu. İstekte tahta ile kütüphane arasındaki bağı tarif edin: tahtadaki hamle kütüphaneye gitsin, yanıtına göre taşın hareket edip etmeyeceği belirlensin ve hamleden sonraki konum, fareyi bıraktığınız yerden değil kütüphanenin durumundan alınsın.

Tarayıcı CDN Üzerinden Kodu Nasıl Alır?

Kütüphane dosyasını bir yerden edinmeniz gerekir. Dosyayı indirip kendi sayfanızın yanına koyabilir ya da sayfa kodunda harici bir servisteki dosyaya bağlantı verebilirsiniz. Bunun için sıkça CDN (Content Delivery Network, içerik dağıtım ağı) kullanılır. Bu, dosyaları kullanıcılara farklı konumlardan sunan bir sunucu ağıdır. Örneğin görseller, stiller ve JavaScript kütüphaneleri CDN üzerinden dağıtılır. Örneğimizde kütüphane dosyasını jsDelivr servisi sunuyor.

Sayfayı açtığınızda tarayıcı kodunu okur ve kütüphaneye giden bağlantıyla karşılaşır. Dosyayı bu adresten ister, yükler ve ardından kütüphaneyi kullanan sayfa kodunu çalıştırır. Kütüphane kullanıcının tarayıcısında çalışır. CDN kodu ulaştırır; satranç hamlelerinin denetimi artık sizin cihazınızda gerçekleşir.

Şemadaki çerçeve, tarayıcıyı harici servisten ayırıyor. Yüklemeden sonra kütüphane sayfanın içindedir: bağlayıcı kod ona aynı yerde erişir. Her hamleyi CDN'ye göndermeniz gerekmez.

chess.js bağlantısı şöyle görünür:

<script type="module">
  import { Chess } from 'https://cdn.jsdelivr.net/npm/chess.js@1.4.0/+esm'

  const chess = new Chess()
  console.log(chess.fen())
  // rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
</script>

Burada üç ayrıntı önemli. İlki type="module". Kütüphane bir ES modülü olarak gelir ve içindeki Chess sınıfına yalnızca import ile erişebilirsiniz; sıradan <script src="..."> etiketi bu dosyayı okuyamaz, içindeki export ifadesinde hata verir. Bazı kütüphanelerin modül kullanmayan eski bir dağıtımı da vardır: sıradan bir etiket yeterlidir ve sayfada kendiliğinden global bir değişken oluşur. chess.js için böyle bir derleme yok, dolayısıyla tek seçenek bu.

İkinci ayrıntı, sürüm numarasının doğrudan adreste yer alması: chess.js@1.4.0. Bağlantı yöntemini ve metot adlarını, URL'de belirtilen sürümün belgelerinden alın. Numarasız adres er ya da geç başka bir dosyaya yönelir ve eski belgelere göre yazılmış kod çalışmaz.

Üçüncü ve en az göze çarpan ayrıntı, adresin sonundaki /+esm. Bu bir süs değil, CDN'den dosyayı modül biçiminde derlemesini isteyen bir ek. Olmazsa aynı adresten başka bir derleme gelir ve import aradığını bulamaz.

Oyunun tamamını kurmadan da kütüphanenin gerçekten yüklenip yüklenmediğini kontrol edebilirsiniz. Aynı <script type="module"> içine birkaç satır ekleyip tarayıcı konsolunu açın (geliştirici araçlarındaki Console sekmesi, F12 veya Ctrl+Shift+I):

// beyaz piyon e2'den doğrudan e5'e gidemez
try {
  chess.move('e5')
} catch (error) {
  console.log('Hamle reddedildi:', error.message) // Invalid move: e5
}

chess.move('e4')          // bu hamleyi kütüphane kabul eder
console.log(chess.turn()) // b, sıra siyahlarda

Konsoldaki başlangıç konumu, reddedilen hamle ve e4'ten sonra sıranın siyahlara geçmesi, dosyanın ulaştığını ve kuralların çalıştığını gösterir. Sırada bunları tahtaya bağlamak var.

Bir de beklentiyi doğru ayarlayalım: CDN, ağ bağlantısına olan bağımlılığı ortadan kaldırmaz. Tarayıcı dosyanın önbellekteki kopyasını yeniden kullanabilir, bu yüzden her sayfa açılışında tekrar indirmesi gerekmez. Ancak uygun bir kopya yoksa ve CDN'ye erişilemiyorsa kütüphane yüklenmez; oyun da onun kurallarıyla çalışamaz.

Claude Code ile Birlikte Nasıl Çalışır?

"Kütüphaneyi CDN ile bağla" isteği ajana birkaç karar bırakır: dosyanın nereden alınacağı, hangi sürümün seçileceği, bu sayfaya nasıl yükleneceği ve sonucun nasıl doğrulanacağı. Bu kararları doğrudan görevde belirtmek daha kolay. Aşağıda farklı durumlar için prompt örnekleri var; hepsini arka arkaya göndermeniz gerekmiyor.

Bağlantı Adresini Seçme

Ajan bir kütüphane öneriyorsa, önce projenize nasıl bağlanacağını araştırmasını isteyin. Böylece elinizde somut bir adres ve bu adresin nereden geldiğine dair açıklama olur.

Sayfamın yapısına bak ve chess.js'nin zaten bağlı olup olmadığını kontrol et.
Kütüphane belgelerinde ve jsDelivr'de tarayıcıya uygun CDN yükleme
yöntemini bul. Belirli bir sürüm içeren URL öner ve adresin parçalarını
anlat. Belge bağlantılarını paylaş. Şimdilik kodu değiştirme.
Belgeleri doğrulayamazsan bunu belirt.

Yanıtta sürüm numarasını, bağlantı yöntemini ve seçimin nedenini arayın. Yalnızca "işte çalışan bir bağlantı" yanıtı yetmez: ondan ajanın adresi belgelerle karşılaştırıp karşılaştırmadığı ve dosyanın sayfanıza uygun olup olmadığı anlaşılmaz.

Kütüphaneyi Tahtaya Bağlama

Adres seçildikten sonra ajana sonucu görülebilen bir görev verin. Basit bir HTML sayfası için mevcut çalıştırma biçimini korumak istediğinizi de baştan belirtebilirsiniz.

chess.js'yi seçilen CDN adresi ve sabit sürümle bağla.
Sayfanın mevcut çalıştırma biçimini koru. Kütüphaneyi tahtaya bağla:
her hamleyi ona ilet ve durumundaki konumu göster.
Geçersiz hamlede taşı ilk karesine döndür.
Bağlantının eklendiği ve kütüphane yanıtının işlendiği yerleri göster.

Burada iki ayrı sonuç var: tarayıcı kütüphaneyi aldı ve tahtadaki hamleler kütüphanenin kurallarından geçmeye başladı. Kodda her iki yeri de göstermesini isterseniz ajanın ne eklediğini görebilirsiniz.

Sonucu Tarayıcıda Denetleme

HTML'de bağlantının bulunması yalnızca dosyanın değiştirildiğini doğrular. Sıradaki istek, yüklemeyi ve oyunun davranışını kontrol etmenize yardımcı olur.

Sayfayı aç ve geliştirici araçlarının Network sekmesinde chess.js'nin
yüklenmesini kontrol et. Console'daki hatalara bak. Ardından başlangıç
konumundan e2-e5'i dene: hamle reddedilmeli, piyon e2'de kalmalı.
Sonra e2-e4 yap: hamle kabul edilmeli, sıra siyahlara geçmeli.
Her adımda ne gözlemlediğini bildir. Tarayıcıya erişimin yoksa,
bana kısa kontrol adımları ver ve kendin doğrulamadığını belirt.

Network sekmesinde sayfanın ağ istekleri, Console'da ise kodun mesajları ve hataları görünür. Dosya yüklenmesine rağmen piyon e5'e gidiyorsa nedeni hamlenin işlenişinde aramak gerekir. CDN adresini değiştirmek, tahta ile kütüphane arasındaki bu bağı tek başına düzeltmez.

Yükleme Hatasını İnceleme

Bir hata oluştuğunda Console'daki tam hata metnini ve başarısız isteğin Network'teki adresini ajana iletin. Böylece bağlantı seçeneklerini denemek yerine belirli bir nedeni araştırabilir.

Kütüphaneyi bağladıktan sonra sayfada bir hata oluşuyor.
Console'daki metin: [mesajın tamamını buraya yapıştırın].
Network'teki URL ve istek sonucu: [adres ve durum kodunu ekleyin].
Dosyanın erişilebilir olup olmadığını, biçiminin import işlemimize
uyup uymadığını ve koddaki adların seçilen sürümün belgeleriyle
örtüşüp örtüşmediğini denetle.
Önce bu verilere dayanarak nedeni söyle, sonra en küçük düzeltmeyi yap
ve kontrolü tekrarla. CDN'yi, sürümü ve oyun kodunu aynı anda değiştirme.

Köşeli parantez içindeki metni kendi verilerinizle değiştirin. Network'te kütüphane isteği hiç yoksa bunu da belirtin: bu da işe yarar bir ipucu. Düzeltmeden sonra tüm zincirin çalıştığını doğrulamak için iki hamleyi yeniden deneyin.

CDN Erişilemezse Ne Olacağını Planlama

Kütüphane yüklenmezse etkin tahta, oynanabiliyormuş gibi yanlış bir izlenim verebilir. Ajanınızdan bu durumu kullanıcıya anlaşılır biçimde göstermesini isteyin.

chess.js CDN'den yüklenemediğinde ne olacağını ele al.
Kütüphane hazır olana kadar hamlelere izin verme. Hata oluşursa
anlaşılır bir mesaj ve sayfayı yeniden yükleme seçeneği göster.
Önce CDN isteği engelliyken, sonra engel kaldırıldığında davranışı
kontrol et. Önbelleği hesaba kat: ağı kapatmak, önceden yüklenmiş
bir kopyayı kullanılabilir bırakabilir. Hatayı nasıl denetlediğini anlat.

Bu kontrolü olağan bir oyundan ayrı yapmak daha kolay. Sonuçta iki açık durum görmelisiniz: kütüphane erişilebilir ve hamleler denetleniyor; ya da yükleme başarısız ve sayfa neden henüz oynayamadığınızı açıklıyor.