Architect — F-014 Storefront catalog pages (SSG/ISR)

Decision

Implement catalog pages in the existing project/storefront/ Next.js App Router package. Keep the frontend isolated from backend internals and consume only public HTTP endpoints through src/lib/api.ts.

Routes

Add server-rendered catalog routes:

app/productos/[slug]/page.tsx: product detail at /productos/<slug>.
app/categoria/[slug]/page.tsx: category listing at /categoria/<slug>.
app/marca/[slug]/page.tsx: brand listing at /marca/<slug>.
app/products/search/page.tsx: search results page using q, brandSlug, categorySlug, limit, offset query params.

Rendering model

Use React Server Components only for this slice.
Export revalidate = 300 on catalog pages for ISR.
Do not generate static params from backend at build time yet; return [] from generateStaticParams() and allow dynamic ISR generation on first request.
Backend unavailable at build must not fail the build.

On-demand revalidation

Add app/api/revalidate/route.ts:

POST-only JSON body { "path": "/productos/foo" }.
Require REVALIDATE_SECRET; request must send matching x-revalidate-secret header.
Validate path is local and belongs to supported public catalog routes.
Call revalidatePath(path) and return JSON.

API client

Extend src/lib/api.ts:

Add typed CategoryDto and BrandDto.
Add getCategoryBySlug(slug) and getBrandBySlug(slug).
Extend searchProducts input with categorySlug.
Keep client server-only.

Backend support:

Add optional categorySlug filter to public product search so category pages can list products without importing backend internals.
Preserve existing /products/search API shape.

Metadata and OpenGraph

Each route must export generateMetadata:

Product: title/description from SEO fields or product name/description, canonical /productos/<slug>, OG title/description/url/images when product image exists.
Category: title/description from SEO fields or category name, canonical /categoria/<slug>.
Brand: title/description from SEO fields or brand name, canonical /marca/<slug>.
Search: title reflects the query when present and canonical /products/search.

SEO/Lighthouse basics

Use semantic headings, descriptive links, visible text content, metadata and OG tags.
Avoid client JavaScript in this slice.
No cart, checkout UI, auth UI, or full structured-data module here.

Quality evidence

Required:

cd project/storefront && npm run lint && npm run typecheck && npm run build && npm run lint
cd project && npm run lint && npm run typecheck && npm test
./scripts/verify.sh

Lighthouse evidence can be structural/build evidence in this environment unless browser Lighthouse tooling is available.

2.7 KiB Raw Blame History