172 lines
6.5 KiB
Markdown
172 lines
6.5 KiB
Markdown
# 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**.
|
|
|
|
```sh
|
|
# 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` |
|
|
|
|
```sh
|
|
# 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`:**
|
|
|
|
```dotenv
|
|
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:
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
# 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
|
|
|
|
```sh
|
|
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
|
|
|
|
```text
|
|
[ ] 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:**
|
|
|
|
```sh
|
|
yarn build:admin # Admin-Module
|
|
```
|