tibi-svelte-starter/.agents/skills/tibi-project-setup/SKILL.md

name, description

name	description
tibi-project-setup	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.

# 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

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:

grep -n '__PROJECT_NAME__\|__TIBI_NAMESPACE__\|__NAMESPACE__' .env api/config.yml frontend/.htaccess
# Expected: no output (all placeholders replaced)

Result in .env:

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:

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

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:

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:

# 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

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.