diff --git a/.agents/skills/tibi-project-setup/SKILL.md b/.agents/skills/tibi-project-setup/SKILL.md new file mode 100644 index 0000000..0737f81 --- /dev/null +++ b/.agents/skills/tibi-project-setup/SKILL.md @@ -0,0 +1,173 @@ +--- +name: tibi-project-setup +description: Set up a new tibi project from the tibi-svelte-starter template. Covers cloning, placeholder replacement, environment config, Docker startup, mock mode, demo cleanup, and build verification. Use when creating a new project or onboarding into this template. +--- + +# tibi-project-setup + +## When to use this skill + +Use this skill when: + +- Creating a new project from the `tibi-svelte-starter` template +- Onboarding into a freshly cloned starter project where placeholders haven't been replaced yet +- The user asks to "set up", "initialize", or "bootstrap" a new tibi project + +## Prerequisites + +- Code-Server environment at `*.code.testversion.online` +- `git`, `yarn`, `make`, `docker compose` available +- Traefik reverse proxy running on the host (manages `*.code.testversion.online` subdomains automatically via Docker labels) + +## Step 1 — Clone and set up remotes + +Skip this step if already inside a cloned project. + +```sh +# In the workspace directory (e.g. /WM_Dev/src/gitbase.de/cms/) +git clone https://gitbase.de/cms/tibi-svelte-starter.git my-project +cd my-project +git remote rename origin template +# Create a new remote repo (e.g. on gitbase.de) and add as origin: +# git remote add origin https://gitbase.de/org/my-project.git +``` + +**Verify:** `git remote -v` shows `template` pointing to the starter and optionally `origin` pointing to the new repo. + +## Step 2 — Replace placeholders + +Three placeholders must be replaced in the correct files: + +| Placeholder | Files | Format | Example | +| -------------------- | -------------------------------------- | --------------------------------------------------------- | ------------ | +| `__PROJECT_NAME__` | `.env` | kebab-case (used for URLs, Docker containers, subdomains) | `my-project` | +| `__TIBI_NAMESPACE__` | `.env` | snake_case (used as DB prefix and in API URLs) | `my_project` | +| `__NAMESPACE__` | `api/config.yml`, `frontend/.htaccess` | snake_case — same value as `TIBI_NAMESPACE` | `my_project` | + +```sh +PROJECT=my-project # kebab-case +NAMESPACE=my_project # snake_case + +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 +``` + +**Verify each replacement:** + +```sh +grep -n '__PROJECT_NAME__\|__TIBI_NAMESPACE__\|__NAMESPACE__' .env api/config.yml frontend/.htaccess +# Expected: no output (all placeholders replaced) +``` + +**Result in `.env`:** + +```dotenv +PROJECT_NAME=my-project +TIBI_NAMESPACE=my_project +CODING_URL=https://my-project.code.testversion.online +STAGING_URL=https://dev-my-project.staging.testversion.online +``` + +### Common mistakes + +- **Mixing formats**: `PROJECT` must be kebab-case (`my-project`), `NAMESPACE` must be snake_case (`my_project`). Never use kebab-case where snake_case is expected or vice versa. +- **Forgetting `frontend/.htaccess`**: Contains the namespace for API rewrite rules. If missed, API calls from the frontend will fail silently. +- **Forgetting `api/config.yml`**: First line is `namespace: __NAMESPACE__`. If not replaced, tibi-server won't start correctly. + +## Step 3 — Page title + +The page title is set dynamically via `` in `frontend/src/App.svelte`. The demo app uses the constant `SITE_NAME` for this. In a new project, `App.svelte` is typically rewritten completely — just make sure `` with a `` is present. SSR automatically injects it via the `<!--HEAD-->` placeholder in `spa.html`. + +## Step 4 — Admin token + +`api/config.yml.env` ships with a default `ADMIN_TOKEN`. For production projects, generate a secure one: + +```sh +echo "ADMIN_TOKEN=$(openssl rand -hex 20)" > api/config.yml.env +``` + +**Verify:** `cat api/config.yml.env` shows a 40-character hex token. + +## Step 5 — Install, upgrade, and start + +```sh +yarn install +yarn upgrade # Update all deps to latest versions within package.json ranges +make docker-up # Start stack in background +# or +make docker-start # Start stack in foreground (CTRL-C to stop) +``` + +`yarn upgrade` is safe here because the project is freshly cloned and nothing is running yet. The template's `yarn.lock` may be months old — upgrading ensures you start with the latest compatible (semver-range) versions. + +**Do NOT run `yarn upgrade` on an existing, running project without testing.** Even patch-level updates can introduce regressions. For running projects, upgrade targeted packages with `yarn upgrade <package>` and verify with `yarn validate` + `yarn build`. + +**Verify containers are running:** + +```sh +make docker-ps # All containers should be "Up" +make docker-logs # Check for errors +``` + +## Step 6 — Verify URLs + +Traefik picks up Docker labels automatically — no manual config needed. After `make docker-up`, these URLs become available: + +| Service | 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/` | + +The subdomains are registered via the Docker label `online.testversion.code.subdomain=${PROJECT_NAME}`. Traefik watches Docker events and creates routes dynamically. + +**Verify:** `curl -sI https://{PROJECT_NAME}.code.testversion.online/ | head -1` returns `HTTP/2 200`. + +## Step 7 — Mock mode (optional) + +For frontend development without a running tibi-server backend: + +```sh +# Set in .env: +MOCK=1 +# Then restart: +make docker-up +``` + +Mock data lives in `frontend/mocking/` as JSON files. Missing endpoints return 404. + +**When to use mock mode:** Early UI prototyping, frontend-only work, CI environments without a database. + +## Step 8 — Remove demo content + +For a real project, remove or replace the demo files: + +| File/Folder | Content | +| ---------------------------------- | ------------------------------------------------------ | +| `frontend/src/blocks/` | Demo block components (HeroBlock, FeaturesBlock, etc.) | +| `frontend/mocking/content.json` | Demo mock data for content | +| `frontend/mocking/navigation.json` | Demo mock data for navigation | +| `api/collections/content.yml` | Content collection config | +| `api/collections/navigation.yml` | Navigation collection config | +| `tests/e2e/` | Demo E2E tests | +| `video-tours/tours/` | Demo video tour | + +Then adapt `frontend/src/App.svelte` (header, footer, content loading) to your own data model. + +**Decision guide:** + +- **Keep demo content** if you want to use it as a reference while building your own components. +- **Delete immediately** if you're starting with a completely custom design and the demo files would only cause confusion. + +## Step 9 — Build and validate + +```sh +yarn build # Frontend bundle for modern browsers +yarn build:server # SSR bundle (for tibi-server goja hooks) +yarn build:admin # Admin modules (optional) +yarn validate # TypeScript + Svelte checks (must show 0 errors and 0 warnings) +``` + +**All four commands must succeed with exit code 0 before the project is considered set up.** diff --git a/AGENTS.md b/AGENTS.md index c8af462..fb3bfb8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,8 +12,6 @@ Tibi CMS starter template — Svelte 5 SPA with esbuild, SSR via goja, and Playw ## Setup commands -> **New project from this template?** Follow the step-by-step guide in [README.md](README.md). - - Install deps: `yarn install` - Start dev: `make docker-up && make docker-start` - Start with mock data: set `MOCK=1` in `.env`, then `make docker-up && make docker-start` diff --git a/README.md b/README.md index 6435369..7a0655b 100644 --- a/README.md +++ b/README.md @@ -2,156 +2,25 @@ Starter Kit für SPAs(s) `;)` mit Svelte und TibiCMS inkl. SSR -## Neues Projekt erstellen — Schritt-für-Schritt +> **Neues Projekt aufsetzen?** → Skill `.agents/skills/tibi-project-setup/SKILL.md` -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 +## Setup-Checkliste ```text -[ ] Repository geklont und Remote gesetzt -[ ] __PROJECT_NAME__ in .env ersetzt -[ ] __TIBI_NAMESPACE__ in .env ersetzt +[ ] Repository geklont und Remotes konfiguriert +[ ] __PROJECT_NAME__ in .env ersetzt (kebab-case) +[ ] __TIBI_NAMESPACE__ in .env ersetzt (snake_case) [ ] __NAMESPACE__ in api/config.yml und frontend/.htaccess ersetzt -[ ] App.svelte mit eigenem Template und <svelte:head> (inkl. <title>) erstellt +[ ] Keine verbleibenden __*__-Platzhalter (mit grep prüfen) +[ ] App.svelte hat <svelte:head> mit <title> [ ] ADMIN_TOKEN in api/config.yml.env gesetzt -[ ] yarn install ausgeführt +[ ] yarn install && yarn upgrade ausgeführt [ ] make docker-up gestartet -[ ] Website unter https://{PROJECT_NAME}.code.testversion.online/ erreichbar +[ ] Website erreichbar unter https://{PROJECT_NAME}.code.testversion.online/ [ ] 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.