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 composeverfü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>ausApp.svelte→ SSR injiziert sie in den<!--HEAD-->-Platzhalter vonspa.html<html lang>wird vom SSR-Hook (api/hooks/ssr/get_read.js) anhand der URL-Sprache gesetzt- SSR-Bundle wird mit
yarn build:servererstellt und landet inapi/hooks/lib/app.server.js
Weiteres Build-Target:
yarn build:admin # Admin-Module