Sebastian Frank
40ffa8207e
- Introduced ContactFormBlock, FeaturesBlock, HeroBlock, and RichtextBlock components. - Implemented a scroll-reveal action for animations on element visibility. - Enhanced CSS styles for better theming and prose formatting. - Added localization support for new components and updated existing translations. - Created e2e tests for demo pages including contact form validation and navigation. - Added a video tour showcasing the demo pages and interactions.
90 lines
4.7 KiB
Markdown
90 lines
4.7 KiB
Markdown
# 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`).
|