Instruction file imported from md-ahr/next-commerce (.cursor/rules/project-core.mdc). Copyright stays with the author.

Next Commerce — Core

Frontend-only ecommerce storefront. Third-party REST APIs. Feature-based architecture.

Stack

Next.js 16 · shadcn/ui · Tailwind v4 · TanStack Query · Zustand · Zod · Pino · Sentry · Vitest

Hard Rules

1. shadcn primitives — pnpm dlx shadcn@latest add <name> for components/ui/
2. Shadcn Space blocks/pages — MCP user-shadcnspace-mcp then pnpm dlx shadcn@latest add @shadcn-space/<name> — never hand-roll sections
3. Feature folders — business logic in features/<name>/, thin routes in app/
4. Validate — run pnpm validate before marking work complete
5. Tests — unit tests for all business logic in features/*/
6. Static images — Unsplash via @/lib/images; product images from DummyJSON
7. Color — 60-30-10 (background / card / primary) per docs/04-design-system.md
8. Section gaps — page-shell + page-stack + section-stack on every page
9. Responsive — sm 576 / md 768 / lg 1024 / xl 1200 only
10. Logging — Pino via @/lib/logger; console.* is forbidden
11. Sentry — captureException from @/lib/sentry for unexpected errors (no-op until DSN)

Docs

Patterns

Copy from features/_reference/ — do not invent new patterns.