cms/tibi-svelte-starter
Template
3
0
Fork 2
Code Issues Pull Requests Projects Releases Wiki Activity

🗑️ chore: remove outdated instructions and migration documentation

Browse Source
This commit is contained in:
Sebastian Frank
2026-02-25 20:45:46 +00:00
parent 602fd6101f
commit 3c3e70b474
10 changed files with 155 additions and 196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
.github/copilot-instructions.md vendored
View File

@@ -1,25 +0,0 @@
# Copilot Instructions
This workspace uses scoped instructions with YAML front matter in `.github/instructions/*.instructions.md`.
Keep this file minimal to avoid duplicate or conflicting guidance.
## Quick Reference
- **General workflow**: See `.github/instructions/general.instructions.md`
- **Frontend (Svelte)**: See `.github/instructions/frontend.instructions.md`
- **API Hooks (tibi-server)**: See `.github/instructions/api-hooks.instructions.md`
- **SSR/Caching**: See `.github/instructions/ssr.instructions.md`
- **Testing (Playwright)**: See `.github/instructions/testing.instructions.md`
## Toolchain
- See `.env` in root for project-specific environment variables
- See `Makefile` for starting up the development environment with Docker
- If development environment is running, access the website at: `https://${PROJECT_NAME}.code.testversion.online/` or ask the user for the correct URL
- You can also use Browser MCP, so ask user to connect if needed
- Esbuild is used, watching for changes in files to rebuild automatically
- To force a restart of the frontend build and dev-server run: `make docker-restart-frontend`
- Backend is tibi-server configured in `/api/` folder and also restarted if changes are detected in this folder
- To show last X lines of docker logs run: `make docker-logs-X` where X is the number of lines you want to see
- For a11y testing use the MCP a11y tools if available
- For testing run: `yarn test` (all), `yarn test:e2e`, `yarn test:api`, `yarn test:visual`

38
.github/instructions/general.instructions.md vendored
View File

@@ -1,38 +0,0 @@
---
name: General
description: Workspace-wide guidance and workflows.
applyTo: "**/*"
---
# General
## Code Style & Conventions
- Look in the problems tab for any errors or warnings in the code
- 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, but ask the user if there is a specific library they want to use
- If you are unsure about any requirements or details, ask the user for clarification before proceeding
- Respect a11y and localization best practices if applicable, optimize for WCAG AA standards
## Development Workflow
- Default dev flow is Docker/Makefile: `make docker-up`, `make docker-start`, `make docker-logs`, `make docker-restart-frontend` (see Makefile).
- Local dev is secondary: `yarn dev` for watch, `yarn build` and `yarn build:server` for production builds (see package.json).
- Frontend code is automatically built by watcher and browser-sync; backend code is automatically built and reloaded by extension, so no manual restarts needed during development.
- Read `.env` for environment URLs and secrets.
- Keep `tibi-types/` read-only unless explicitly asked.
- `webserver/` is for staging/ops only; use BrowserSync/esbuild for day-to-day dev.
## 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`.
## Testing
- Write unit tests for new functionality and ensure existing tests pass.
- Playwright is configured for E2E, API, mobile, and visual regression tests.
- Run tests via `yarn test` (all), `yarn test:e2e`, `yarn test:api`, `yarn test:visual`.
- After code changes, run only affected spec files: `npx playwright test tests/e2e/filename.spec.ts`.

12
.github/instructions/ssr.instructions.md vendored
View File

@@ -1,12 +0,0 @@
---
name: SSR
description: Server-side rendering flow and caching.
applyTo: "api/hooks/ssr/**"
---
# SSR and Caching
- SSR request flow: `api/hooks/ssr/get_read.js` calls `api/hooks/lib/ssr-server.js` and injects `window.__SSR_CACHE__` used by `api/hooks/lib/ssr.js` on the client.
- SSR cache HTML is stored in the `ssr` collection.
- SSR builds output to `api/hooks/lib/app.server.js` via `yarn build:server`.
- SSR route validation is currently disabled and returns -1 in `api/hooks/config.js`; update this when enabling SSR per route.

41
.github/instructions/testing.instructions.md vendored
View File

@@ -1,41 +0,0 @@
---
name: Testing
description: Playwright test conventions, fixtures, and visual regression.
applyTo: "tests/**"
---
# Testing
- Playwright for API tests (`tests/api/`), E2E tests (`tests/e2e/`), mobile tests (`tests/e2e-mobile/`), and Visual Regression tests (`tests/e2e-visual/`). Config in `playwright.config.ts`.
- Self-test after code changes: run only affected spec files (`npx playwright test tests/e2e/filename.spec.ts` or `-g "test name"`), not a full test suite run – saves time.
- Always coordinate test adjustments with the user: do not fix broken tests to match buggy frontend or vice versa. When tests fail, first clarify whether the test or the code is wrong.
## BrowserSync Workaround
BrowserSync keeps a WebSocket open permanently, preventing `networkidle` and `load` from resolving. All fixture files override `page.goto()` and `page.reload()` to use `waitUntil: "domcontentloaded"` by default. Always use `domcontentloaded` for navigation waits.
## Fixtures & Helpers
- `tests/e2e/fixtures.ts` – Shared fixtures (`authedPage`, `testUser`) and helpers (`waitForSpaReady`, `navigateToRoute`, `clickSpaLink`).
- `tests/e2e-visual/fixtures.ts` – Visual test helpers (`waitForVisualReady`, `hideDynamicContent`, `prepareForScreenshot`, `expectScreenshot`, `getDynamicMasks`).
- `tests/e2e-mobile/fixtures.ts` – Mobile helpers (`openHamburgerMenu`, `isMobileViewport`, `isTabletViewport`, `isBelowLg`).
- `tests/api/fixtures.ts` – API fixtures (`api`, `authedApi`, `accessToken`).
- `tests/api/helpers/` – API test utilities (`test-user.ts`, `admin-api.ts`, `maildev.ts`).
- `tests/fixtures/test-constants.ts` – Central constants (`TEST_USER`, `ADMIN_TOKEN`, `API_BASE`).
## Visual Regression Tests
- Visual regression tests live in `tests/e2e-visual/` with separate Playwright projects (`visual-desktop`, `visual-iphonese`, `visual-ipad`).
- Run: `yarn test:visual`. Update baselines: `yarn test:visual:update`.
- Screenshots are stored in `tests/e2e-visual/__screenshots__/{projectName}/` and MUST be committed to the repo.
- Tolerance: `maxDiffPixelRatio: 0.02` (2%) for cross-OS/hardware rendering differences.
- Always call `prepareForScreenshot(page)` before `expectScreenshot()`.
- Use `waitForVisualReady(page)` instead of `waitForSpaReady()` – it additionally waits for skeleton loaders and CSS settling.
- Dynamic content: `hideDynamicContent(page)` disables BrowserSync overlay and animations; `getDynamicMasks(page)` returns locators for non-deterministic elements.
- For AI review of screenshots, run `./scripts/export-visual-screenshots.sh`.
## API Tests
- API tests use `tests/api/fixtures.ts` with `api` (unauthenticated) and `authedApi` (with Bearer token) fixtures.
- Helpers: `ensureTestUser()` (`tests/api/helpers/test-user.ts`), Admin API (`tests/api/helpers/admin-api.ts`), MailDev (`tests/api/helpers/maildev.ts`).
- After hook changes, run only affected API tests: `npx playwright test tests/api/filename.spec.ts`.

48
.github/migration/README.md vendored
View File

@@ -1,48 +0,0 @@
# Migration: PhyProof-Patterns → Starter-Template
> Übernahme generischer Patterns aus `wm-phytolab/phyproof-shop-tibi-2025` in `cms/tibi-svelte-starter`.
**Erstellt:** 2026-02-25
**Quelle:** `/WM_Dev/src/gitbase.de/wm-phytolab/phyproof-shop-tibi-2025`
---
## Pakete & Reihenfolge
| # | Paket | Status | Abhängig von | Dateien |
|---|-------|--------|-------------|---------|
| 1 | [Foundation](paket-1-foundation.md) | ✅ | — | requestsStore, serverBuildInfo, formContext, clickOutside, utils, store, types |
| 2 | [Build-System](paket-2-build-system.md) | ✅ | Paket 1 | writeBuildInfo, esbuild-wrapper, ES-targets, Sentry tunnel, SPA-rewrites, versionCheck |
| 3 | [Toast + Loading](paket-3-toast-loading.md) | ⬜ | Paket 1 | toast.ts, ToastContainer, LoadingBar, Portal |
| 4 | [API-Layer](paket-4-api-layer.md) | ⬜ | 1, 2, 3 | api.ts Rewrite (fetch, dedup, loading, version-check) |
| 5 | [SSR Caching](paket-5-ssr-caching.md) | ⬜ | — | ssr.yml, ssr-server.js, utils.js, clear_cache.js, get_read.js |
| 6 | [Widgets + Nav](paket-6-widgets-navigation.md) | ⬜ | 1, 3, 4 | Button, Form, Input, Select, SearchableSelect, MedialibImage, Pagination, Carousel, Tooltip, DebugFooterInfo, navigation.ts |
**Hinweis:** Paket 5 (SSR) ist Backend-only und kann parallel zu den Frontend-Paketen umgesetzt werden.
---
## Parallelisierung
```
Paket 1 (Foundation) ──→ Paket 2 (Build) ──→ Paket 4 (API) ──→ Paket 6 (Widgets)
└──→ Paket 3 (Toast) ──┘
Paket 5 (SSR) ────────── (unabhängig, jederzeit) ──────────────┘
```
---
## Bewusst nicht übernommen
| Feature | Grund |
|---------|-------|
| `auth.ts` | Zu komplex als Default — pro Projekt entscheiden |
| Pagebuilder | Block-Registry ist immer projektspezifisch |
| Video Tours | Nischig — als separates Tool |
| i18n-Erweiterungen | Sprachsetup-abhängig |
| `validators.ts` | Passwort-Stärke zu spezifisch |
| Shop-Widgets | Cart, Filter, Pricing usw. |
| `@tailwindcss/typography` | Dependency nur bei Bedarf |
| `navigationData.ts` | CMS-Navigation braucht Collection-Setup |
| `CookieConsent.svelte` | GA-ID hardcoded, GDPR-Setup projektspezifisch |

57
AGENTS.md Normal file
View File

@@ -0,0 +1,57 @@
# 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 (Docker): `make docker-up && make docker-start`
- Start dev (local): `yarn dev`
- Build frontend: `yarn build`
- Build SSR bundle: `yarn build:server`
- Validate types: `yarn validate`
## Development workflow
- Default dev flow is Docker/Makefile: `make docker-up`, `make docker-start`, `make docker-logs`, `make docker-restart-frontend`.
- Local dev is secondary: `yarn dev` for watch, `yarn build` and `yarn build:server` for production builds.
- 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.
## 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.

30
.github/instructions/api-hooks.instructions.md → api/hooks/AGENTS.md
View File

@@ -1,18 +1,16 @@
---
name: API Hooks
description: tibi-server hook conventions and typing.
applyTo: "api/hooks/**"
---
# API Hooks (tibi-server) # API Hooks (tibi-server)
Hook files run inside the tibi-server Go runtime (goja).
## Conventions
- Wrap hook files in an IIFE: `;(function () { ... })()`. - Wrap hook files in an IIFE: `;(function () { ... })()`.
- Always return a HookResponse type or throw a HookException type. - Always return a HookResponse type or throw a HookException type.
- Use inline type casting with `/** @type {TypeName} */ (value)` and typed collection entries from `types/global.d.ts`. - Use inline type casting with `/** @type {TypeName} */ (value)` and typed collection entries from `types/global.d.ts`.
- Avoid `@ts-ignore`; use proper casting instead. - Avoid `@ts-ignore`; use proper casting instead.
- Use `const` and `let` instead of `var`. The tibi-server runtime supports modern JS declarations. - Use `const` and `let` instead of `var`. The tibi-server runtime supports modern JS declarations.
## context.filter – Go object quirk ## context.filter — Go object quirk
`context.filter` is not a regular JS object but a Go object. Even when empty, it is **truthy**. `context.filter` is not a regular JS object but a Go object. Even when empty, it is **truthy**.
Always check with `Object.keys()`: Always check with `Object.keys()`:
@@ -27,7 +25,7 @@ const requestedFilter =
: null : null
``` ```
**Never** use `context.filter || null` – it is always truthy and results in an empty filter object inside `$and`, which crashes the Go server. **Never** use `context.filter || null` — it is always truthy and results in an empty filter object inside `$and`, which crashes the Go server.
## Single-item vs. list retrieval ## Single-item vs. list retrieval
@@ -37,15 +35,13 @@ instead, only add authorization filters (e.g. `{ userId: userId }`).
## HookResponse fields for GET hooks ## HookResponse fields for GET hooks
- `filter` – MongoDB filter (list retrieval only, or to restrict single-item retrieval) - `filter` — MongoDB filter (list retrieval only, or to restrict single-item retrieval)
- `selector` – MongoDB projection (`{ fieldName: 0 }` to exclude, `{ fieldName: 1 }` to include) - `selector` — MongoDB projection (`{ fieldName: 0 }` to exclude, `{ fieldName: 1 }` to include)
- `offset`, `limit`, `sort` – pagination/sorting - `offset`, `limit`, `sort` — pagination/sorting
- `pipelineMod` – function to manipulate the aggregation pipeline - `pipelineMod` — function to manipulate the aggregation pipeline
## API Tests (Playwright) ## Related tests
- When creating or modifying collections/hooks: extend or create corresponding API tests in `tests/api/`. - When creating or modifying collections/hooks: extend or create corresponding API tests in `tests/api/`.
- Test files live under `tests/api/` and use fixtures from `tests/api/fixtures.ts`. - After hook changes, run only affected API tests: `npx playwright test tests/api/filename.spec.ts`.
- Helpers: `ensureTestUser()` (`tests/api/helpers/test-user.ts`), Admin API (`tests/api/helpers/admin-api.ts`), MailDev (`tests/api/helpers/maildev.ts`). - When tests fail, clarify whether the hook or the test needs adjustment — coordinate with the user.
- After hook changes, run only the affected API tests: `npx playwright test tests/api/filename.spec.ts`.
- When tests fail, clarify whether the hook or the test needs adjustment – coordinate with the user.

24
api/hooks/ssr/AGENTS.md Normal file
View File

@@ -0,0 +1,24 @@
# SSR and Caching
Server-side rendering via goja (Go JS runtime) with HTML caching.
## Request flow
1. `get_read.js` receives the request and calls `lib/ssr-server.js`.
2. `ssr-server.js` renders the Svelte app via `lib/app.server.js` and injects `window.__SSR_CACHE__`.
3. On the client, `lib/ssr.js` hydrates using the injected cache data.
4. Rendered HTML is stored in the `ssr` collection with dependency tracking.
## Build
- SSR bundle is built via `yarn build:server` and outputs to `lib/app.server.js`.
- The build uses `--banner:js='// @ts-nocheck'` to suppress type errors in the generated bundle.
## Cache invalidation
- `clear_cache.js` hook invalidates SSR cache entries based on collection dependencies.
- When content changes, only SSR entries that depend on the changed collection/entry are cleared.
## Route validation
SSR route validation is currently disabled and returns -1 in `config.js`; update this when enabling SSR per route.

34
.github/instructions/frontend.instructions.md → frontend/AGENTS.md
View File

@@ -1,14 +1,19 @@
---
name: Frontend
description: Svelte SPA structure and conventions.
applyTo: "frontend/src/**"
---
# Frontend # Frontend
- SPA entry point is `frontend/src/index.ts`, main component is `frontend/src/App.svelte`. Svelte 5 SPA bundled with esbuild and styled with Tailwind CSS 4.
- Component organization: `lib/` for utilities and stores, keep route components in a `routes/` folder when needed, `css/` for styles.
- Use PascalCase component names and export props at the top of the `<script>` tag; keep code/comments in English. ## Structure
- Entry point: `src/index.ts`, main component: `src/App.svelte`.
- `src/lib/` — utilities, stores, actions, API layer.
- `src/widgets/` — reusable UI components (Button, Input, Form, etc.).
- `src/css/` — global styles and Tailwind imports.
- Keep route components in a `src/routes/` folder when needed.
## Conventions
- PascalCase component names; export props at the top of `<script>` tag.
- Keep code and comments in English.
- SSR safety: guard browser-only code with `typeof window !== "undefined"`. - SSR safety: guard browser-only code with `typeof window !== "undefined"`.
- API behavior: PUT responses return only changed fields; filter by id uses `_id`; API requests reject non-2xx with `{ response, data }` and error payload in `error.data.error`. - API behavior: PUT responses return only changed fields; filter by id uses `_id`; API requests reject non-2xx with `{ response, data }` and error payload in `error.data.error`.
@@ -19,15 +24,14 @@ applyTo: "frontend/src/**"
## i18n ## i18n
- `svelte-i18n` is configured in `frontend/src/lib/i18n/index.ts` with lazy loading for locale files. - `svelte-i18n` is configured in `src/lib/i18n/index.ts` with lazy loading for locale files.
- Locale files live in `frontend/src/lib/i18n/locales/{lang}.json`. - Locale files live in `src/lib/i18n/locales/{lang}.json`.
- URL-based language routing: `/{lang}/...` (e.g. `/de/`, `/en/about`). - URL-based language routing: `/{lang}/...` (e.g. `/de/`, `/en/about`).
- Language utilities in `frontend/src/lib/i18n.ts`: `extractLanguageFromPath()`, `localizedPath()`, `getLanguageSwitchUrl()`. - Language utilities in `src/lib/i18n.ts`: `extractLanguageFromPath()`, `localizedPath()`, `getLanguageSwitchUrl()`.
- Use `$_("key")` from `svelte-i18n` for translations in components. - Use `$_("key")` from `svelte-i18n` for translations in components.
## E2E Tests (Playwright) ## Related tests
- When developing frontend features: extend or create corresponding E2E tests in `tests/e2e/`. - When developing frontend features: extend or create corresponding E2E tests in `tests/e2e/`.
- Shared fixtures and helpers in `tests/e2e/fixtures.ts`: `waitForSpaReady(page)`, `navigateToRoute(page, path)`, `clickSpaLink(page, selector)`, `authedPage` fixture.
- After frontend changes, run only the affected E2E tests: `npx playwright test tests/e2e/filename.spec.ts` or `-g "test name"`. - After frontend changes, run only the affected E2E tests: `npx playwright test tests/e2e/filename.spec.ts` or `-g "test name"`.
- When tests fail, clarify whether the frontend or the test needs adjustment – coordinate with the user. - When tests fail, clarify whether the frontend or the test needs adjustment — coordinate with the user.

42
tests/AGENTS.md Normal file
View File

@@ -0,0 +1,42 @@
# Testing
Playwright tests for E2E, API, mobile, and visual regression. Config in `playwright.config.ts`.
## Running tests
- All tests: `yarn test`
- E2E: `yarn test:e2e`
- API: `yarn test:api`
- Visual regression: `yarn test:visual`
- Single file: `npx playwright test tests/e2e/filename.spec.ts`
- Single test: `npx playwright test -g "test name"`
- After code changes, run only affected spec files — not the full suite.
## BrowserSync workaround
BrowserSync keeps a WebSocket open permanently, preventing `networkidle` and `load` from resolving. All fixture files override `page.goto()` and `page.reload()` to use `waitUntil: "domcontentloaded"` by default. Always use `domcontentloaded` for navigation waits.
## Fixtures & helpers
- `e2e/fixtures.ts` — Shared fixtures (`authedPage`, `testUser`) and helpers (`waitForSpaReady`, `navigateToRoute`, `clickSpaLink`).
- `e2e-visual/fixtures.ts` — Visual test helpers (`waitForVisualReady`, `hideDynamicContent`, `prepareForScreenshot`, `expectScreenshot`, `getDynamicMasks`).
- `e2e-mobile/fixtures.ts` — Mobile helpers (`openHamburgerMenu`, `isMobileViewport`, `isTabletViewport`, `isBelowLg`).
- `api/fixtures.ts` — API fixtures (`api`, `authedApi`, `accessToken`).
- `api/helpers/` — API test utilities (`test-user.ts`, `admin-api.ts`, `maildev.ts`).
- `fixtures/test-constants.ts` — Central constants (`TEST_USER`, `ADMIN_TOKEN`, `API_BASE`).
## Visual regression
- Tests in `e2e-visual/` with separate Playwright projects (`visual-desktop`, `visual-iphonese`, `visual-ipad`).
- Run: `yarn test:visual`. Update baselines: `yarn test:visual:update`.
- Screenshots in `e2e-visual/__screenshots__/{projectName}/` — MUST be committed.
- Tolerance: `maxDiffPixelRatio: 0.02` (2%) for cross-OS/hardware rendering differences.
- Always call `prepareForScreenshot(page)` before `expectScreenshot()`.
- Use `waitForVisualReady(page)` instead of `waitForSpaReady()` — it additionally waits for skeleton loaders and CSS settling.
- Dynamic content: `hideDynamicContent(page)` disables BrowserSync overlay and animations; `getDynamicMasks(page)` returns locators for non-deterministic elements.
- For AI review of screenshots, run `./scripts/export-visual-screenshots.sh`.
## Coordination
- Always coordinate test adjustments with the user: do not fix broken tests to match buggy frontend or vice versa.
- When tests fail, first clarify whether the test or the code is wrong.