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-seocomponents) - Enforced client/server boundaries for hooks and UI components
- Implemented mock API fallback in
lib/api.tsto 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.tsxwith 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.tswith 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_URLto 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
paramsin 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