Başlarken16 dk okuma

Kurulum

Go'yu ve collage CLI'ını kurun, collage new ile bir proje scaffold edin ve onu collage dev ile çalıştırın.

Bir collage projesi sıradan bir Go modülüdür. collage komut satırı aracı bu projeyi scaffold eder, siz üzerinde çalışırken çalıştırır ve yayına alırken build eder. Framework'ün kendisi ise projenin import ettiği bir kütüphanedir. İkisi de Go dışında hiçbir şeye ihtiyaç duymaz.

Sıfırdan çalışan bir projeye böyle gelinir. go install, collage CLI'ını PATH'inize koyar. collage new mysite varsayılan olarak minimal projeyi yazar: tek bir page'i saran bir layout ve bir stylesheet. --template demo ile demoları ve testlerini yazar. İkisi de bir .env.example ile gelir. go mod tidy, go.mod'a collage'ı ekler ve go.sum'ı yazar. Ardından collage dev localhost:6060'ta serve eder ve her request'i, kendine ait loopback bir adreste çalışan programa iletir. Kaydedilen bir Go dosyası yeniden build edilip yeniden başlatılır, kaydedilen bir template ya da static dosya page'i yeniler.go install …/collage@latestcollage new mysiteminimal--template demovarsayılan: layout,page, stylesheetdemolar ve testleri,bir not-found pagego mod tidygo.mod'da collage, go.sumcollage devlocalhost:6060Go dosyası kaydedildi: rebuild, restarttemplate ya da static dosya: yenilemeprogram: kendine ait loopback adres
Sıfırdan çalışan bir projeye böyle gelinir. go install CLI'ı PATH'inize koyar. collage new, siz --template demo istemedikçe minimal projeyi yazar. Demo template'i buna demoları ve testlerini ekler; ikisi de bir .env.example ile gelir. go mod tidy framework'ü çeker ve sürümünü go.mod ile go.sum'a kaydeder; --with bunu sizin yerinize yapar. collage dev varsayılan olarak 6060 portunda dinler ve her request'i, kendine ait loopback bir adreste çalıştırdığı programınıza iletir. Kaydedilen bir Go dosyası yeniden build edilip yeniden başlatılır, kaydedilen bir template ya da static dosya ise yalnızca page'i yeniler.

Go'yu kurun

collage Go 1.26.11 veya daha yeni bir sürüm ister, 1.27 serisinde ise 1.27.4 veya daha yenisini: daha eski patch'lerde, collage'ın body sınırının üzerine kurulu olduğu http.MaxBytesReader'da bir HTTP/1 sunucusunu çökertebilen bir race vardır (GO-2026-6859). Varsayılan GOTOOLCHAIN=auto ile daha eski bir Go, 1.26.11'i kendisi indirir. Go'yu go.dev/dl adresinden ya da paket yöneticinizden kurun ve kontrol edin:

go version

CLI'ı kurun

go install github.com/Elagoht/collage/cmd/collage@latest

go install binary'yi $(go env GOBIN) dizinine koyar. GOBIN ayarlı değilse $(go env GOPATH)/bin dizinini kullanır. Bu dizin PATH'inizde olmalıdır. Olup olmadığını kontrol edin:

collage version

Yazdırılan sürüm build'in kendisinden okunur, yani go install hangi sürümü çektiyse o görünür. collage help bütün komutları listeler, collage help new ise tek bir komutu açıklar.

Shell completion ve man sayfası

CLI, TAB'a basıldığında komutlarını, flag'lerini ve onların değerlerini tamamlar. Script'i shell'inizin başlangıç dosyasından yükleyin:

eval "$(collage completion bash)"      # ~/.bashrc
source <(collage completion zsh)       # ~/.zshrc, after compinit
collage completion fish | source       # ~/.config/fish/config.fish

collage man --install, collage(1)'i man'in baktığı yere koyar; böylece man collage çalışır. İkisinin ayrıntıları da CLI referansında.

Proje oluşturun

collage new mysite

Bu komut ./mysite içine, module path'i mysite olan, çalışmaya hazır bir proje yazar ve sonraki adımları ekrana basar:

Scaffolded "mysite" in mysite

Next steps:
  cd mysite
  go mod tidy
  collage dev

Demo projesinin (aşağıda) adımlarında collage dev'den önce cp .env.example .env satırı da yer alır.

Ad hem projenin adı hem de varsayılan module path'tir, bu yüzden geçerli bir module path olmalıdır: go mod init'in kabul ettiği gibi, eğik çizgiyle ayrılmış parçalarda harfler, rakamlar ve - . _ ~. Böyle olmayan bir ad, ya da module path olmayan bir --module, hiçbir şey yazılmadan 2 çıkış koduyla reddedilir; geçerli bir ad verin ya da module path için --module kullanın. Ad yerine bir path verirseniz proje oraya scaffold edilir ve o dizinin adını alır: proje için açtığınız bir dizinde collage new . projeyi o dizine scaffold eder ve sonraki adımlarda cd yer almaz.

go mod tidy framework'ü çeker. Scaffold edilen go.mod yalnızca modülün adını ve Go sürümünü, go 1.26.11'i içerir. Bu yüzden projenin hangi collage sürümüyle build edildiğini kaydeden şey ilk tidy çalıştırmasıdır.

Birkaç flag, projenin nereye ve nasıl yazılacağını değiştirir. Flag'leri tek ya da çift tireyle yazabilirsiniz. Proje adından önce de gelebilirler, sonra da:

FlagEtkisi
--template demoDemoları ve testlerini oluşturur. Varsayılan --template minimal'dir: tek bir page'i saran bir layout ve bir stylesheet
-dir pathProjeyi ./<name> yerine path içine scaffold eder; bu durumda ad bir path değil, bir ad olmalıdır
-module pathgo.mod'daki module path'i belirler, örneğin github.com/you/mysite. Varsayılan değer proje adıdır; module path olmayan bir değer 2 çıkış koduyla reddedilir
-forceBoş olmayan bir dizine de scaffold eder
--aiBir coding agent'ın collage projesinde ihtiyaç duyduğu kuralları içeren AGENTS.md'yi ve onu import eden bir CLAUDE.md yazar. collage ai init aynısını sonradan yapar; bkz. CLI
--with pluginsProje yazıldıktan sonra plugin ekler: @prod gibi bundle'lar ve elagoht/session gibi plugin'ler, virgülle ayrılmış. Plugin'ler çekildiği için go mod tidy bir sonraki adım olmaktan çıkar
collage new mysite -module github.com/you/mysite
collage new mysite --template demo
collage new mysite -dir . -force
collage new .
collage new mysite --with @site,@prod

Demolarla ya da demolar olmadan

--template demo, bir ana sayfa ve canlı demolarla dolu bir /features page'i oluşturur. Bu demolar şunlardır:

  • bir API action'ına post edip cache'lenmiş bir page'i tag ile invalidate eden bir buton;
  • kendi page'ine post edilen bir HTML form;
  • kendi URL'sinde açılabilen bir saat fragment'i;
  • /healthz adresindeki bir JSON document.

Bunların her birini çalışırken görmenin en hızlı yolu budur. Her birinin arkasındaki kod da tek oturuşta okunacak kadar kısadır.

Varsayılan template olan minimal aynı main.go'yu ve aynı dizin yapısını oluşturur. İçinde yalnızca "hello" diyen tek bir page'i saran bir layout ve dark mode'u olan bir stylesheet bulunur. Silmeniz gereken hiçbir şey yoktur. Gerçek bir siteye başlarken bunu kullanın. İlk page'iniz rehberi de minimal bir projeden başlar.

Scaffold'un içinde neler var

Minimal bir proje şöyle görünür:

mysite/
├── main.go                     newApp, the configuration; main hands it to collage.Main
├── embed.go                    files: templates/, static/ and plugins-config.json, embedded
├── embed_dev.go                files as the project directory, for collage dev's builds
├── routes.go                   every page, document and action — a new route goes here
├── plugins.go                  the plugin list; collage plugin add and del edit it
├── plugins-config.json         plugin settings, keyed by plugin name
├── .env.example                the environment variables, to copy to .env
├── go.mod
├── .gitignore
├── README.md
├── pages/
│   └── home.go                 the home page: its layout, content and path
├── fragments/
│   ├── layouts/master.go       Master(), the layout every page shares, and the site's title
│   └── pages/home.go           the home page's content, its data and its markup:
│                               <h1>Hello from {{.Name}}</h1>
├── templates/
│   └── layouts/master.html     the layout's HTML, with {{slot "content"}}
└── static/
    └── app.css                 the background and text colour, light and dark

Kod, alanlara (area) göre düzenlenir. Bir page pages/<area>/<name>.go dosyasındadır, içeriği ise pages/ yapısını aynen yansıtan fragments/pages/<area>/<name>.go dosyasında, onun karşılığında durur. Proje büyüdükçe geri kalan her şey demo projesinin koyduğu yere gider:

pages/<area>/<name>.go            a page: its layouts, content, path, actions
fragments/layouts/master.go       Master(), the layout every page wraps itself in
fragments/pages/<area>/<name>.go  each page's content, mirroring pages/
actions/<area>/<name>.go          an action and its handler, one per file
documents/<name>.go               routes that are not HTML
data/<domain>/                    state, by domain
templates/layouts/                the layouts' HTML

Bir page'in ve bir fragment'in markup'ı Go dosyasında, data handler'ının yanında bir collage.InlineHTML sabiti olarak durur; template dosyası olan yalnızca layout'lardır. Bir page'in markup'ını düzenlemek bir Go değişikliğidir ve collage dev bunun için yeniden build alır. Bir page'e kendi template dosyasını vermek isterseniz collage add page --file bunu hâlâ yapar.

collage add page blog/post bir page'i oraya yazar ve routes.go'da register eder. collage add aynısını bir fragment, bir action ya da bir document için de yapar; bkz. CLI.

Demo projesi bunlara ek olarak şunları içerir:

  • testleri app.Handler()'ı collagetest ile ve sunucu başlatmadan çalıştıran main_test.go;
  • bir not-found page'i;
  • bir favicon;
  • demo ile errors alanlarındaki page'ler. Bu page'lerle birlikte action'ları, bir document, data/count/ içinde bir sayaç ve bunların script'i de gelir.

Scaffold'daki birkaç şeyi, değiştirmeden önce bilmekte fayda var.

main.go CLI ile bir sözleşmeye uyar.collage dev programı, environment'ında COLLAGE_DEV=1 ve dinleyeceği HOST ile PORT tanımlı olarak çalıştırır. collage export ise programı -collage-build -out <dir> ile çalıştırır.

Scaffold edilen main.go yaklaşık elli satırdır, çünkü main yalnızca collage.Main(newApp)'i çağırır ve bunların hepsine collage.Main uyar. newApp'e bir collage.Env verir: değişkenin belirlediği Dev, dinlenecek Host ile Port ve CacheDir. Ardından kendisine söylenen adreste serve eder, flag verildiğinde ise siteyi serve etmek yerine dosyalara render eder.

Flag'lerden sonra gelen bir kelime, yani go run . <command>, bir plugin'in komutunu çalıştırır. Bu komutu da collage.Main dispatch eder. collage.Main'i kendi yazdığınız bir main ile değiştirirseniz bunların hepsinin çalışmaya devam etmesini sağlayın. Aksi hâlde bu komutlar işe yarar hiçbir şey yapmaz. Ayrıntılar CLI referansında yer alır.

plugins.go plugin listesidir. Bu dosyadaki plugins() fonksiyonu plugin'leri sırayla döndürür. main.go onu bir kez, Plugins: plugins() olarak verir. Liste başlangıçta boştur. collage plugin add elagoht/sitemap listeye bir girdi yazar, collage plugin del ise bir girdiyi kaldırır. Bkz. Plugin kullanmak.

newApp, main'den ayrıdır.newApp bütün uygulamayı kurar: config'i, routes.go'daki route'ları ve /static/ mount'unu. Sonra bir sunucu başlatmadan uygulamayı döner. Demo projesindeki main_test.go aynı fonksiyonu çağırır ve app.Handler()'ı collagetest ile çalıştırır. Böylece testler sitenin ayrıca kurulmuş ikinci bir kopyasını değil, gerçekten çalışan siteyi test eder. Test yazmak sayfasına bakın.

Template'ler, static dosyalar ve plugin ayarları embed edilir.embed.go içindeki tek bir //go:embed all:templates all:static plugins-config.json satırı bunları binary'nin içine tek bir dosya sistemi, yani files olarak embed eder. Bu sayede binary herhangi bir çalışma dizininden çalışabilir. collage dev ise -tags collage_dev ile build eder: bu tag embed.go yerine embed_dev.go'yu alır ve hiçbir şey embed edilmez. Orada files diskteki proje dizinidir. Böylece düzenlediğiniz bir template bir sonraki request'te yine görünür, files verilen bir plugin düzenlemekte olduğunuz kopyayı okur ve Go build cache'i her kaydetmede onların bir kopyasını daha biriktirmez (collage dev sayfasına bakın).

newApp, Env üzerinden files'tan iki şey okur. env.PluginConfig(files), plugins-config.json dosyasıdır: çalışma dizininde bu dosya varsa o okunur, böylece bir deployment bir ayarı yeniden build etmeden değiştirebilir; yoksa binary'deki kopya okunur. env.Static(files, "static") ise /static/'in serve ettiği şeydir.

Development'ta static dosyalar os.DirFS ile değil, os.OpenRoot ile mount edilir. Bunu env.Static yapar. Bir os.Root, dizinin dışına çıkan bir symlink'i reddeder. os.DirFS ise onu takip eder. Production'da embed edilmiş kopya serve edilir. Bu kopya fs.Sub üzerinden sunulur, böylece static/ dizini URL'de ikinci bir path segment olarak görünmez. Static asset'ler sayfasına bakın.

Production'da render edilen page'ler diskte, .cache/ altında cache'lenir. Development'ta page cache hiç okunmaz. Böylece yaptığınız bir değişiklik hiçbir zaman stale bir page'in arkasında kalmaz. Caching sayfasına bakın.

Environment dosyası

Minimal ya da demo, her proje bir .env.example dosyasıyla gelir. Yorumları çıkarıldığında dosya şöyledir:

COLLAGE_CSRF_KEY=
PORT=6060
HOST=localhost
BASE_URL=http://localhost:6060

Bu dosyayı git'in yok saydığı .env dosyasına kopyalayın:

cp .env.example .env

collage dev, .env içindeki değişkenleri programın environment'ına ekler. .env.development varsa onun içindekileri ekler: git'in yine yok saydığı bu dosya yalnızca development'a ait ayarları tutar ve collage dev altında .env'in yerini alır. Her zaman tek bir dosya okur, ikisini birden okumaz. Kurallar kısadır:

  • Shell'inizde zaten tanımlı bir değişken önceliklidir. Bu yüzden PORT=4000 collage dev beklendiği gibi çalışır. Dosyada ne yazarsa yazsın COLLAGE_DEV=1 her zaman tanımlanır.
  • HOST ve PORT, collage dev'in kendisinin dinlediği adrestir ve başlarken bir kez okunur. Programa ise loopback bir adreste kendine ait bir HOST ve PORT verilir. Ayrıntılar için aşağıya bakın.
  • Dosya KEY=value satırlarından, # ile başlayan yorumlardan ve boş satırlardan oluşur. Satır başında export öneki ve değerin etrafında tırnak kullanabilirsiniz.
  • Hatalı bir satır atlanmaz, dosya adı ve satır numarasıyla birlikte raporlanır. Çünkü atlanan bir satır, sizin yazdığınız ama programın hiç görmediği bir ayar demektir. Siz satırı düzeltene kadar hiçbir şey başlatılmaz ya da yeniden başlatılmaz. Zaten çalışan bir build serve etmeye devam eder. collage dev de izlemeyi sürdürür, yani düzeltmeyi kaydettiğinizde süreç kaldığı yerden devam eder.
  • Hiç dosya olmaması bir hata değildir. Dosya varsa adı stderr'e yazılır.
  • Shell'iniz de dosya da BASE_URL'i ayarlamıyorsa değeri collage dev'in kendi adresi olan http://localhost:6060'tır. Mutlak URL yazan bir plugin, örneğin bir sitemap ya da bir canonical link, origin olmadan başlamayı reddeder. Development'ta doğru origin de budur.

Program da bu dosyaları okur. Scaffold edilen main'in çağırdığı collage.Main, newApp çalışmadan önce çalışma dizinindeki .env'i aynı kurallarla yükler. COLLAGE_DEV=1 altında önce .env.development'a bakar. Böylece os.Getenv("BASE_URL") dosyayı go run .'ta, collage export'ta ve build edilmiş binary'de görür, source .env gerekmez. Değişkenlerini kendisi ayarlayan bir sunucuda o değişkenler önceliklidir ve dosyanın olmaması bir hata değildir.

BASE_URL, okuyucuların siteye ulaştığı adrestir. Bir sitemap, bir canonical link ya da bir feed bu adresi bir path'in önüne yazar. PORT'u değiştirirseniz bunu da değiştirin. Production'da sitenin kendi adresidir, örneğin https://example.com.

COLLAGE_CSRF_KEY, form'ların taşıdığı token'ları imzalar. Development sırasında boş bırakabilirsiniz. Bu durumda her process için yeni bir key üretilir. Form içeren herhangi bir şeyi deploy etmeden önce bir key tanımlayın. Aksi hâlde restart öncesinde gönderilmiş her form, restart'tan sonra reddedilir.

İçinde form olan cache'lenmiş bir page de key'e bağlıdır. Yeni bir key ile restart ettikten sonra o page, içinde eski key'in token'ı ile serve edilmez, baştan render edilir. Caching sayfasına bakın. Bir key'i şöyle üretebilirsiniz:

openssl rand -hex 32

Çalıştırın

collage dev

Site http://localhost:6060 adresinde açılır. Bu adres collage dev'in kendisidir: HOST ve PORT'u programınızın okuyacağı şekilde okuyup orada dinler. Her request'i, loopback bir adreste çalıştırdığı programa iletir. Program başlarken gelen bir request, programı bekler.

collage dev çalışırken dört şey olur.

Go değişikliklerinde yeniden build alınır

collage dev projeyi go build ile build eder ve binary'yi çalıştırır. Programı oluşturan dosyaları izler: .go dosyalarını (testler hariç), go.mod, go.sum, plugins-config.json ve environment dosyasını. Bunlardan biri değiştiğinde projeyi yeniden build eder.

Önce yeni build alınır. Eski process ancak yeni build başarıyla derlendikten sonra düzgünce durdurulur ve yenisi başlatılır. Derlenmeyen bir değişiklikte program durdurulur ve bir değişiklik yeniden derlenene kadar localhost:6060 derleyicinin hatasını gösterir. Böylece bir yazım hatası, artık kodla uyuşmayan bir build'in arkasına saklanmaz.

Art arda yapılan kayıtlar tek bir rebuild tetikler. Gizli dizinler, bin, dist, node_modules, testdata ve vendor hiçbir zaman izlenmez. Böylece çalışan programın yazdığı hiçbir dosya kendi rebuild'ini tetikleyemez. Kendiliğinden kapanan bir program da döngü halinde yeniden başlatılmaz. Başlangıçta oluşan bir panic ya da template'i eksik olan bir page buna örnektir. Program bir sonraki değişikliğinizde yeniden başlar.

Template'ler ve static dosyalar diskten okunur

Development mode'da her template, her render'dan önce diskten yeniden parse edilir. Static dosyalar da diskteki static/ dizininden serve edilir. İkisini düzenlemek de rebuild gerektirmez ve rebuild yapılmaz.

Tarayıcı kendini yeniler

Development'ta serve edilen her page küçük bir script taşır. Bu script bir template ya da static dosya değiştiğinde ve program bir rebuild'den sonra yeniden ayağa kalktığında page'i yeniler. Bir dosyayı kaydedip tarayıcıya bakmanız yeterlidir, kurmanız gereken bir şey yoktur.

Programınızın diskten kendisinin okuduğu içerik, örneğin Markdown ya da JSON, ne template ne de static dosyadır. Bu içerikteki değişikliklerin de page'i yenilemesini istiyorsanız dizinini Config.DevWatch içinde belirtin.

Script hiçbir zaman production'daki bir page'e eklenmez. Bir form gönderiminin response'una da eklenmez, çünkü page'i yenilemek form'u yeniden gönderirdi.

Script sunucuya açık bir stream tutar. Bir tarayıcı HTTP/1.1 üzerinden bir origin'e, tüm sekmeleri toplamında en fazla altı bağlantı açar. Açık her development sekmesinde bir stream olunca, yan yana açık altı page altı bağlantının hepsini tutardı ve başka hiçbir şey yüklenmezdi: ne yedinci sekme yüklenirdi ne de bu page'lerin kendi fragment'leri.

Bu yüzden her development sekmesi tek bir shared worker üzerinden dinler: /_collage/reload-worker.js. Bu worker, kaç page açık olursa olsun hepsi için tek bir stream tutar. Shared worker olmayan yerlerde her sekme kendi stream'ini tutar, gizliyken onu kapatır ve yeniden görüldüğünde tekrar bağlanır. Gizliyken bir şey değiştiyse page o anda yenilenir.

Hiç kapanmayan bir stream, yüklenmesi hiç bitmeyen bir page demektir. Bir ekran görüntüsü aracı ya da bir end-to-end test de tam olarak bunun bitmesini bekler.

Playwright, Puppeteer ya da Selenium'un yönettiği bir tarayıcı navigator.webdriver'ı set eder ve script orada bağlanmaz. Bunu set etmeyen araçlar için, yani headless Chrome'un --screenshot ve --dump-dom seçenekleri için, URL'ye ?collage-reload=0 ekleyin. Page script olmadan serve edilir.

Hatalar page'in üzerinde görünür

Development'ta başarısız olan bir fragment sessizce ortadan kaybolmaz. Page, üzerinde bir panel ile serve edilir. Bu panel fragment'in adını ve hatasını gösterir, template hatalarında dosya ve satırı da belirtir. Hatayı bir fallback kapatmış olsa bile panel yine görünür. Page'in tamamı başarısız olduğunda, built-in error page önce nedeni gösterir: başarısız olan çağrının template'ini, satırını, sütununu ve çağrının ne döndüğünü. Ardından hatanın başladığı fragment'i söyler ve bir panic'in stack'i dahil bütün hata zincirini gösterir. Kendi yazdığınız bir error page'in üstünde de aynı panel çıkar ve hangi page'in yerine gösterildiğini belirtir.

Cevap verecek bir program olmadığında (program başlarken kapandıysa ya da ilk build derlenmediyse) page, reddedilen bir bağlantı yerine programın ya da derleyicinin yazdırdıklarını gösteren bir 503 olur. Açık olan bir page yenilenerek bu page'e geçer ve bir değişiklik programı geri getirdiğinde yeniden yenilenir. Başladıktan 10 saniye sonra hâlâ kendisine verilen adreste dinlemeyen bir program da bu page'de, kendisine verilen adresle birlikte belirtilir.

Bunların hiçbiri development dışında yoktur. Production'daki bir error page tek bir genel cümle gösterir. Çünkü hata mesajları hostname'ler, dosya yolları ve credential'lar içerir. Bunları bir yabancının eline verme ihtimali en yüksek response da tam olarak error page'dir. Hatalar sayfasına bakın.

Örnek: bir ekip arkadaşı için proje kurmak

Başka birinin de üzerinde çalışacağı bir projeye başlıyorsunuz: ekibin iş listesi uygulaması. Projeyi bir kez scaffold edip commit'lersiniz. Sonra her biriniz onu kendi makinesinde, kendi ayarlarıyla çalıştırır.

Kendi makinenizde şunları bir kez çalıştırın:

collage new team --template demo -module github.com/you/team
cd team
go mod tidy

Scaffold edilen .gitignore, paylaşılanla paylaşılmayanın arasındaki çizgiyi zaten çeker. Yorumları çıkarıldığında kuralları şunlardır:

/bin/team
/bin/team.exe
/dist/
/.cache/
*.exe
/.env
/.env.*
!/.env.example
YolCommit'lenir miNeden
go.mod, go.sumevetHerkesin build aldığı collage sürümünü sabitler
.env.exampleevetKopyalanacak değişkenleri tutar, içinde hiçbir secret yoktur
collage new'in yazdığı diğer her şeyevetProjenin kendisi
.env.development, .envhayırHerkesin kendi değişkenleri
/bin/teamhayırcollage build'in yazdığı dosya
/dist/hayırcollage export'un yazdıkları
/.cache/hayırRestart'lar arasında saklanan render edilmiş page'ler

Ekip arkadaşınızın da yukarıda anlatıldığı gibi Go'ya ve CLI'a ihtiyacı vardır. Repository'yi clone'ladıktan sonra demo projesinin README.md'sinde listelenen adımları çalıştırır:

cd team
go mod tidy
cp .env.example .env
collage dev

go.mod zaten bir collage sürümünü gerektirdiği için bu go mod tidy başka bir sürüm seçmez, o sürümü çeker. .env.example projenin geri kalanıyla birlikte commit'lenir (!/.env.example satırı onu yok sayılan dosyaların dışında tutar). Bu yüzden projenin sonradan ihtiyaç duyduğu bir değişken, içinde secret olmadan oraya eklenir ve bir sonraki kişi onu kopyalar.

Herkesin .env dosyası kendine aittir. Orada COLLAGE_CSRF_KEY yukarıda anlatıldığı gibi boş kalabilir ya da o kişinin kendi key'ini tutabilir. Deploy edilen sitenin kullandığı key, production environment'ının secret'larına girer. Herkesin okuyabildiği .env.example'a asla girmez.

Portu değiştirmek. 6060 portu dolu olan biri, kendi .env dosyasında başka bir port belirler. BASE_URL'i de onunla birlikte değiştirin. Bu değişken collage dev'in serve ettiği adrestir. Bir sitemap, canonical bir link ya da bir feed de path'lerin önüne bu adresi koyar.

PORT=6161
HOST=localhost
BASE_URL=http://localhost:6161

collage dev başlarken adresi ve okuduğu dosyayı yazar:

01:09:37 - collage dev: serving http://localhost:6161
01:09:37 - collage dev: loaded .env

Bu adres bir kez, başlarken belirlenir. Dosyaya yeni bir PORT kaydetmek programı yeniden build eder, ama collage dev siz onu durdurup yeniden başlatana kadar eski adreste dinlemeye devam eder. Tek bir çalıştırma için PORT=4000 collage dev dosyaya dokunmadan aynı işi görür.

Editör desteği

VS Code için Collage Snippets & Highlighter extension'ı vardır. Şunları ekler:

  • Snippet'ler: Go için (cpage, cfragd, caction, cplugin …) ve template'ler için (clayout, cslot, cform, cformv …). Birçok Go snippet'i (cpagef, cactionf, cvalid, credirect, cdataf, cmeta …), dosyada package satırı yoksa onu da ekler: yanındaki dosyaların package'ı, go.mod'un yanında main, değilse dizinin adı. Kullandıkları import'ları da ekler; collage-validate ve collage-flash import'ları da buna dahildir.
  • Highlighting: HTML içindeki {{ … }} renklendirilir. Template'ler HTML dosyası olarak kalır, bu yüzden Emmet, tag tamamlama ve biçimlendirme çalışmaya devam eder. Go'da inline bir fragment'in template'i de HTML olarak renklendirilir; argümanlar tek satırda ya da birkaç satırda olabilir. collage.InlineHTML olarak tanımlanmış bir sabit de öyle.
  • Go içindeki HTML, HTML olarak düzenlenir: inline bir template'te tag ve attribute tamamlama, HTML snippet'leriniz, Emmet, hover, katlama, eşleşen tag ve yazarken kapanan tag'ler. {{ … }} içinde de aşağıdaki her şey çalışır.
  • Completion ve hover: collage'ın, yayımlanmış plugin'lerinin ve Go'nun builtin'leri olan her template fonksiyonu için, imzası ve dokümantasyonuyla.
  • Projenizdeki adlar: {{pageURL "…"}} içinde page'ler ve parametreleri, {{fragmentURL "…" "…"}} içinde fragment'ler, {{slot "…"}} içinde slot'lar ve {{asset "…"}} içinde mount edilmiş dosyalar.
  • Diagnostics ve go to definition: var olmayan bir page, fragment ya da dosya için bir uyarı verir. F12 ile bir addan onu tanımlayan Go koduna gidersiniz.
  • plugins-config.json doğrulaması: yayımlanmış her plugin ve collage.json içeren her plugin için completion, açıklamalar ve yanlış yazılmış bir key için uyarı.

Extension, projenizdeki adları projeyi collage dev gibi derleyip collage-inspect ile çalıştırarak öğrenir; collage inspect de aynısını yapar. Bunu go.mod'u collage'ı gerektiren her dizinde yapar ve bir Go dosyası her kaydedildiğinde tekrarlar. Bir collage projesi, hiçbir şey eklemeden bu komuta cevap verir.

Extension henüz VS Code Marketplace'te değildir. .vsix dosyasını son release'inden indirin ve kurun:

code --install-extension collage-snippets-highlighter-<version>.vsix
AyarVarsayılanNe yapar
collage.completionsautoCompletion ve hover'ın nerede sunulacağı: auto, yalnızca go.mod'u collage'ı gerektiren bir dizinde; always; ya da never
collage.inspecttrueProjeyi öğrenmek için projenin collage-inspect ile çalıştırılıp çalıştırılmayacağı. Bu komut uygulamayı sunmadan kurar. Bu yüzden kurulurken veritabanına bağlanan bir program burada da bağlanır
collage.diagnosticswarningVar olmayan bir adın nasıl raporlanacağı: off, information, warning ya da error
collage.goCommandgoÇalıştırılacak go komutu

Snippet'ler ve highlighting her zaman açıktır. Extension'ın README'si bütün snippet'leri ve renklendirilecek scope'ları listeler.

Sırada ne var

İlk page'iniz, minimal bir projede sıfırdan, veri kullanan bir page oluşturur. Yayına almaya hazır olduğunuzda collage build bir binary üretir, collage export ise static dosyalar yazar. Deployment ve Static export sayfalarına bakın.