tibi-svelte-starter/README.md

tibi-starter

Starter Kit für SPAs(s) ;) mit Svelte und TibiCMS inkl. SSR

Neues Projekt erstellen — Schritt-für-Schritt

Diese Anleitung ist so geschrieben, dass ein autonomer Agent oder ein Entwickler sie 1:1 abarbeiten kann, um ein eigenständiges tibi-Projekt mit eigener Code-Server-Subdomain zu erstellen.

Voraussetzungen

• Zugang zum Code-Server unter *.code.testversion.online
• git, yarn, make, docker compose verfügbar
• Traefik-Reverse-Proxy läuft auf dem Host (verwaltet *.code.testversion.online-Subdomains automatisch via Docker-Labels)

1. Repository klonen (falls noch nicht geschehen)

Wenn du bereits in einem geklonten Projekt arbeitest, überspringe diesen Schritt und gehe direkt zu Schritt 2.

# Im Workspace-Verzeichnis (z.B. /WM_Dev/src/gitbase.de/cms/)
git clone https://gitbase.de/cms/tibi-svelte-starter.git mein-projekt
cd mein-projekt
git remote rename origin template
# Neues Remote-Repo anlegen (z.B. auf gitbase.de) und als origin setzen:
# git remote add origin https://gitbase.de/org/mein-projekt.git

2. Platzhalter ersetzen

Alle Platzhalter müssen durch die echten Projektwerte ersetzt werden. Hier die vollständige Liste:

Platzhalter	Wo	Ersetzen durch	Beispiel
__PROJECT_NAME__	.env	Projektname (kebab-case, wird für URLs und Container verwendet)	mein-projekt
__TIBI_NAMESPACE__	.env	Tibi-Namespace (snake_case, wird als DB-Prefix und in API-URLs verwendet)	mein_projekt
__NAMESPACE__	api/config.yml, frontend/.htaccess	Gleicher Wert wie TIBI_NAMESPACE	mein_projekt

# Projektname (kebab-case) — für URLs, Docker-Container, Subdomains
PROJECT=mein-projekt
# Tibi-Namespace (snake_case) — für DB, API-Pfade
NAMESPACE=mein_projekt

sed -i "s/__PROJECT_NAME__/$PROJECT/g" .env
sed -i "s/__TIBI_NAMESPACE__/$NAMESPACE/g" .env
sed -i "s/__NAMESPACE__/$NAMESPACE/g" api/config.yml frontend/.htaccess

Ergebnis in .env:

PROJECT_NAME=mein-projekt
TIBI_NAMESPACE=mein_projekt
CODING_URL=https://mein-projekt.code.testversion.online
STAGING_URL=https://dev-mein-projekt.staging.testversion.online

3. Seitentitel anpassen

Der Seitentitel wird dynamisch über <svelte:head> in frontend/src/App.svelte gesetzt. Die Demo-App verwendet dafür die Konstante SITE_NAME. In einem neuen Projekt wird App.svelte typischerweise komplett neu geschrieben — dabei einfach sicherstellen, dass <svelte:head> mit einem passenden <title> vorhanden ist. SSR injiziert ihn dann automatisch über den <!--HEAD-->-Platzhalter in spa.html.

4. Admin-Token prüfen

api/config.yml.env enthält bereits ein ADMIN_TOKEN. Für Produktionsprojekte durch ein sicheres Token ersetzen:

echo "ADMIN_TOKEN=$(openssl rand -hex 20)" > api/config.yml.env

5. Subdomains prüfen

Traefik erkennt die Docker-Labels automatisch. Nach make docker-up sind folgende URLs verfügbar:

Dienst	URL
Website (BrowserSync)	https://{PROJECT_NAME}.code.testversion.online/
Tibi Admin	https://{PROJECT_NAME}-tibiadmin.code.testversion.online/
Tibi Server API	https://{PROJECT_NAME}-tibiserver.code.testversion.online/
Maildev	https://{PROJECT_NAME}-maildev.code.testversion.online/

Es ist KEINE manuelle Traefik-Konfiguration nötig. Die Subdomains werden automatisch über das Docker-Label online.testversion.code.subdomain=${PROJECT_NAME} registriert. Traefik überwacht Docker-Events und erstellt die Routen dynamisch.

6. Starten

yarn install
make docker-up      # Stack im Hintergrund starten
# oder
make docker-start   # Stack im Vordergrund (CTRL-C zum Stoppen)

Prüfe, ob alles läuft:

make docker-ps      # Container-Status anzeigen
make docker-logs    # Logs verfolgen

7. Mock-Modus (Frontend ohne tibi-server)

Für schnelle UI-Entwicklung ohne Backend:

# In .env setzen:
MOCK=1
# Dann:
make docker-up

Mock-Daten liegen in frontend/mocking/ als JSON-Dateien. Fehlende Endpunkte liefern 404.

8. Demo-Inhalte entfernen

Für ein echtes Projekt die Demo-Dateien entfernen/ersetzen:

Datei/Ordner	Inhalt
frontend/src/blocks/	Demo-Block-Komponenten (HeroBlock, FeaturesBlock, etc.)
frontend/mocking/content.json	Demo-Mockdaten für Content
frontend/mocking/navigation.json	Demo-Mockdaten für Navigation
api/collections/content.yml	Content-Collection-Konfiguration
api/collections/navigation.yml	Navigation-Collection-Konfiguration
tests/e2e/	Demo-E2E-Tests
video-tours/tours/	Demo-Video-Tour

Danach frontend/src/App.svelte (Header, Footer, Content-Loading) an das eigene Datenmodell anpassen.

9. Build und Deployment

yarn build          # Frontend für moderne Browser
yarn build:server   # SSR-Bundle (für tibi-server goja-Hooks)
yarn build:admin    # Admin-Module (optional)
yarn validate       # TypeScript + Svelte prüfen (muss 0 Fehler/Warnungen zeigen)

Checkliste für autonome Agents

[ ] Repository geklont und Remote gesetzt
[ ] __PROJECT_NAME__ in .env ersetzt
[ ] __TIBI_NAMESPACE__ in .env ersetzt
[ ] __NAMESPACE__ in api/config.yml und frontend/.htaccess ersetzt
[ ] App.svelte mit eigenem Template und <svelte:head> (inkl. <title>) erstellt
[ ] ADMIN_TOKEN in api/config.yml.env gesetzt
[ ] yarn install ausgeführt
[ ] make docker-up gestartet
[ ] Website unter https://{PROJECT_NAME}.code.testversion.online/ erreichbar
[ ] yarn validate zeigt 0 Fehler und 0 Warnungen
[ ] yarn build und yarn build:server erfolgreich

---

Architektur

Via Svelte wird eine SPA (Single-Page-App) programmiert. Der Code wird einmal für den Browser aufbereitet und außerdem für den Server kompiliert und transpiliert. Der Server-Code wird in einem tibi-server SSR-Hook eingebunden und generiert fertiges HTML anhand der aktuellen Route — für SEO und optimierte Ladezeiten.

Die Navigation innerhalb der App löst nur API-Aufrufe aus, ohne jedes Mal SSR anzustoßen. Ein Cache in der ssr-Collection minimiert die SSR-Last.

SSR-Details:

• <title> und <meta description> kommen über <svelte:head> aus App.svelte → SSR injiziert sie in den <!--HEAD-->-Platzhalter von spa.html
• <html lang> wird vom SSR-Hook (api/hooks/ssr/get_read.js) anhand der URL-Sprache gesetzt
• SSR-Bundle wird mit yarn build:server erstellt und landet in api/hooks/lib/app.server.js

Weiteres Build-Target:

yarn build:admin    # Admin-Module