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/skills/tibi-project-setup/SKILL.md
+81 -14
View File
@@ -13,6 +13,8 @@ Use this skill when:
- Onboarding into a freshly cloned starter project where placeholders haven't been replaced yet
- The user asks to "set up", "initialize", or "bootstrap" a new tibi project
Goal: a new website project should end up as a **fully working tibi-server + tibi-admin-nova project**, not just a renamed starter clone.
## Prerequisites
- Code-Server environment at `*.code.testversion.online`
@@ -34,23 +36,25 @@ git remote rename origin template
**Verify:** `git remote -v` shows `template` pointing to the starter and optionally `origin` pointing to the new repo.
## Step 2 — Replace placeholders
## Step 2 — Replace placeholders and starter values
Three placeholders must be replaced in the correct files:
Replace the starter placeholders and starter-derived values in the correct files:
| Placeholder | Files | Format | Example |
| -------------------- | ---------------------------------------------- | --------------------------------------------------------- | ------------ |
| `__PROJECT_NAME__` | `.env` | kebab-case (used for URLs, Docker containers, subdomains) | `my-project` |
| `__TIBI_NAMESPACE__` | `.env`, `api/config.yml`, `frontend/.htaccess` | snake_case (used as DB prefix and in API URLs) | `my_project` |
| `__TIBI_NAMESPACE__` | `.env`, `api/config.yml`, `frontend/.htaccess` | kebab-case, same value as `PROJECT_NAME` | `my-project` |
```sh
PROJECT=my-project # kebab-case
NAMESPACE=my_project # snake_case
NAMESPACE=my-project # same kebab-case value as PROJECT
sed -i "s/__PROJECT_NAME__/$PROJECT/g" .env
sed -i "s/__TIBI_NAMESPACE__/$NAMESPACE/g" .env api/config.yml frontend/.htaccess
```
Also update the starter-derived values that are not placeholder tokens anymore, especially `STAGING_PATH`, `STAGING_URL`, `CODING_URL`, `api/hooks/config-client.js`, and starter metadata in `package.json`.
**Verify each replacement:**
```sh
@@ -62,14 +66,14 @@ grep -n '__PROJECT_NAME__\|__TIBI_NAMESPACE__' .env api/config.yml frontend/.hta
```dotenv
PROJECT_NAME=my-project
TIBI_NAMESPACE=my_project
TIBI_NAMESPACE=my-project
CODING_URL=https://my-project.code.testversion.online
STAGING_URL=https://dev-my-project.staging.testversion.online
```
### Common mistakes
- **Mixing formats**: `PROJECT` must be kebab-case (`my-project`), `NAMESPACE` must be snake_case (`my_project`). Never use kebab-case where snake_case is expected or vice versa.
- **Using different values for `PROJECT` and `NAMESPACE`**: In this starter, `TIBI_NAMESPACE` must match `PROJECT_NAME` and use the same kebab-case value.
- **Forgetting `frontend/.htaccess`**: Contains the namespace for API rewrite rules. If missed, API calls from the frontend will fail silently.
- **Forgetting `api/config.yml`**: First line is `namespace: __TIBI_NAMESPACE__`. If not replaced, tibi-server won't start correctly.
@@ -77,29 +81,30 @@ STAGING_URL=https://dev-my-project.staging.testversion.online
The page title is set dynamically via `<svelte:head>` in `frontend/src/App.svelte`. The demo app uses the constant `SITE_NAME` for this. In a new project, `App.svelte` is typically rewritten completely — just make sure `<svelte:head>` with a `<title>` is present. SSR automatically injects it via the `<!--HEAD-->` placeholder in `spa.html`.
Also verify that SSR still renders meaningful page content and not just the shell after the rewrite.
## Step 4 — Admin token
`api/config.yml.env` ships with a default `ADMIN_TOKEN`. For production projects, generate a secure one:
```sh
echo "ADMIN_TOKEN=$(openssl rand -hex 20)" > api/config.yml.env
token=$(openssl rand -hex 20) && sed -i "s/^ADMIN_TOKEN=.*/ADMIN_TOKEN=$token/" api/config.yml.env
```
**Verify:** `cat api/config.yml.env` shows a 40-character hex token.
This updates only `ADMIN_TOKEN` and keeps the other env keys in the file intact.
**Verify:** `cat api/config.yml.env` shows a 40-character hex token while preserving entries such as `ADMIN_ASSET_VERSION`.
## Step 5 — Install, upgrade, and start
```sh
yarn install
yarn upgrade # Update all deps to latest versions within package.json ranges
make docker-up # Start stack in background
# or
make docker-start # Start stack in foreground (CTRL-C to stop)
```
`yarn upgrade` is safe here because the project is freshly cloned and nothing is running yet. The template's `yarn.lock` may be months old — upgrading ensures you start with the latest compatible (semver-range) versions.
**Do NOT run `yarn upgrade` on an existing, running project without testing.** Even patch-level updates can introduce regressions. For running projects, upgrade targeted packages with `yarn upgrade <package>` and verify with `yarn validate` + `yarn build`.
Do not blindly run a full dependency upgrade as part of project bootstrap unless the task explicitly includes dependency maintenance. First get the starter running as-is, then upgrade intentionally and validate.
**Verify containers are running:**
@@ -154,6 +159,17 @@ For a real project, remove or replace the demo files:
Then adapt `frontend/src/App.svelte` (header, footer, content loading) to your own data model.
But do not delete starter structures blindly. For a serious project build-out, first decide which parts remain useful foundations:
- SSR pipeline
- i18n route model
- pagebuilder-based content collection
- navigation collection
- media library and image handling
- tests / tours as scaffolding
The goal is not "delete the demo". The goal is "reshape the starter into a project architecture that editors can use productively".
**Decision guide:**
- **Keep demo content** if you want to use it as a reference while building your own components.
@@ -164,8 +180,59 @@ Then adapt `frontend/src/App.svelte` (header, footer, content loading) to your o
```sh
yarn build # Frontend bundle for modern browsers
yarn build:server # SSR bundle (for tibi-server goja hooks)
yarn build # Frontend + admin module
yarn validate # TypeScript + Svelte checks (must show 0 errors and 0 warnings)
```
**All four commands must succeed with exit code 0 before the project is considered set up.**
**These commands must succeed before the project is considered set up.**
## Step 10 — Shape the project for real editor workflows
For a complete website on this starter, setup is not done when Docker runs. It is done when the project has a coherent content/admin model.
Inspect and adapt at least these areas:
- `api/collections/content.yml`: page types, block schema, SEO, i18n, pagebuilder config
- `api/collections/navigation.yml`: header/footer structure and editor UX
- `frontend/src/blocks/`: real block set for the website, not just demo showcase blocks
- `frontend/src/blocks/BlockRenderer.svelte`: final block registry
- `types/global.d.ts`: actual project data model
- `frontend/src/App.svelte`: final shell, content-loading, SSR-safe behavior
For Nova specifically, use current capabilities where they improve the website build process:
- `preview` for readable row, breadcrumb, and foreign-key display
- `sidebar` groups for publication/SEO/settings
- `containerProps.layout` for usable forms
- `dependsOn` for block-specific fields
- `drillDown` for complex arrays
- `pagebuilder` for heterogeneous page content
- `subNavigation`, `singleton`, `viewHint`, and foreign previews where appropriate
For tibi-server specifically, decide early whether the site also needs:
- `actions:` for forms, newsletter, calculators, imports, or webhooks
- publication-aware SSR invalidation
- field-level permissions
- AI/LLM integration for admin/editor workflows
## Step 11 — Functional verification for a real website project
After the first project shaping pass, verify more than just TypeScript:
```sh
yarn build
yarn build:server
yarn validate
```
Then also verify:
- the public site loads via the website URL
- the Nova admin loads via the admin URL
- pages can be created and edited in admin
- pagebuilder blocks are usable in admin
- SSR renders real page content, not only the shell
- navigation and media references render correctly
- forms/actions work if the project uses them
If the goal is "LLM can build a complete website automatically", the project setup skill must lead to a fully functional content/admin/runtime stack, not merely a placeholder replacement.