56 lines
2.1 KiB
Markdown
56 lines
2.1 KiB
Markdown
---
|
|
name: tibi-ssr-caching
|
|
description: Implement and debug server-side rendering with goja (Go JS runtime) and dependency-based HTML cache invalidation for tibi-server. Use when working on SSR hooks, cache clearing, or the server-side Svelte rendering pipeline.
|
|
---
|
|
|
|
# tibi-ssr-caching
|
|
|
|
## SSR request flow
|
|
|
|
1. `ssr/get_read.js` receives a page request and calls `lib/ssr-server.js`.
|
|
2. `ssr-server.js` loads `lib/app.server.js` (the Svelte SSR bundle) and renders the page.
|
|
3. During rendering, API calls are tracked as **dependencies** (collection + entry ID).
|
|
4. The rendered HTML + dependencies are stored in the `ssr` collection.
|
|
5. On the client, `lib/ssr.js` hydrates using `window.__SSR_CACHE__` injected by the server.
|
|
|
|
## Building the SSR bundle
|
|
|
|
```bash
|
|
yarn build:server
|
|
```
|
|
|
|
- Output: `api/hooks/lib/app.server.js`
|
|
- Uses `babel.config.server.json` to transform async/await to generators (goja doesn't support async).
|
|
- Add `--banner:js='// @ts-nocheck'` to suppress type errors in the generated bundle.
|
|
|
|
## Dependency-based cache invalidation
|
|
|
|
When content changes, `clear_cache.js` only invalidates SSR entries that depend on the changed collection/entry:
|
|
|
|
```js
|
|
// Each SSR cache entry stores its dependencies:
|
|
{
|
|
url: "/some-page",
|
|
html: "...",
|
|
dependencies: [
|
|
{ collection: "content", id: "abc123" },
|
|
{ collection: "medialib", id: "def456" }
|
|
]
|
|
}
|
|
```
|
|
|
|
The hook queries the `ssr` collection for entries whose `dependencies` array matches the changed collection (and optionally entry ID), then deletes only those cached pages.
|
|
|
|
## SSR route validation
|
|
|
|
Route validation in `config.js` controls which paths get SSR treatment. Return:
|
|
|
|
- A positive number to enable SSR for that route
|
|
- `-1` to disable SSR (current default in the starter template)
|
|
|
|
## Common pitfalls
|
|
|
|
- **goja has no async/await**: The babel server config transforms these, but avoid top-level await.
|
|
- **No browser globals**: `window`, `document`, `localStorage` etc. don't exist in goja. Guard with `typeof window !== "undefined"`.
|
|
- **SSR cache can go stale**: Always ensure `clear_cache.js` covers any new collection that affects rendered output.
|