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 /api/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 /api/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 Strapi data.

All pages are SSR (useFetch/useSeoMeta); nothing blog-related is client-only-rendered.

Server (Nitro) endpoints — the only Strapi client

frontend/server/api/:

Endpoint	Purpose
GET /api/articles	Paginated list (page query, PAGE_SIZE=12), optional category slug filter. Proxies to Strapi with ARTICLE_SUMMARY_QUERY. Returns Paginated<ArticleSummary>.
GET /api/articles/:slug	One article: fetches from Strapi with ARTICLE_DETAIL_QUERY (includes content + createdBy), converts Markdown to HTML, builds the meta description, derives the author byline. 400 without a slug, 404 if not found. Returns Article.
GET /api/categories	All categories (name + slug only), sorted by name.
GET /api/categories/:slug	One category by slug. 400/404 as above.

This is the single point of contact with Strapi (CLAUDE.md rule): pages never call $fetch against Strapi directly, and NUXT_STRAPI_URL / any Strapi token never reach the client. If you add a view that needs new data, add the endpoint here and type its return in frontend/shared/types/blog.ts — don't scatter Strapi calls into components.

Supporting utilities

• frontend/server/utils/strapi.ts
  • strapiFetch<T>(path) — server-only fetch against runtimeConfig.strapiUrl, with optional Bearer token; wraps failures as a 502 so internal details never leak to the client.
  • 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 — Strapi query-string builders kept intentionally minimal (only the fields each page actually renders): ARTICLE_SUMMARY_QUERY, ARTICLE_DETAIL_QUERY, PAGE_SIZE, pagination(), pageParam().
• frontend/app/composables/useMediaUrl.ts — the only composable; turns a Strapi image object into an absolute browser URL by prefixing runtimeConfig.public.strapiUrl 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)

StrapiImage   { url, alternativeText, width, height }
Category      { name, slug }
ArticleSummary{ title, slug, publishedAt, cover: StrapiImage | 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.

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.