Template

Files

T

apairon 958b45272d ✨ feat: enhance admin UI configuration and SSR handling

- Add support for number chip arrays and JSON editor in admin UI config.
- Introduce pagebuilder block registry for Svelte components in admin previews.
- Implement custom role names and a 3-layer cascade model for field-level permissions.
- Add CORS configuration hierarchy for better API security.
- Update project setup instructions for admin token and config management.
- Improve SSR 404 signaling with proper context handling in NotFound component.
- Refactor routing structure to separate NotFound page into its own route.

2026-05-12 23:20:31 +00:00

5.9 KiB

Raw Blame History

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/, esbuild, Tailwind CSS 4.
Backend: tibi-server with hooks in api/hooks/, collections in api/collections/.
SSR: goja (Go JS runtime) in api/hooks/ssr/.
Tests: Playwright in tests/ (API, E2E, mobile, visual).
Types: types/global.d.ts (project), tibi-types/ (read-only, from sibling repo).

Key constraints

Dev servers always run in Docker — never yarn dev or yarn start locally.
yarn is for standalone tasks: build, build:server, validate.
Bootstrap details (placeholder replacement, docker setup) → tibi-project-setup skill.
Build checklist for full website projects → .agents/BUILD_CHECKLIST.md.

Quick reference

Action	Command
Start dev stack	`make docker-up` or `make docker-start`
Restart frontend	`make docker-restart-frontend`
Logs	`make docker-logs`
Build frontend	`yarn build`
Build SSR	`yarn build:server`
Validate	`yarn validate`
Run all tests	`yarn test`
Run E2E tests	`yarn test:e2e`
Run API tests	`yarn test:api`

Testing notes

Tests read CODING_URL from .env. Ensure it serves both / and /api/....
After changes, run only affected specs: npx playwright test tests/e2e/filename.spec.ts.
CI runs yarn validate but not Playwright (needs MongoDB + tibi-server).

API access

Token header with ADMIN_TOKEN from api/config.yml.env.
Collection user: permissions apply to JWT auth (X-Auth-Token), not static Token:.
For write access via ADMIN_TOKEN, add "token:${ADMIN_TOKEN}": { methods: { post: true, put: true } } to the collection permissions.

Required secrets

Secret	Location	Purpose
`ADMIN_TOKEN`	`api/config.yml.env`	API/admin access token
`ADMIN_ASSET_VERSION`	`api/config.yml.env`	Cache-busting for admin bundle (auto-generated)
`.basic-auth-web`	project root (git-ignored)	BrowserSync basic auth
`.basic-auth-code`	project root (git-ignored)	Code-Server basic auth

Generated dev defaults in api/config.yml.env may be committed. Production values are overwritten in CI/CD via secrets.

Reference repositories (sibling repos)

Repo	Path	Key file
tibi-types	`../../cms/tibi-types`	`index.d.ts` (context types), `schemas/config/collection.schema.json`
tibi-server	`../../cms/tibi-server`	`docs/` (19 files: collections, hooks, auth, actions, SSE, jobs, etc.)
tibi-admin-nova	`../../cms/tibi-admin-nova`	`types/admin.d.ts` (all admin config types)

When to consult which repo

Collection YAML → tibi-server/docs/04-collections.md + tibi-types/schemas/config/collection.schema.json
Hooks → tibi-server/docs/06-hooks.md + tibi-types/index.d.ts
Admin UI config → tibi-admin-nova/types/admin.d.ts + tibi-admin-nova/api/collections/ (examples)
Permissions → tibi-server/docs/05-authentication.md
Actions/forms → tibi-server/docs/19-actions.md
Realtime/SSE → tibi-server/docs/07-realtime.md
Images/uploads → tibi-server/docs/08-file-upload-images.md
LLM integration → tibi-server/docs/09-llm-integration.md
Field-level permissions → tibi-server/docs/17-field-level-permissions.md

TypeScript

"include": ["frontend/src/**/*", "types/**/*", "./../../cms/tibi-types", "api/**/*"]

Domain types (entities, block props, API responses) be strict. any/[key: string]: any OK for inherently dynamic data (MongoDB filters, CMS fields, hook payloads).
No @ts-ignore — use /** @type {…} */ cast instead.
Zero warnings policy: always run yarn validate after changes; fix all warnings.
Svelte 5 with Runes: $props(), $state(), $derived(), $effect().

Tailwind CSS 4

Canonical v4 syntax — no v3 legacy classes:

v3	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!`

Architecture skills (loaded on demand)

Use these tables as the lookup index. Each skill is a deep-dive for its domain.

1. Project start and solution design

Skill	When
`tibi-project-setup`	Bootstrap a new project from scratch
`website-solution-architecture`	Translate requirements into collections, blocks, SSR, workflows
`security-hardening-and-token-strategy`	Token strategy, secrets, hook risk surfaces, CORS

2. Content model and editor UX

Skill	When
`content-authoring`	Add pages, block types, collections
`nova-pagebuilder-modeling`	Block schemas, preview, drillDown, dependsOn
`nova-navigation-modeling`	Header/footer trees, viewHint.navigation, declaredTrees
`admin-ui-config`	Field widgets, sidebar, layout, choices, foreign refs
`media-seo-publishing`	Image fields, alt/caption, SEO, publication model
`permissions-and-editor-workflows`	Field-level readonly/hidden, 3-layer cascade, custom roles
`nova-ai-editor-features`	AI-assisted alt text, LLM actions, token budgets

3. Backend behavior

Skill	When
`tibi-hook-authoring`	Write/debug server-side hooks (goja)
`tibi-actions-and-forms`	Contact forms, newsletter, webhooks, action endpoints
`scheduled-jobs-and-automation`	Cron tasks, cleanup, reports, sync
`realtime-and-live-workflows`	SSE channels, live notifications, preview refresh

4. Frontend and delivery

Skill	When
`frontend-architecture`	SPA router, stores, Svelte 5 patterns, API layer
`tibi-ssr-caching`	SSR rendering, cache invalidation, 404 signaling
`playwright-testing`	Deterministic seed data, API/E2E/admin/visual tests

5.9 KiB Raw Blame History