Site şablonu
Journey AI içeriğini yayınlayan Next.js site şablonunun yapısı, ayarları ve bir isteğin sayfaya dönüşme yolu.
Bu sayfada site şablonunun ne olduğunu, proje yapısını, gereken ortam değişkenlerini ve bir isteğin nasıl sayfaya dönüştüğünü öğreneceksin.
Journey AI başsız (headless) bir CMS'tir. İçerik panelde düzenlenir, API üzerinden JSON olarak sunulur. Ziyaretçinin gördüğü siteyi ise site şablonu çizer. Şablon Cms-Landing-Core deposunda duran bir Next.js projesidir. Her yeni site bu şablondan kopyalanır ve yapılandırılır.
Teknik yığın
| Alan | Kullanılan |
|---|---|
| Çatı | Next.js 16 (App Router), React 19, TypeScript |
| Stil | Tailwind CSS v4, shadcn/ui, lucide-react |
| Form | react-hook-form, zod |
| İçerik | react-markdown, remark-gfm |
| Paket yöneticisi | Yalnızca pnpm |
| Çıktı | output: "standalone", Docker ve Node 22 |
Hızlı başlangıç
git clone <Cms-Landing-Core> my-site && cd my-site
cp .env.example .env.local # NEXT_PUBLIC_API_URL ve NEXT_PUBLIC_SITE_URL'i doldur
pnpm install
pnpm dev # http://localhost:3000
pnpm exec tsc --noEmit && pnpm lintYeni bir site projesi, depodaki scripts/create-landing-project.sh betiğiyle oluşturulur. Node 22 veya üstü gerekir; paket yöneticisi olarak yalnızca pnpm kullan.
README güncel değil
Deponun README dosyası artık bulunmayan klasörlere (templates/next-core/, examples/proxy.ts) atıf yapar. Kurulumda bu sayfayı ve deponun .env.example dosyasını esas al.
Proje yapısı
Proje başına yapılandırma
| Dosya | Ne ayarlanır |
|---|---|
src/lib/template-config.ts | Ana sayfa slug'ı (HOME_SLUG), varsayılan dil (DEFAULT_LANGUAGE), HTML_LANG, OG_LOCALE, header ve footer slug'ları, sitemap dışı yollar, form metinleri |
src/lib/middleware/languages.ts | Sitede açık olan diller (TEMPLATE_LANGUAGES) |
src/lib/middleware/config.ts | Dil öneki davranışı, proxy ayarları |
src/app/globals.css | Tailwind v4 @theme ve shadcn renk değişkenleri |
next.config.ts | Uzak görsel kaynakları, paneli iframe'de açacak alan adları |
Ortam değişkenleri
Değerleri .env.example dosyasındaki açıklamalara göre doldur. Gizli değerleri depoya koyma.
| Değişken | Görevi |
|---|---|
NEXT_PUBLIC_API_URL | Zorunlu. CMS API kökü, örneğin https://api.example.com. |
PRIVATE_API_ADDRESS | İsteğe bağlı. Sunucu tarafının kullanacağı iç CMS adresi. |
NEXT_PUBLIC_SITE_URL | Canonical, Open Graph ve paylaşım URL'lerinin kökü. |
NEXT_PUBLIC_SITE_NAME | Başlık şablonundaki site adı. |
PREVIEW_MODE | Yalnızca sunucuda okunur. true ise site önizleme sitesi olarak çalışır. |
NEXT_PUBLIC_INSPECTOR_ENABLED | Panel denetleyicisi. Yalnızca önizleme dağıtımında açılır. |
SITE_PROXY_SECRET | Form gönderiminde ziyaretçi bilgisini CMS'e iletmek için ortak anahtar. |
REVALIDATE_ALLOWED_ORIGINS | Yenileme ucunu çağırabilecek kökenler. |
REVALIDATE_NODES | Birden çok sunucu örneği varsa yenilemenin iletileceği diğer örnekler. |
NEXT_PUBLIC_BUILD_IMG_SERVER_ADDRESS, NEXT_PUBLIC_RUNTIME_IMG_SERVER_ADDRESS | Görsel CDN'i için preconnect. |
NEXT_PUBLIC_API_URL ayarlı değilse geliştirmede bir kurulum ekranı görürsün. Üretimde sayfalar 404 döner.
Tek içerik rotası
Sitede elle yazılmış sayfa yoktur. Tüm içerik tek bir catch-all rotadan geçer: src/app/[[...slug]]/page.tsx. /kurumsal/ekip adresi kurumsal/ekip slug'ına, / adresi HOME_SLUG'a çevrilir.
Bir istek nasıl sayfaya dönüşür
Proxy çalışır
src/proxy.ts statik dosyaları atlar, bozuk URL artıklarını temizler, CMS'ten gelen yönlendirme haritasını uygular, büyük harfli yolları küçük harfe 301 ile yönlendirir ve dil önekini çözer.
Sayfa CMS'ten çekilir
Rota GET /api/v1/page/detail/{dil}?path={slug} çağrısını yapar. Çağrı react.cache ile sarılıdır. Böylece metadata ve sayfa gövdesi tek isteği paylaşır.
Bileşen ağacı çizilir
components[] dizisindeki her üst düzey eleman DynamicComponent üzerinden bir React bileşenine çevrilir. Ayrıntı için Bileşenler sayfasına bak.
Metadata üretilir
buildMetadata SEO alanlarından başlık, açıklama, canonical, Open Graph, Twitter ve robots etiketlerini üretir. PageSchemas JSON-LD bloklarını basar.
Kabuk eklenir
Header, footer ve navigasyon kök layout'ta sunucuda çekilen şablondan gelir. İlk HTML'de bulunurlar.
Sonuç önbelleğe yazılır
Sayfa 300 saniyelik ISR ile önbellekte durur. Ayrıntı için Önbellek ve önizleme sayfasına bak.
Kod kuralları
- Varsayılan olarak sunucu bileşeni yaz.
"use client"yalnızca durum veya tarayıcı API'si gerektiğinde. - Tailwind ölçeğinin dışına çıkma:
text-[17px]değiltext-lg. - Ham renk yerine anlamsal token kullan:
bg-background,text-muted-foreground. - İkonlar yalnızca
lucide-react. GSAP modül seviyesinde değil,src/lib/gsap.tsüzerinden tembel yüklenir.
Sonraki adımlar
İlgili sayfalar
Bileşenler
CMS bileşen tiplerinin React bileşenlerine nasıl eşlendiği ve siteye yeni bir blok eklemenin adımları.
Önbellek ve önizleme
Site şablonunun ISR ve önbellek katmanları, panelin tetiklediği yenileme, önizleme sitesi, yönlendirmeler, dil önekleri ve sitemap.
Geliştirici dokümantasyonu
Journey AI ile site geliştirme ve teknik entegrasyon rehberleri.