✨ feat: add project setup skill documentation; provide step-by-step guide for initializing new tibi projects
This commit is contained in:
173
.agents/skills/tibi-project-setup/SKILL.md
Normal file
173
.agents/skills/tibi-project-setup/SKILL.md
Normal file
@@ -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 `<svelte:head>` 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 `<svelte:head>` with a `<title>` 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.**
|
||||
Reference in New Issue
Block a user