davide
49c42ecc96
Strapi + Postgres are gone in favor of PocketBase: a single Go binary with embedded SQLite, built-in admin UI and per-collection API rules. No content existed yet, so this is a clean swap with no data migration. Collections and rules are defined as code in pocketbase/pb_migrations/ and applied automatically on first boot. Draft & Publish has no native PocketBase equivalent, so it's reproduced with a nullable `publishedAt` field enforced by listRule/viewRule, matching the old Strapi semantics. Routing flips: PocketBase's admin UI and REST/file API are hardwired to `/_/` and `/api/*` at the domain root (its own dashboard assets and API calls reference those paths directly, so a stripped path prefix like `/admin/*` would break them). `/api` is therefore reserved for PocketBase now, and the frontend's Nitro endpoints move to `/content/*` (frontend/server/routes/content/, not server/api/). A `/admin` vanity route in Nitro (not Caddy) redirects to `/_/`, so it works the same in dev, where Caddy isn't part of the stack, and in production. frontend/server/utils/strapi.ts becomes pocketbase.ts; queries.ts is rewritten for PocketBase's filter/sort/fields/expand query syntax. StrapiImage becomes MediaImage (no width/height — PocketBase file fields don't store dimensions, and the cover images already reserve their aspect ratio via CSS, so this is not a regression). docs/*.md, CLAUDE.md and README.md are updated in the same commit.
90 lines
5.5 KiB
Markdown
90 lines
5.5 KiB
Markdown
# Frontend (Nuxt)
|
|
|
|
## Pages
|
|
|
|
| Route | File | Behavior |
|
|
|---|---|---|
|
|
| `/` | `app/pages/index.vue` | Static hero/intro copy plus the single latest article, fetched via `/content/articles` (page 1), shown as a featured block. |
|
|
| `/blog` | `app/pages/blog/index.vue` | Paginated archive (`PAGE_SIZE = 12`), grid of `ArticleCard`, prev/next via `?page=`. |
|
|
| `/blog/[slug]` | `app/pages/blog/[slug].vue` | Full article: fetches `/content/articles/:slug`, renders the pre-converted `article.html`, SEO meta, canonical URL, Open Graph, JSON-LD `BlogPosting`, breadcrumb to its category. |
|
|
| `/category/[slug]` | `app/pages/category/[slug].vue` | Fetches the category by slug, then a paginated, category-filtered article list; 404s if the category doesn't exist. |
|
|
| `/come-difendersi-dal-corralito` | `app/pages/come-difendersi-dal-corralito.vue` | Fully static marketing page, no PocketBase data. |
|
|
|
|
All pages are SSR (`useFetch`/`useSeoMeta`); nothing blog-related is client-only-rendered.
|
|
|
|
## Server (Nitro) endpoints — the only PocketBase client
|
|
|
|
`frontend/server/routes/content/` (not `server/api/` — `/api/*` is reserved for PocketBase itself,
|
|
see [architecture.md](./architecture.md#path-routing-caddy); Nitro maps `server/routes/**` to the
|
|
matching path with no added prefix, unlike `server/api/**`):
|
|
|
|
| Endpoint | Purpose |
|
|
|---|---|
|
|
| `GET /content/articles` | Paginated list (`page` query, `PAGE_SIZE=12`), optional `category` slug filter. Queries PocketBase with `ARTICLE_SUMMARY_FIELDS`. Returns `Paginated<ArticleSummary>`. |
|
|
| `GET /content/articles/:slug` | One article: queries PocketBase with `ARTICLE_DETAIL_FIELDS` (includes `content` + `authorName`), converts Markdown to HTML, builds the meta description. 400 without a slug, 404 if not found or unpublished. Returns `Article`. |
|
|
| `GET /content/categories` | All categories (name + slug only), sorted by name. |
|
|
| `GET /content/categories/:slug` | One category by slug. 400/404 as above. |
|
|
|
|
This is the **single point of contact** with PocketBase (`CLAUDE.md` rule): pages never call
|
|
`$fetch` against PocketBase directly, and `NUXT_POCKETBASE_URL` never reaches the client. If you
|
|
add a view that needs new data, add the endpoint here (under `/content/*`) and type its return in
|
|
`frontend/shared/types/blog.ts` — don't scatter PocketBase calls into components.
|
|
|
|
`GET /admin` (`frontend/server/routes/admin.get.ts`) is the one other top-level server route: a
|
|
redirect to `${runtimeConfig.public.pocketbaseUrl}/_/`, PocketBase's own fixed dashboard path. It
|
|
lives in Nitro rather than Caddy so it works the same in dev (no Caddy in that stack) and
|
|
production — see [architecture.md](./architecture.md#path-routing-caddy).
|
|
|
|
## Supporting utilities
|
|
|
|
- `frontend/server/utils/pocketbase.ts`
|
|
- `pbFetch<T>(path)` — server-only fetch against `runtimeConfig.pocketbaseUrl`; wraps failures
|
|
as a 502 so internal details never leak to the client.
|
|
- `toMediaImage(collection, id, filename, alt)` — builds a PocketBase file URL
|
|
(`/api/files/{collection}/{id}/{filename}`) from a record; returns `null` when there's no
|
|
file.
|
|
- `renderMarkdown(source)` — `marked.parse()`, no sanitization (trusted, admin-only content).
|
|
- `summarise(source, maxLength = 155)` — strips Markdown syntax to build a plain-text meta
|
|
description, word-boundary clipped.
|
|
- `frontend/server/utils/queries.ts` — PocketBase query-string builders kept intentionally minimal
|
|
(only the fields each page actually renders): `ARTICLE_SUMMARY_FIELDS`, `ARTICLE_DETAIL_FIELDS`,
|
|
`PAGE_SIZE`, `pagination()`, `pageParam()`, `quote()` (escapes a value for PocketBase's `filter`
|
|
DSL).
|
|
- `frontend/app/composables/useMediaUrl.ts` — the only composable; turns a `MediaImage` into an
|
|
absolute browser URL by prefixing `runtimeConfig.public.pocketbaseUrl` unless already absolute.
|
|
- `frontend/shared/utils/site.ts` — site constants (`SITE_NAME`, `SITE_EMAIL`, `SOCIAL_LINKS`).
|
|
- `frontend/shared/utils/format.ts` — `it-IT` date formatting (`formatDate`, `formatDateTime`,
|
|
`isoDate`).
|
|
|
|
## Types (`frontend/shared/types/blog.ts`)
|
|
|
|
```
|
|
MediaImage { url, alt }
|
|
Category { name, slug }
|
|
ArticleSummary{ title, slug, publishedAt, cover: MediaImage | null, category: Category | null }
|
|
Article extends ArticleSummary { html, summary, author: string | null }
|
|
Paginated<T> { items: T[], page, pageCount, total }
|
|
```
|
|
|
|
`Article` is the detail shape (adds rendered HTML, meta summary, byline); `ArticleSummary` is what
|
|
listing pages use. `MediaImage` carries no width/height — PocketBase file fields don't store
|
|
dimensions, and the covers already reserve their aspect ratio via CSS (`aspect-ratio`), so no
|
|
layout shift results.
|
|
|
|
## Layout & shared components
|
|
|
|
- `app/layouts/default.vue` — the only layout: header (logo, tagline, nav), `<main id="main">`
|
|
slot, footer (contact email, nav, social links), with a skip-link for accessibility.
|
|
- `app/components/ArticleCard.vue` — listing-grid card: cover (lazy, omitted if none), category
|
|
kicker, title link, formatted date.
|
|
- `app/components/SocialIcon.vue` — inlines SVG brand marks from `simple-icons` at build time
|
|
(`?raw` imports) rather than bundling the whole icon set.
|
|
|
|
## SEO & accessibility
|
|
|
|
Every article page ships: unique `<title>`, meta description, canonical URL, Open Graph tags, and
|
|
JSON-LD `BlogPosting` structured data, with the article body already present in server-rendered
|
|
HTML (no client-only content). Accessibility requirements (focus visibility, labeled inputs,
|
|
meaningful alt text, descriptive links, full keyboard navigation) apply across all pages/components
|
|
— see `CLAUDE.md`.
|