Cloudflare Workers'a bir sayfa nasıl yayınlanır

Elinizde hazır bir sayfa içeren klasör var, ama bağlantısı yok. Onu Cloudflare Workers'a yayınlayalım, süreci de Claude Code'a bırakalım: yayınlama ve güncellemeyi kısa bir isteğe indirgeyen bir skill oluşturacağız.

1. Statik dosyalar için Cloudflare Workers nedir

Workers kelimesi "sunucuda çalışan programlar" gibi geliyor ve bu doğru. Ama işin tamamı bu değil: bir worker'a bir dosya klasörü eklenebilir ve o zaman sunucu bunları sıradan bir hosting gibi doğrudan sunar. Bu sırada tek satır kod bile yazılmaz.

HTML, CSS ve görsellerden oluşan bir sayfa için bu mod yeterlidir. Belgelerde bu klasöre static assets, yani statik varlıklar denir; proje ayarlarında da yalnızca tek bir alan kaplar: klasörün yolu.

Cloudflare dosyaları kendi sunucu ağı üzerinden dağıtır ve ziyaretçilere daha yakın konumlarda önbelleğe alır.

2. Bunun maliyeti ne kadar

Statik dosyalara yapılan istekler ücretsizdir ve sayıca sınırsızdır. Bu tarifenin bir koşuludur, ziyaret istatistiği tutulmadığına dair bir vaat değil.

Peki o bilinen sayı nereden geliyor - günde 100.000 istek? Bu, sunucudaki o programın, yani Worker script'inin çağrılarına konan bir limit. Yalnızca bir klasör eklenmiş bir sayfada script yoktur, dolayısıyla bu sayaca girmez.

Şemadaki üst yol sayfamıza uygun: dosya, sunucu tarafı program çağrılmadan gönderilir. Alt yol ise daha sonra bir Worker script'i eklenirse gerekli olur.

Ücretsiz tarifenin yine de limitleri var, ama bunlar başka bir şeyle ilgili - yayınladığınız şeyin boyutuyla:

Bir düzine görsel içeren bir sayfa için bu limitler genellikle yeterlidir. Büyük bir projeden önce güncel Cloudflare koşullarını kontrol edin: sınırlar değişebilir. Bu arada, dosya başına 25 MB ilk videoya kadar cömert görünüyor.

3. Hesap

cloudflare.com üzerinde kayıt olmak sıradan bir işlem: e-posta ve parola, ardından onay e-postası. Ücretsiz tarife için kart gerekmiyor. Kendi alan adınızı eklemeniz de gerekmiyor - servis bunu önerecek, ama bu öneri ürünün diğer yarısıyla ilgili, yani mevcut sitelerin korunması ve hızlandırılmasıyla.

Giriş yaptıktan sonra ihtiyacınız olan bölüm "Workers & Pages" adını taşıyor ve pek göz önünde değil: sol menüde önce Build grubu, onun içinde Compute ve ancak onun da içinde - "Workers & Pages". Panel zamanla yeniden düzenleniyor, dolayısıyla bu yolda bölüm yoksa isme göre arayın: sol üstteki arama Ctrl + K ile açılır. İsimdeki iki kelime iki Cloudflare ürününü temsil ediyor; size gereken ilk yarısı, yani Workers; oraya özellikle bir şey seçmeden kendiliğinden varacaksınız.

İlk deployda karşınıza bir şey daha çıkacak: Cloudflare hesap için bir alt alan adı seçmenizi isteyecek. Bütün projeleriniz onun üzerinde yaşayacak; adres iki parçadan oluşur - proje adı artı sizin alt alan adınız:

my-landing.example-account.workers.dev
|          |               |
|          |               Cloudflare'in ortak alan adı
|          hesabınızın alt alan adı
proje adı

bu ismi sonradan değiştirmek zahmetli, dolayısıyla aklınıza ilk geleni yazmamak daha iyi.

4. İlk deploy

Önce kısaca panelde yayınlamanın nasıl göründüğüne bakalım. Bu, servisi tanımak için isteğe bağlı bir adım: hemen ajan üzerinden deploy kurup tek bir adres tutmak istiyorsanız, aşağıdaki hazırlığa geçin.

landing/          <- verdiğimiz klasör bu
  index.html      <- ana sayfa, adı zorunlu
  wrangler.jsonc  <- ajan ilk deploydan önce oluşturur
  style.css
  img/
    hero.png

Yayınlamadan önce seçtiğiniz klasörün içeriğini kontrol edin: içindeki dosyalar herkese açık hale gelecek. Göstermeyi düşünmediğiniz kişisel dosyaları ve taslakları çıkarın.

Panel üzerinden elle

Projeler bölümünde yeni bir proje başlatan bir düğme var. Ardından size dosyaları vermeniz istenir: tek bir dosya ya da bütün bir klasör seçebilirsiniz. Yükleyip onayladınız - Cloudflare bunları kendi tarafına yerleştirdi ve size bir bağlantı verdi. Düğme adları ve ekranların sırası burada yeni makaleler çıktığından daha sık değişiyor, dolayısıyla düğmelerin yazısına değil, adımların mantığına bakın: proje başlat, dosyaları ver, adres al.

Elde ettiğiniz adresi, https://…workers.dev, açın ve sayfa ile görselleri kontrol edin. Bunu aynı bilgisayardan yapabilirsiniz. Telefon, sayfanın dışarıdan açıldığını ve mobilde nasıl göründüğünü ek olarak kontrol etmek için işe yarar.

Panel üzerinden yayınlamadan sonra yerel bir yapılandırma dosyası oluşmaz. Örneğimizdeki skill, klasörü böyle bir projeyle kendiliğinden ilişkilendirmez: yapılandırma dosyası olmadan yeni bir isim ve ikinci bir adres oluşturur. Cloudflare, Wrangler üzerinden mevcut bir Worker'ı güncellemenize izin verir, ama bunun için yapılandırma dosyasını ayrıca o Worker'ın adına göre ayarlamanız gerekir.

Bunu ajanın yapması için ne gerekiyor

Bundan sonraki yayınlar için bir skill kuracağız. Hazırlık bilgisayarınızda bir kere yapılır.

Fazla programa ihtiyaç olmayacak. Hesabınız zaten var, bir de Node.js gerekiyor - node -v komutuyla kontrol edilir; komut bulunamazsa önce onu kurmanız gerekir. Wrangler'ın kendisini kurmaya gerek yok: npx sıra ona geldiğinde güncel sürümü kendisi indirir.

Şemadaki ikinci adım giriş; bunu her şeyden önce, hemen şimdi halletmekte fayda var:

npx wrangler login    # bir tarayıcı açılır, orada bir onay düğmesi vardır

Komutu terminalde çalıştırın. Bu adım eksikse, prosedürün tamamı ilk çalıştırmada buna takılır; bu da bozuk bir skill gibi görünür, oysa sorun hiç de skill'de değildir. Her şeyin yolunda olduğunu npx wrangler whoami komutuyla kontrol edebilirsiniz - bu komut kim olarak giriş yaptığınızı gösterir.

Bu rota için tarayıcı üzerinden giriş yeterlidir. API token'ı sonda, isteğe bağlı devam bölümünde ele alınıyor.

Şemadaki üçüncü adımı, npx wrangler deploy, ajan sayfanın klasöründen çalıştıracak. Önce ona yapılandırma dosyası hazırlama ve yayınlama kurallarını verelim.

5. Deploy için kendi skill'iniz

Sayfa tek olduğu sürece sohbete bir istek yeterli. Ama ikinci, üçüncü, onuncu bir sayfa gelince - her seferinde ajana aynı şeyi anlatmanız gerekir: hangi klasörü alıyoruz, projeye ne ad veriyoruz, ayar dosyasıyla ne yapıyoruz. Üçüncü seferde bu can sıkıcı olur.

Skill'in ne yapabilmesi gerekiyor

Beş adım var ve her biri eksiksiz görünsün diye değil, somut bir sorunu çözmek için eklendi:

1. Adı verilen klasörü alıp index.html'in onun kökünde durduğundan emin olmak. Deploydan önce, sonra değil, en sık yapılan hatayı yakalayan ucuz bir kontrol.
2. Proje adını belirlemek - her seferinde sormak yerine klasörün adından çıkarmak.
3. Klasörün içinde, index.html'in yanında, wrangler.jsonc dosyası olup olmadığına bakmak. Yoksa - oluşturmak; varsa - adı oradan almak ve içinde hiçbir şeyi yeniden yazmamak.
4. Deployu bu klasörden başlatmak ve komutu çalıştırmadan önce göstermek.
5. Herkese açık adresi döndürmek ve sayfayı ve görselleri o adresten kontrol etmeyi hatırlatmak.

Proje adı klasörden çıkarılır

Bu, tüm sürecin en önemli kararı; ajanın doğaçlamasına bırakılmaması gereken de tam olarak o. İsim bir kuralla belirlenmezse, ajan onu kendisi uydurur - ve bir dahaki sefere başka bir şey uydurur. Sonuçta farklı bir adreste ikinci bir proje ortaya çıkar, ilki de ortada asılı kalır.

Kural basit: klasörün adı, projenin adıdır. Worker adında yalnızca küçük Latin harfleri, rakamlar ve tire bulunabilir, dolayısıyla geri kalan her şeyi - noktalar, boşluklar, alt çizgiler - tireye çeviriyoruz ve sonuna kısa bir sonek, dört rastgele karakter ekliyoruz:

landing/                 ->  landing-42c2
my.first.page/           ->  my-first-page-8e10
portfolio-2026/          ->  portfolio-2026-b7a3

Sonek, farklı projelerdeki aynı isimli iki klasörün aynı adresi paylaşmaması için var. Ayar dosyası oluşturulduğunda bir kere üretilir, hem de mutlaka bir komutla, ajanın kafasından değil: yoksa ajan örnekteki soneki alır ve aynı makaleyi okuyan herkeste sonek aynı çıkar. Bundan sonra sonek her zaman yapılandırma dosyasından okunur. Skill'in önce mevcut yapılandırma dosyasına bakıp ancak sonra bir şey yazmasının nedeni tam olarak bu.

Ayar dosyasını ajan yazar

Ajan, terminalde soru sorulmadan deploy çalıştırabilmek için wrangler.jsonc'e proje adını ve yayınlama ayarlarını yazar. Yapılandırma dosyası index.html'in yanında durur, dolayısıyla içindeki dosya yolu bir nokta, yani "aynı klasör":

{
  "name": "landing-42c2",
  "compatibility_date": "2026-09-07",
  "assets": { "directory": "." }
}

compatibility_date alanı, platformun belirtilen tarihte geçerli olan davranışını seçer. Yeni bir yapılandırma dosyası için ajan, Cloudflare belgelerinin önerdiği gibi bugünün tarihini koyar; tekrar yayınlarken eskisini korur.

Yapılandırma dosyasını bir üst seviyeye, klasörün yanına koymak iyi bir fikir değil: dosya adı sabit, bir dizinde böyle bir dosyadan yalnızca bir tane olabilir; ikinci klasör ya ilkinin yapılandırma dosyasını ezer ya da onun adı altında yayınlanır. Klasörün içinde her proje kendi kendine yeterlidir ve deploy doğrudan oradan çalıştırılır.

Bu düzenlemenin bir yan etkisi: yapılandırma dosyası sayfayla aynı klasörde durduğundan, onunla birlikte hostinge gider ve bağlantıdan açılabilir hale gelir. İçinde gizli bir bilgi yok - isim, tarih ve bir nokta; bundan rahatsız olan, yanına bir .assetsignore dosyası koyup neyin yayınlanmayacağını orada listeler.

Görevde açıkça belirtmeye değer üç kural var, yoksa ajan bunları tahmin edemez:

• dosya yoksa - oluştur, ne yazdığını göstererek;
• dosya varsa - ismi ve tarihi olduğu gibi bırak, bugünün tarihi farklı olsa bile;
• dosyayı yalnızca içerik gerçekten değiştiğinde yeniden yaz.

Elinizin altında tutmaya değer dört istek

Birincisi - skill'in kendisi için görev. Diğerlerinden daha uzun, çünkü prosedürü baştan sona anlattığınız tek an bu:

Cloudflare Workers'a statik sayfalar deploy etmek için bir skill oluştur.
Bunu bu projenin .claude/skills/ klasörüne koy.
Sonunda oluşturulan SKILL.md'nin yolunu ve skill'i açıkça çağırma yöntemini göster.

Önce Cloudflare'in Workers ve static assets hakkındaki güncel
belgelerini oku: komutlar ve yapılandırma alanları değişmiş olabilir.
Aşağıdaki açıklamada belgelerle çelişen bir şey varsa - bana söyle,
sessizce yeniden yazma.

Skill açıklamasında hangi ifadelerle tetiklenmesi gerektiğini listele,
en azından şunlar olsun: "klasörü yayınla", "yeniden yayınla", "Cloudflare'e deploy et".

Prosedür: bir klasör alıyorum, kökte index.html olduğunu kontrol ediyorum.
Proje adını bu klasörün adından çıkarıyorum: içinde yalnızca
küçük Latin harfleri, rakamlar ve tire kalıyor, geri kalan her şeyi
(boşluklar, alt çizgiler, büyük harfler, Latin olmayan harfler) tireye çeviriyorum.
Sonuna tireyle dört karakterlik bir sonek ekliyorum.
Soneki uydurmuyorum, bir komutla alıyorum:
node -e "console.log(crypto.randomUUID().slice(0,4))"
wrangler.jsonc yapılandırma dosyası, yayınlanan klasörün içinde, index.html'in
yanında duruyor; içindeki assets.directory "." değerine eşit.
Yapılandırma dosyası yoksa - onu oluşturuyorum: name, compatibility_date,
assets.directory. Yeni bir compatibility_date için YYYY-MM-DD
formatında bugünün tarihini alıyorum. Ne yazdığımı gösteriyorum.
Yapılandırma dosyası varsa - ismi ve tarihi oradan alıyorum ve yeniden yazmıyorum.
Dosyayı yalnızca içerik gerçekten değiştiğinde yeniden yazıyorum.
Yapılandırma dosyası var ama assets.directory bu klasörü göstermiyorsa
veya yapılandırma dosyasında main alanı varsa - duruyorum ve söylüyorum, deploy çalıştırmıyorum.
Yeniden yayınlama istenirse ve klasörde yapılandırma dosyası yoksa - duruyorum
ve soruyorum, yeni bir proje oluşturmuyorum.
Deploy: proje klasöründen npx wrangler deploy. Komutu çalıştırmadan önce gösteriyorum.
Cevapta herkese açık adresi döndürüyorum ve o adresten sayfayı ve görselleri
kontrol etmeyi hatırlatıyorum. Güncellemede adres aynı kalmalı.
Node.js yoksa veya oturum açılmamışsa - bunu söylüyorum,
etrafından dolanmaya çalışmıyorum.
Hesabın henüz bir workers.dev subdomaini yoksa - bunu söylüyorum:
etkileşimsiz deploy bu noktada başarısız olur.

Oluşturulduktan sonra ajanın gösterdiği .claude/skills/<isim>/SKILL.md dosyasını açın: yukarıdaki kurallar içinde olmalı. İkinci istekten önce, ajanın gösterdiği yöntemle oluşturulan skill'i açıkça çağırın. Skill bulunamıyorsa, ajandan yolu ve skill'in mevcut projede erişilebilir olup olmadığını kontrol etmesini isteyin.

İkincisi - işe başlamadan önceki kontrol. Bir klasörün ilk deployundan önce, bir şey dışarı çıkmadan planı görmek istediğinizde işe yarar; birkaç klasör varsa, her biri için ayrı ayrı gönderilir:

Dosya oluşturma ve değiştirme, wrangler çalıştırma. Sadece landing
klasörüyle ne yapacağını göster: hangi proje adı, hangi yapılandırma dosyasını
yazacaksın, hangi komutu çalıştıracaksın.

Bir çekince var: sonek, yapılandırma dosyası yazıldığı anda ortaya çıkıyor, dolayısıyla henüz yapılandırma dosyası olmayan bir klasörde plandaki isim ile gerçek çalıştırmadaki isim eşleşmeyebilir. Geri kalan her şey eşleşecektir.

Üçüncüsü ve dördüncüsü - günlük işin istekleri, bütün bu hazırlık da zaten onlar için:

landing klasörünü Cloudflare Workers'a yayınla.

landing içindeki index.html'i düzelttim. Cloudflare Workers'a yeniden yayınla.

İlk yayından sonra aldığınız bağlantıyı açın, metni ve görselleri kontrol edin. Ardından landing/index.html içinde göze çarpan bir ifadeyi değiştirin ve dördüncü isteği gönderin. Sayfayı aynı adresten yenileyin: yeni ifade görünmeli. Adres değiştiyse, bir sonraki deploydan önce ajandan yapılandırma dosyasındaki ismi kontrol etmesini isteyin.

Bununla ana rota tamamlandı: skill oluşturuldu, sayfa yayınlandı, güncelleme aynı bağlantıdan kontrol edildi. Her yayından önce geriye kalan tek şey doğru klasörü seçmek ve ajanın komutuna bakmak.

6. Ek senaryolar

Aynı anda birçok klasör hazırlama ya da tarayıcı üzerinden giriş yapmadan deploy çalıştırma ihtiyacınız olana kadar bundan sonrasını okumayabilirsiniz.

Prosedürün yetmediği zaman

Talimat biçimindeki skill, klasörler birkaç tane ya da birkaç düzine olduğu sürece iyi çalışır. Daha fazlasında ajanın prosedürü her seferinde yeniden okuyup elle uygulaması engel olmaya başlar: elli kadar klasörde bu uzun sürer ve sonuç her seferinde aynı olmaz.

O zaman prosedür bir script'e dönüştürülür: script klasörleri kendisi dolaşır, yapılandırma dosyalarını yazar, hiçbir şey değişmeyenleri atlar ve bir özet basar. Skill bu sırada bir yere gitmez - sadece yapılandırma dosyalarını kendisi yazmak yerine script'i çağırır, deployu ise yine kendisi çalıştırır.

Onu yazmak da size düşmez. Ajanın elinde zaten prosedürün ayrıntılı bir açıklaması var - sizin skill'iniz - dolayısıyla istek kısa çıkar:

Python'da, benim deploy skill'imde anlatılanın aynısını yapan
bir script yaz, sadece projedeki tüm klasörler için birden.

Kökte index.html olan klasörleri alır;
node_modules, .git ve dist içine bakmaz.
Her biri için bizim kuralımıza göre bir isim oluşturur ve wrangler.jsonc'i
klasörün içine yazar.
Yapılandırma dosyası zaten varsa - ismi ve compatibility_date'i oradan alır,
dosyayı yalnızca içerik gerçekten değiştiğinde yeniden yazar.
Yapılandırma dosyası okunamıyorsa - ona dokunmaz, bunu söyler
ve klasörü atlar.
Varsayılan olarak yalnızca planı gösterir ve hiçbir şey yazmaz;
yazma işlemi açık bir bayrakla olur.
Yalnızca seçilen klasörlerden geçmek için bir filtre olsun.
Script yalnızca yapılandırma dosyalarını hazırlar, deploy çalıştırmaz.
Sonunda bir tablo basar: klasör, proje adı, ne yapıldığı.
Bu açıklamada belirsiz bir şey varsa - sor, sessizce kendi kafana göre tamamlama.

Planın gösterilmesi, yazmadan önce klasör listesini kontrol etmenizi sağlar. İsmin ve tarihin korunması, mevcut yapılandırma dosyalarını kazara değişikliklerden korur. Script'in kendisi yalnızca ayarları hazırlar; yayınlamayı hâlâ skill yapar.

Erişim token'ı

Kendi bilgisayarınızda zaten npx wrangler login ile giriş yaptınız. Wrangler bu yetkilendirmeyi saklar; ajanın çalıştırdığı komutlar da onu kullanır.

Tarayıcı üzerinden giriş yapmadan otomatik bir çalıştırma veya daha dar yetkiler gerekiyorsa API token'ı kullanılır. Onu profilde oluşturabilirsiniz: avatar, profil, API token'ları bölümü. Doğrudan adres - dash.cloudflare.com/profile/api-tokens.

Oluşturma formu korkutucu görünüyor: yetki grupları, kaynaklar, bir de birtakım filtreler. Aslında orada verilecek dört karar var ve alanların yarısına hiç dokunmayabilirsiniz.

1. Token adı. Altı ay sonra ne için olduğunu hatırlamayacaksınız, dolayısıyla işe yarar bir ad yazın: "token 2" değil, "dizüstünden sayfa deployu".
2. Yetkiler. Bunları teker teker toplamaya gerek yok, üstelik bu iyi bir fikir de değil. Hazır şablonlar listesinde Edit Cloudflare Workers var - yayınlama için gereken her şey zaten onun içinde toplanmış.
3. Kaynaklar. Token'ı yalnızca yayınladığınız o hesapla sınırlayın. Tek bir hesabınız olsa bile, onu açıkça seçin: hesap sayısı artabilir, token ise aynı kalır.
4. Ömür ve IP filtresi. İsteğe bağlı alanlar. Token bir akşamlığına veya başkasının makinesi için gerekiyorsa ömür koymak mantıklı; olağan işte bu alanlar olduğu gibi bırakılır.

Sonra token, CLOUDFLARE_API_TOKEN ortam değişkenine konur, hesap ise CLOUDFLARE_ACCOUNT_ID'de belirtilir. Ortam değişkeni, programların kendiliğinden okuduğu bir makine ayarıdır; wrangler ikisini de siz bir şey yapmadan bulur. Değişkenlerin nasıl çalıştığı ve nerede tutulması gerektiği ayrı bir konu; burada şunu bilmek yeterli: bu bir saklama yeri, yazışmadaki bir satır değil.