blog/docs/frontend.md

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; 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.

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.

Tests (tests/, repo root)

Kept at the repo root, not under frontend/, since e2e exercises the frontend and PocketBase together — but the tooling (Vitest/Playwright configs, node_modules) still lives in frontend/, the only npm project in the repo; the configs there just point include/testDir at ../tests/.

Three layers, all against real code (no mocked PocketBase):

• tests/unit/ — Vitest, environment: 'nuxt' (frontend/vitest.unit.config.ts). Pure functions in frontend/server/utils/* and frontend/shared/utils/* (imported directly, not via auto-import) plus components and composables via @nuxt/test-utils/runtime's mountSuspended.
• tests/integration/ — Vitest, node environment (frontend/vitest.integration.config.ts). @nuxt/test-utils/e2e's setup() builds and runs the real Nitro server, pointed (via nuxtConfig.runtimeConfig overrides) at a real ephemeral PocketBase instance from tests/support/pocketbase.ts. Exercises the actual /content/* and /admin routes.
• tests/e2e/ — Playwright (frontend/playwright.config.ts), a real browser against the built app (node .output/server/index.mjs) and another ephemeral PocketBase on a fixed port (needed so the Nuxt server's env and Playwright's globalSetup can reference each other without an async hand-off — see the comments in playwright.config.ts/tests/e2e/global-setup.ts).

tests/support/pocketbase.ts is the shared piece: it downloads the same pinned PocketBase binary pocketbase/Dockerfile uses (cached in .cache/pocketbase/ at the repo root, gitignored), starts it against the real pocketbase/pb_migrations/, and seeds it from tests/support/fixtures.ts — so integration and e2e tests run against the exact schema/rules that ship to production, not a hand-maintained approximation of them.