Project Document

Comprehensive overview of what’s been built, why, and how to operate it.

A. Tech Stack

  • Framework: Next.js 15 (App Router) with React 19
  • Styling: Tailwind CSS 4, custom theme in app/globals.css
  • UI/Animations: Radix UI, framer-motion
  • State: Zustand for cart, custom toast
  • SEO: Next.js Metadata API

B. Key Decisions

  • Removed incompatible libraries targeting React 18 (e.g., Remix, SvelteKit, Vaul)
  • Migrated to server-side Metadata API (no next-seo components)
  • Enforced client/server boundaries for hooks and UI components
  • Implemented mock API fallback in lib/api.ts to run without a backend

C. Routes & Pages

  • Home: / with hero, featured categories/products, category previews, reviews
  • Product list: /products; Product details: /products/[slug] with reviews, related
  • Categories: /category; Category details: /category/[slug]
  • Blog list: /blog; Blog details: /blog/[slug]
  • Static: /about, /contact
  • New: /project-document (this page)

D. Components (Highlights)

  • Layout: components/layout-wrapper.tsx with Navbar, Footer, PageTransition, Toaster, CartDrawer
  • UI: Product grid/cards, details, filters; Blog hero/grid/card; Category/product sections
  • Accessibility/UX: Loading skeletons, not-found pages, animations, sticky navbar

E. Data & API

  • Single API module: lib/api.ts with typed endpoints and mock data
  • Products/Categories/Blog/Reviews endpoints with retry and graceful fallbacks
  • Added mock support for: /products/:id/reviews, /blog, /blog/:slug
  • Set NEXT_PUBLIC_API_URL to use a real backend; otherwise mocks are used

F. Known Fixes

  • Resolved npm peer dependency issues by aligning with React 19/Next 15
  • Fixed “Invalid hook call” sources by moving hooks to client components
  • Updated dynamic routes to await params in Next 15
  • Hardened against null API responses (reviews, blog posts)
  • Removed extra top padding under navbar

G. Environment & Commands

  • Dev: npm run dev; Build: npm run build; Start: npm run start
  • Tailwind theme in app/globals.css
  • Typescript config: tsconfig.json

H. Next Steps

  • Connect real API and map IDs/slugs consistently
  • Expand reviews system with forms and moderation
  • Enable analytics and monitoring