davide
47a8e7788f
Require CLAUDE.md changes to keep docs/ in sync with new features or architecture.
78 lines
4.5 KiB
Markdown
78 lines
4.5 KiB
Markdown
# 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`.
|