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

✨ feat: enhance project setup and architecture documentation

Browse Source 
- Updated `tibi-project-setup` skill to clarify project initialization goals and steps.
- Improved `tibi-ssr-caching` skill to detail SSR architecture, responsibilities, and caching mechanisms.
- Introduced `website-solution-architecture` skill for translating website requirements into coherent solutions.
- Refined `AGENTS.md` to provide a structured roadmap for project development phases.
- Added `ADMIN_ASSET_VERSION` to `api/config.yml.env` for asset versioning.
- Updated SSR request flow and cache invalidation logic in `api/hooks/ssr/AGENTS.md`.
- Removed obsolete `esbuild.config.admin.js` and integrated asset versioning into the main `esbuild.config.js`.
- Adjusted `api/collections/content.yml` to utilize asset versioning for admin scripts.
This commit is contained in:
Sebastian Frank
2026-05-12 20:01:22 +00:00
parent 4a604bab0b
commit 491f495c66
23 changed files with 3189 additions and 225 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+87 -16
View File
@@ -10,28 +10,44 @@ Tibi CMS starter template — Svelte 5 SPA with esbuild, SSR via goja, and Playw
- **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.
## Project bootstrap
Before treating this repo as a real project, replace the starter placeholders and initial project values.
Derive these values from the real repo path `gitbase.de/ORG/REPO`:
- `PROJECT_NAME`: use the repo name in kebab-case.
- `TIBI_NAMESPACE`: set it equal to `PROJECT_NAME`, i.e. use the same repo name in kebab-case.
- `STAGING_PATH`: use the real repo org and repo name, i.e. `/staging/ORG/REPO/dev`.
- `.env`: replace `PROJECT_NAME=__PROJECT_NAME__`, `TIBI_NAMESPACE=__TIBI_NAMESPACE__`, `STAGING_PATH=/staging/__ORG__/__PROJECT__/dev`, `STAGING_URL=https://dev-__PROJECT_NAME__.staging.testversion.online`, and `CODING_URL=https://__PROJECT_NAME__.code.testversion.online`.
- `api/config.yml`: replace `namespace: __TIBI_NAMESPACE__`.
- `frontend/.htaccess`: replace both `__TIBI_NAMESPACE__` proxy targets.
- `api/hooks/config-client.js`: replace `https://__PROJECT__.code.testversion.online` with the real origin URL.
- `package.json`: adapt starter metadata like `name` and `repository` when creating the real project repo.
- Docker and local URLs derive from `.env`, so `PROJECT_NAME` and `TIBI_NAMESPACE` must be correct before `make docker-up`.
- Recommended check: search for remaining starter placeholders with `rg '__[A-Z0-9_]+__' .`.
## 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`
- Start dev: `make docker-up` or `make docker-start`
- Restart frontend watcher/dev-server: `make docker-restart-frontend`
- View logs: `make docker-logs` or `make docker-logs-X`
- Start with mock data: set `MOCK=1` in `.env`, then use the normal Docker start command
- Build frontend/admin bundle: `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.
- **Mock mode**: Set `MOCK=1` to run the frontend without a tibi-server. API calls are served from JSON files in `frontend/mocking/`. Missing mock endpoints return 404.
- Frontend code is automatically rebuilt by the watcher/BrowserSync stack; backend hooks reload 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).
@@ -57,20 +73,18 @@ Tibi CMS starter template — Svelte 5 SPA with esbuild, SSR via goja, and Playw
## 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`.
- Auth via `Token` header with `ADMIN_TOKEN` from `api/config.yml.env` when a configured token with the required permissions is needed.
## Required secrets and credentials
| Secret | Location | Purpose |
| --- | --- | --- |
| `ADMIN_TOKEN` | `api/config.yml.env` | API admin auth + tibi-admin login |
| `ADMIN_TOKEN` | `api/config.yml.env` | Access token for configured API/admin permissions |
| `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.
@@ -123,16 +137,73 @@ Project-specific types (e.g. `Ssr`, `ApiOptions`, `ContentEntry`) live in `types
### Architecture skills (loaded on demand)
These skills provide deep-dive documentation. Use them when working on the respective area:
These skills provide deep-dive documentation. Use them by phase instead of treating them as an unsorted reference list.
#### 1. Project start and solution design
| Skill | When to use |
| --- | --- |
| `tibi-project-setup` | Setting up a new project from scratch |
| `website-solution-architecture` | Translating website requirements into a complete solution across content, admin, SSR, and workflows |
| `security-hardening-and-token-strategy` | Applying secure token, secret, permission, and hook-capability decisions |
#### 2. Content model and editor UX
| 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 |
| `nova-pagebuilder-modeling` | Designing editor-friendly block systems, nested block schemas, and pagebuilder UX |
| `nova-navigation-modeling` | Modeling multilingual header/footer/navigation trees with current Nova navigation features |
| `admin-ui-config` | Configuring collection admin views, field widgets, layouts |
| `media-seo-publishing` | Modeling media, SEO, and publication workflows for website projects |
| `permissions-and-editor-workflows` | Designing safe editorial permissions, field rules, and role-aware admin workflows |
| `nova-ai-editor-features` | Applying AI and LLM capabilities in editor workflows and media authoring responsibly |
#### 3. Backend behavior and integrations
| Skill | When to use |
| --- | --- |
| `tibi-hook-authoring` | Writing or debugging server-side hooks |
| `tibi-actions-and-forms` | Building contact forms, workflow endpoints, and other action-based website features |
| `scheduled-jobs-and-automation` | Building cron-based background tasks, cleanups, reports, and sync workflows |
| `realtime-and-live-workflows` | Designing SSE-based live updates, notifications, previews, and status workflows |
#### 4. Frontend runtime and delivery
| Skill | When to use |
| --- | --- |
| `frontend-architecture` | Routing, state management, Svelte 5 patterns, API layer, error handling |
| `tibi-ssr-caching` | SSR rendering and cache invalidation |
| `tibi-project-setup` | Setting up a new project from scratch |
### Quickstart roadmap for a new website
Use this order when building a project from scratch on this starter:
1. Foundation.
Start with `tibi-project-setup` until Docker, URLs, build, and validate are green.
2. Solution design.
Use `website-solution-architecture` first, then `security-hardening-and-token-strategy`, before writing components or hooks.
3. Content and admin model.
Use the skills from **Content model and editor UX** to shape `api/collections/content.yml`, `api/collections/navigation.yml`, reusable domain collections, and Nova authoring UX.
4. Frontend and runtime.
Use `frontend-architecture` plus `nova-pagebuilder-modeling` when wiring routing, i18n, content loading, `frontend/src/blocks/BlockRenderer.svelte`, and shared types.
5. Backend behavior.
Use the skills from **Backend behavior and integrations** for hooks, forms/actions, jobs, and realtime only where the project actually needs them.
6. SSR and publishing.
Use `tibi-ssr-caching` once routes, navigation, and page-critical data are defined, and use `media-seo-publishing` plus `permissions-and-editor-workflows` where publication, SEO, and editorial restrictions matter.
7. Optional AI editor features.
Use `nova-ai-editor-features` only when there is a concrete editorial workflow for it.
8. Final verification.
Confirm public site, admin authoring, pagebuilder rendering, navigation/media resolution, forms/actions, and SSR all work, then run `yarn build`, `yarn build:server`, and `yarn validate`.
For one-off tasks, use the phase tables above as the lookup index instead of maintaining a second skill matrix here.
### Tailwind CSS 4 canonical classes