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.

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.

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