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.

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

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).

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.

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.