Dağıtım

text build taşınabilir bir dist/ üretir. Bir adaptör bunu platformun beklediği çıktıya dönüştürür.

#Adaptörler

text build --adapter <name>

Adaptör, TEXTJS_ADAPTER ile de belirlenebilir. text build Vercel’de (VERCEL=1) veya Cloudflare Pages’te (CF_PAGES=1) çalıştığında ilgili adaptör otomatik olarak seçilir.

Sunucu adaptörleri (bun, vercel ve cloudflare), text start ile aynı işlem hattını çalıştırır: middleware, rewrites, rota önbelleğini kullanan rota işleyicileri, statik varlıklar ve ardından sayfa URL’leri için konsol belgesi. curl gibi terminal istemcileri bunun yerine sayfanın ilk karesini ANSI metni olarak alır. vercel ve cloudflare adaptörlerinde bu yalnızca statik sayfaları kapsar (bkz. curl ve terminal istemcileri). Sunucu adaptörleri, /assets/ altındaki hash içeren dosyaları Cache-Control: public, max-age=31536000, immutable ile sunar.

#Statik

text build --adapter static

GitHub Pages, S3 veya CDN gibi sunucusuz barındırma hizmetleri için kullanın. dynamic = "force-static" veya revalidate içeren GET rota işleyicileri ön render ile dosyalara dönüştürülür: app/api/feed.json/route.ts, dist/api/feed.json olur. Derin bağlantıların konsol uygulamasını açması için index.html dosyasının bir kopyası 404.html dosyasına yazılır. Statik barındırma hizmetleri curl ile tarayıcıyı ayırt edemediğinden curl HTML sayfasını alır.

Uygulama şu nedenlerle sunucu gerektiriyorsa derleme tüm nedenleri listeleyerek başarısız olur: middleware.ts, sunucuda render edilen rotalar, dinamik rota işleyicileri, dinamik segment içeren rota işleyicileri veya GET dışındaki yöntemler. Bunun yerine barındırma hizmetinde rewrites yapılandırın.

#Bun

text build --adapter bunPORT=8080 bun dist/server.js

bun adaptörü, çalışma zamanında node_modules gerektirmeyen, kendi kendine yeterli tek bir sunucu yazar. PORT (varsayılan 3000) ve HOSTNAME (varsayılan 0.0.0.0) değerlerini okur; server.js veya .text/ içeriğini hiçbir zaman sunmaz. Uzun ömürlü bir süreç olduğundan, text start gibi sunucuda render edilen rotaları (export const runtime = "server") ve bunların canlı oturumlarını da barındırır. Bir konteynerde kullanın:

FROM oven/bun:1COPY dist /appCMD ["bun", "/app/server.js"]

#Vercel

text build --adapter vercelvercel deploy --prebuilt

Veya Vercel’e bağlı bir Git deposuna gönderin: derleme text build komutunu çalıştırır, Vercel’i algılar ve .vercel/output yazar.

Edge middleware, x-middleware-next / x-middleware-rewrite protokolünü kullandığından üstbilgi geçersiz kılmaları ve yeniden yazmalar, fonksiyona veya CDN’e ulaşılmadan önce Vercel’in yönlendiricisinde gerçekleşir. Tüm eşleştiriciler tek bir rota src desenini paylaşır. Hiçbir eşleştiricinin kapsamadığı istekler, yollarının kanonik biçimde olmama ihtimali yoksa middleware’i atlar (yüzde kaçışları, URL ayrıştırıcısının kodladığı karakterler, //, . veya .. segmentleri, sonda eğik çizgi). Middleware ardından kanonik yolu eşleştirir, has / missing koşullarını denetler ve Vercel’in aynı şekilde yönlendirmesi için isteği bu yola yeniden yazar. middleware.ts içermeyen uygulamalar da aynı edge fonksiyonunu alır; bu fonksiyon yalnızca yeniden yazma yapar. Her derleme bir Edge fonksiyonu içerdiğinden oturum açılmış bir Vercel hesabından dağıtın: anonim dağıtımlar (vercel deploy --temporary) Edge fonksiyonlarını kabul etmez.

İşleyici fonksiyonu dahilidir. Her işleyici rotası, eşleşen yolu bu fonksiyona x-textjs-path istek üstbilgisinde iletir. Bu üstbilgi middleware’den önce ve sonra her istekten kaldırılır ve edge middleware, istemciden veya middleware.ts dosyasından gelen böyle bir üstbilgiyi hiçbir zaman iletmez; dolayısıyla bunu yalnızca işleyici rotaları ayarlayabilir. /_textjs/* istekleri, middleware ve yeniden yazmalardan önce ve sonra fonksiyonu çalıştırmadan 404 döndürür. Üretilen rotalar, diğer tüm barındırma hizmetlerindeki eşleştiriciler ve yeniden yazmalar gibi büyük/küçük harfe duyarlı eşleşir.

Adaptörün testleri bu çıktıyı Vercel yönlendiricisinin yerel bir emülasyonunda çalıştırır. src eşleştirme, dest yakalamaları, üstbilgi dönüşümleri ve status rotalarına ilişkin davranışı gerçek dağıtımlarla karşılaştırılarak denetlenmiştir; anonim olarak dağıtılamadığı için Edge middleware denetlenmemiştir.

#Cloudflare Pages

text build --adapter cloudflarebunx wrangler pages dev dist --compatibility-flags=nodejs_compatbunx wrangler pages deploy dist

Çıktı, Pages gelişmiş modunu kullanır:

Pages dizini olduğu gibi yayımladığından .text/ (sunucu paketleri ve derleme manifestleri), dist/ dizininden kaldırılır.

Pages projesinde (Settings → Runtime) veya wrangler.toml dosyasında nodejs_compat uyumluluk bayrağını etkinleştirin; veri önbelleği AsyncLocalStorage kullanır. Statik dosyalar ASSETS bağlaması üzerinden sunulur ve arka planda yeniden doğrulama ctx.waitUntil() kullanır.

Middleware kullanıldığında, hash içeren varlıklar dahil her istek worker’ı çalıştırır; böylece middleware bir dosyaya erişilebilen her yolu görür. Worker’ı çalıştıran her istek bir Functions çağrısıdır ve Workers istek kotanıza dahil edilir. Bir sayfa yüklemesinde bu, belge ve getirdiği her dosya demektir (tek JavaScript paketi olan küçük bir test uygulaması için 2; daha fazla dosyası olan uygulamalar için daha fazla). Workers Free planında günlük kota tükendiğinde Pages statik dosyaları worker olmadan sunar ve middleware atlanır. Middleware dist/ içindeki herhangi bir şeyi koruyorsa Settings → Runtime → Fail open / closed ayarını Fail closed olarak ayarlayın.

name = "my-console"pages_build_output_dir = "dist"compatibility_date = "2025-01-01"compatibility_flags = ["nodejs_compat"]

#Yükseltme

@textjs/app paketindeki güvenlik düzeltmeleri, bir dağıtıma ancak yeniden derleyip dağıttıktan sonra ulaşır:

• Vercel: yeni .vercel/output çıktısını dağıtın.
• Cloudflare Pages: yeni dist/ dizinini _worker.js ve _routes.json ile birlikte dağıtın.
• Bun: yeni dist/ dizininin tamamını (server.js, varlıklar ve canlı paketler) dağıtın ve sunucuyu yeniden başlatın.
• text start: text build komutunu çalıştırın ve yeniden başlatın.

Eski dağıtımlar kendi URL’lerinde erişilebilir kalır (örneğin Vercel ve Cloudflare Pages önizleme URL’leri). Bunları silin veya platformun erişim koruması arkasına alın.

#Sunucuda render edilen rotalar

Sunucuda render edilen rotalar, açık sekme başına bir oturum tuttuğundan uzun ömürlü bir sunucu gerektirir: text start veya bun adaptörü. Bir sayfa runtime = "server" dışa aktardığında static, vercel ve cloudflare adaptörleri derlemeyi TX030 ile başarısız kılar.

#Proxy arkasında çalıştırma

text start, 127.0.0.1 adresine bağlanır ve geri döngü arayüzüne bağlıyken yalnızca localhost, *.localhost ve IP adresli ana makinelere yanıt verir (DNS yeniden bağlama koruması). Diğer ana makineler TX028 ile 403 alır. Genel erişim ayarlarını text.config.ts dosyasına koyun:

import { defineConfig } from "@textjs/app";export default defineConfig({  server: {    origin: "https://console.example.com", // request.url always uses it (or TEXTJS_ORIGIN)    trustProxy: true, // read X-Forwarded-Host / -Proto from your proxy (or TRUST_PROXY=1)    allowedHosts: [".example.com"],  },});

origin veya trustProxy olmadan request.url, doğrulanmış Host üstbilgisinden http üzerinden oluşturulur.

#Dikkat edilecek noktalar

• text.config.ts dosyasındaki proxy yalnızca text dev ve text start ile çalışır; adaptörler bunu içermez. Her sunucu adaptörünün desteklediği rewrites kullanın.
• Her sunucusuz örneğin kendi bellek içi önbelleği vardır. Bkz. Önbellekleme.
• Ham düzenli ifade grupları kullanan rewrites, mümkün olduğu ölçüde Vercel rotalarına dönüştürülür; adlandırılmış parametreler (:slug, :path*) tam olarak dönüştürülür.