tibi-svelte-starter/AGENTS.md

AGENTS.md

Tibi CMS starter template — Svelte 5 SPA with esbuild, SSR via goja, and Playwright tests.

Project overview

• Frontend: Svelte 5 SPA in frontend/src/, bundled with esbuild, styled with Tailwind CSS 4.
• Backend: tibi-server with API hooks in api/hooks/, collections in api/collections/.
• SSR: Server-side rendering via goja (Go JS runtime) in api/hooks/ssr/.
• Tests: Playwright for E2E, API, mobile, and visual regression tests in tests/.
• Types: Shared TypeScript types in types/global.d.ts. Keep tibi-types/ read-only.

Setup commands

• 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
• Build frontend: yarn build
• Build SSR bundle: yarn build:server
• Validate types: yarn validate

Development workflow

• Dev servers always run in Docker — never use yarn dev or yarn start locally; web access only works through the Docker reverse proxy.
• Docker/Makefile commands: make docker-up, make docker-start, make docker-logs, make docker-restart-frontend.
• Local yarn is only for standalone tasks: yarn build, yarn build:server, yarn validate.
• Mock mode: Set MOCK=1 to run the frontend without a tibi-server. API calls are served from JSON files in frontend/mocking/. Enable in Docker via MOCK=1 in .env, then make docker-up && make docker-start. Missing mock endpoints return 404.
• Frontend code is automatically built by watcher and BrowserSync; backend hooks are automatically reloaded on change.
• Read .env for environment URLs and secrets.
• webserver/ is for staging/ops only; use BrowserSync/esbuild for day-to-day dev.
• If development environment is running, access the website at: https://${PROJECT_NAME}.code.testversion.online/.
• To force a restart of the frontend build and dev-server: make docker-restart-frontend.
• To show last X lines of docker logs: make docker-logs-X.
• Esbuild watches for file changes and rebuilds automatically.
• For a11y testing use MCP a11y tools if available.
• For quick interactive browser testing, ask the user to connect Playwright MCP (preferred) or Browser MCP (only in non-autonomous/chat mode).

Testing

• Run all tests: yarn test
• E2E tests: yarn test:e2e
• API tests: yarn test:api
• Visual regression: yarn test:visual
• After code changes, run only affected spec files: npx playwright test tests/e2e/filename.spec.ts.
• Write unit tests for new functionality and ensure existing tests pass.

Video tours

• Video tours are Playwright-based screen recordings (not tests) in video-tours/.
• Run all tours (desktop): yarn tour
• Run all tours (mobile): yarn tour:mobile
• Videos are saved to video-tours/output/ (git-ignored).
• Tour files use .tour.ts suffix in video-tours/tours/.
• Helpers: injectVisibleCursor(), moveThenClick(), moveThenType(), smoothScroll() in video-tours/helpers.ts.
• Fixtures provide a tourPage with visible cursor overlay via video-tours/tours/fixtures.ts.

API access

• API access to collections uses the reverse proxy: CODING_URL/api/<collection> (e.g. CODING_URL/api/content).
• Auth via Token header with ADMIN_TOKEN from api/config.yml.env.

Required secrets and credentials

Secret	Location	Purpose
ADMIN_TOKEN	api/config.yml.env	API admin auth + tibi-admin login
SENTRY_AUTH_TOKEN	Gitea repo secrets	Sourcemap upload to Sentry (CI only)
.basic-auth-web	project root (git-ignored)	Basic auth for BrowserSync dev server
.basic-auth-code	project root (git-ignored)	Basic auth for Code-Server / admin
RSYNC_PASS	Gitea secrets (github.token)	rsync deployment password (CI only)

Note: .basic-auth-web and .basic-auth-code are plain text files in user:password format (htpasswd). They are required by Docker Traefik labels for dev environment access. Curl and Playwright requests are let through without basic auth via Traefik label configuration.

Infrastructure prerequisites

• Code-Server environment — This project is designed for development on a Code-Server instance at *.code.testversion.online with a Traefik reverse proxy managing HTTPS and auto-routing via Docker labels.
• Without Code-Server/Traefik — The Docker stack starts but the website is not reachable via hostname. Workaround: access BrowserSync directly via http://localhost:3000 (requires exposing the port in docker-compose-local.yml).
• Docker + Docker Compose — Required for all development. Never run yarn dev or yarn start locally.
• MongoDB — Runs as a Docker service (mongo). Data persists in tmp/mongo-data/.
• Production — Deployed via rsync to an existing server running tibi-server + MongoDB. The frontend is a static SPA served by a Node.js webserver (webserver/webserver.js) or directly by tibi-server.
• Staging — Docker Compose builds a www container that connects to an external tibi-server at dev-tibi-server.staging.testversion.online.

Reference repositories

These sibling repos in the workspace provide documentation, types, and reference implementations:

Repository	Path	Purpose
tibi-types	../../cms/tibi-types	TypeScript type definitions for hooks, collections, permissions, etc. Included via tsconfig.json — read-only, do not modify. Key file: index.d.ts. JSON schemas in schemas/api-config/.
tibi-server	../../cms/tibi-server	Go source code of the server. docs/ has detailed documentation (16 files), examples/ has sample projects.
tibi-admin-nova	../../cms/tibi-admin-nova	Admin UI reference project. Key file: types/admin.d.ts (1147 lines — all admin types: AdminCollection, AdminCollectionField, AdminCollectionMeta, AdminDashboard, etc.). Use as reference for collection field configs, dashboard setup, and fieldLists.

When to consult which repo

• Write collection YAML → tibi-server/docs/04-collections.md + tibi-types/schemas/api-config/collection.json (JSON schema)
• Write/debug hooks → tibi-server/docs/06-hooks.md + tibi-types/index.d.ts (context types)
• Configure admin UI → tibi-admin-nova/types/admin.d.ts (field types, meta, dashboard) + tibi-admin-nova/api/collections/ (real examples)
• Permissions → tibi-server/docs/05-authentication.md
• Realtime/SSE → tibi-server/docs/07-realtime.md
• Images/uploads → tibi-server/docs/08-file-upload-images.md
• LLM integration → tibi-server/docs/09-llm-integration.md

TypeScript types

tibi-types is included via tsconfig.json:

"include": ["frontend/src/**/*", "types/**/*", "./../../cms/tibi-types", "api/**/*"]

Project-specific types (e.g. Ssr, ApiOptions, ContentEntry) live in types/global.d.ts.

Code style

• Follow the existing code style and conventions used in the project.
• Write clear and concise comments where necessary to explain complex logic.
• Ensure code is modular and reusable where possible.
• Avoid introducing new dependencies unless absolutely necessary.
• Respect a11y and localization best practices; optimize for WCAG AA standards.
• Check the problems tab for any errors or warnings in the code.
• Zero warnings policy: After making changes, always run yarn validate and check the IDE problems tab. Fix all TypeScript, Svelte, and Tailwind warnings — the codebase must stay warning-free.
• When Tailwind suggestCanonicalClasses warnings appear, always fix the source .svelte/.ts/.css file — never the compiled output.

Architecture skills (loaded on demand)

These skills provide deep-dive documentation. Use them when working on the respective area:

Skill	When to use
content-authoring	Adding new pages, content blocks, or collections
frontend-architecture	Routing, state management, Svelte 5 patterns, API layer, error handling
admin-ui-config	Configuring collection admin views, field widgets, layouts
tibi-hook-authoring	Writing or debugging server-side hooks
tibi-ssr-caching	SSR rendering and cache invalidation
tibi-project-setup	Setting up a new project from scratch

Tailwind CSS 4 canonical classes

This project uses Tailwind CSS 4. Always use the canonical v4 syntax:

Legacy (v3)	Canonical (v4)
bg-gradient-to-*	bg-linear-to-*
aspect-[4/3]	aspect-4/3
!bg-brand-600	bg-brand-600!
hover:!bg-brand-700	hover:bg-brand-700!
!rounded-xl	rounded-xl!

Rules:

• Gradient directions use bg-linear-to-{direction} instead of bg-gradient-to-{direction}.
• Bare-ratio aspect values like aspect-4/3 replace arbitrary aspect-[4/3].
• The !important modifier is a suffix (class!) instead of a prefix (!class).