{"id":51124786,"url":"https://github.com/viniarruda/react-ecommerce","last_synced_at":"2026-06-25T06:30:33.423Z","repository":{"id":39559057,"uuid":"171484595","full_name":"viniarruda/react-ecommerce","owner":"viniarruda","description":"E-commerce monorepo application using NextJs, NestJs, Design-System with Typescript","archived":false,"fork":false,"pushed_at":"2026-06-17T16:43:54.000Z","size":140327,"stargazers_count":229,"open_issues_count":10,"forks_count":65,"subscribers_count":10,"default_branch":"main","last_synced_at":"2026-06-17T18:19:17.144Z","etag":null,"topics":["design-system","ecommerce","enzyme","graphql","hacktoberfest","hooks","jest","lerna","monorepo","nestjs","nextjs","provider","react","react-native","redux","shop","shopping-cart","storybook","tests","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/viniarruda.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-02-19T14:06:15.000Z","updated_at":"2026-06-17T16:45:03.000Z","dependencies_parsed_at":"2024-10-30T12:44:45.867Z","dependency_job_id":null,"html_url":"https://github.com/viniarruda/react-ecommerce","commit_stats":null,"previous_names":["viniarruda/react-ecommerce"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/viniarruda/react-ecommerce","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viniarruda%2Freact-ecommerce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viniarruda%2Freact-ecommerce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viniarruda%2Freact-ecommerce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viniarruda%2Freact-ecommerce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/viniarruda","download_url":"https://codeload.github.com/viniarruda/react-ecommerce/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viniarruda%2Freact-ecommerce/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34763481,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["design-system","ecommerce","enzyme","graphql","hacktoberfest","hooks","jest","lerna","monorepo","nestjs","nextjs","provider","react","react-native","redux","shop","shopping-cart","storybook","tests","typescript"],"created_at":"2026-06-25T06:30:31.943Z","updated_at":"2026-06-25T06:30:33.415Z","avatar_url":"https://github.com/viniarruda.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React Ecommerce Boilerplate\n\n\u003e A production-ready, white-label e-commerce boilerplate built on a **Turborepo monorepo**. Clone it, configure your brand in one file, and deploy. Ships with a full storefront, admin panel, REST API, design system, and Storybook.\n\n\u003c!--\n  SCREENSHOTS\n  Run `pnpm dev:app`, then replace placeholders with real captures.\n  Recommended: `npx playwright screenshot http://localhost:3500 .github/screenshots/home.png`\n--\u003e\n\n![](.github/screenshots/home.png)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/screenshots/products.png\" width=\"32%\" alt=\"Products\" /\u003e\n  \u003cimg src=\".github/screenshots/pdp.png\" width=\"32%\" alt=\"Product Detail\" /\u003e\n  \u003cimg src=\".github/screenshots/admin.png\" width=\"32%\" alt=\"Admin Dashboard\" /\u003e\n\u003c/p\u003e\n\n---\n\n## ✦ What's included\n\n| Area | Details |\n|---|---|\n| **Storefront** | Home page, product listing with search/filter/sort, product detail with image gallery + variants + reviews, guest cart + authenticated cart, 3-step checkout, account area |\n| **Admin panel** | Dashboard with live stats, products CRUD + multi-image management, categories, orders with status updates, review moderation queue, user list |\n| **REST API** | NestJS — auth (login/register/JWT refresh), products, categories, cart, orders, reviews, users + addresses |\n| **Design System** | 30+ Tailwind v4 components in `@react-shop/design-system`, white-label CSS variables, dark mode |\n| **SDK** | `@react-shop/sdk` — fully typed Axios client + React Query hooks for every endpoint |\n| **White-label** | Edit `config/branding.ts` + `app/brand.css` → entire store re-themes with zero component changes |\n| **Dark mode** | Class-based, persisted to `localStorage`, no FOUC |\n| **Guest cart** | Add to cart without signing in; sign-in only required at checkout |\n| **Storybook** | All DS components documented with live controls |\n\n---\n\n## Tech Stack\n\n**Frontend**\n- [Next.js 14](https://nextjs.org/) — App Router, TypeScript, server components\n- [React 19](https://react.dev/)\n- [Tailwind CSS v4](https://tailwindcss.com/) — CSS-first config, `@theme` design tokens, CSS variables\n- [Syne](https://fonts.google.com/specimen/Syne) · [DM Sans](https://fonts.google.com/specimen/DM+Sans) · [Space Mono](https://fonts.google.com/specimen/Space+Mono)\n- [React Hook Form](https://react-hook-form.com/) + [Zod](https://zod.dev/)\n- [TanStack Query v5](https://tanstack.com/query)\n\n**Backend**\n- [NestJS](https://nestjs.com/) — modular REST API\n- [Prisma 7](https://www.prisma.io/) — ORM with full relation support\n- [PostgreSQL](https://www.postgresql.org/)\n- JWT auth — access token + refresh token flow\n\n**Tooling**\n- [Turborepo](https://turbo.build/) — monorepo task orchestration\n- [pnpm](https://pnpm.io/) — fast, disk-efficient package manager\n- [ESLint 9](https://eslint.org/) — flat config\n- [Storybook 8](https://storybook.js.org/)\n- [Docker Compose](https://docs.docker.com/compose/) — one-command PostgreSQL\n\n---\n\n## Project Structure\n\n```\nreact-ecommerce/\n├── apps/\n│   ├── web/                    # Next.js storefront + admin panel  (port 3500)\n│   │   ├── app/\n│   │   │   ├── (main)/         # Public routes — /, /products, /cart, /checkout …\n│   │   │   ├── (admin)/        # Admin routes — /admin, /admin/products …\n│   │   │   ├── (auth)/         # Auth routes — /login, /register\n│   │   │   ├── modules/        # Feature modules\n│   │   │   │   ├── products/   # Product list, detail, filters, image gallery\n│   │   │   │   ├── cart/       # Cart (guest + server)\n│   │   │   │   ├── checkout/   # Multi-step checkout flow\n│   │   │   │   ├── account/    # Profile + order history\n│   │   │   │   ├── admin/      # Admin screens + components\n│   │   │   │   ├── layout/     # Header, footer, theme toggle\n│   │   │   │   └── static/     # Policy pages\n│   │   │   └── providers/      # ThemeProvider, GuestCartProvider\n│   │   └── config/\n│   │       └── branding.ts     # ← single source of truth for branding\n│   ├── server/                 # NestJS REST API  (port 5001)\n│   │   └── prisma/\n│   │       ├── schema.prisma\n│   │       └── seed.ts\n│   └── storybook/              # Component docs  (port 6006)\n├── packages/\n│   ├── design-system/          # @react-shop/design-system\n│   ├── sdk/                    # @react-shop/sdk\n│   ├── eslint-config-custom/\n│   └── tsconfig/\n├── scripts/\n│   └── setup-client.ts         # Interactive white-label wizard\n└── docker-compose.yml\n```\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Node.js 18+**\n- **pnpm 8+** — `npm i -g pnpm`\n- **Docker** — for the PostgreSQL container\n\n### 1 · Install dependencies\n\n```bash\ngit clone https://github.com/your-username/react-ecommerce.git\ncd react-ecommerce\npnpm install\n```\n\n### 2 · Start the database\n\n```bash\ndocker compose up -d\n```\n\n### 3 · Configure environment\n\nThe defaults work out of the box with Docker Compose:\n\n```bash\ncp apps/server/.env.example apps/server/.env\n```\n\n```env\n# apps/server/.env\nPORT=5001\nNODE_ENV=development\nSECRET=dev-secret-change-in-production\nDATABASE_URL=postgresql://postgres:postgres@localhost:5432/react_ecommerce\n```\n\n### 4 · Run migrations + seed\n\n```bash\npnpm --filter @react-shop/api prisma:migrate   # apply schema\npnpm --filter @react-shop/api prisma:seed      # create admin + sample data\n```\n\n### 5 · Start the app\n\n```bash\npnpm dev:app\n```\n\n| Service | URL |\n|---|---|\n| 🛍 Storefront | http://localhost:3500 |\n| ⚙️ Admin panel | http://localhost:3500/admin |\n| 🔌 REST API | http://localhost:5001/api |\n| 📖 Storybook | http://localhost:6006 |\n\n---\n\n## Default Accounts\n\n| Role | Email | Password |\n|---|---|---|\n| **Admin** | `admin@ecommerce.com` | `admin123` |\n| **Customer** | `customer@example.com` | `customer123` |\n\n---\n\n## Storefront Pages\n\n| Route | Description |\n|---|---|\n| `/` | Home — editorial hero, featured products, categories, newsletter |\n| `/products` | Listing — search, category pills, sort dropdown |\n| `/products/[id]` | Detail — image gallery, variant selector, reviews, add-to-cart |\n| `/categories` | Category grid |\n| `/new-arrivals` | 12 newest products |\n| `/deals` | Products with a compare/sale price |\n| `/cart` | Cart — guest (localStorage) or server (authenticated) |\n| `/checkout` | Address → review → confirmation |\n| `/account` | Profile (requires login) |\n| `/account/orders` | Order history (requires login) |\n| `/contact` | Contact form |\n| `/faq` | Accordion FAQ |\n| `/shipping` | Shipping info |\n| `/returns` | Returns \u0026 refunds policy |\n| `/privacy` | Privacy policy |\n| `/terms` | Terms of service |\n\n## Admin Panel Pages\n\n| Route | Description |\n|---|---|\n| `/admin` | Dashboard — revenue, orders, products, pending reviews |\n| `/admin/products` | Product CRUD — create/edit modal with multi-image management |\n| `/admin/categories` | Category CRUD |\n| `/admin/orders` | All orders — inline status update |\n| `/admin/orders/[id]` | Order detail + cancel |\n| `/admin/reviews` | Moderation queue — approve / reject |\n| `/admin/users` | User list with role badges |\n\n---\n\n## REST API Reference\n\nBase URL: `http://localhost:5001/api`\n\n\u003cdetails\u003e\n\u003csummary\u003eAuth\u003c/summary\u003e\n\n| Method | Endpoint | Auth | Description |\n|---|---|---|---|\n| `POST` | `/auth/login` | — | Login → `{ user, accessToken, refreshToken }` |\n| `POST` | `/auth/register` | — | Register → `{ user, accessToken, refreshToken }` |\n| `GET` | `/users/me` | ✓ | Current user profile |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eProducts\u003c/summary\u003e\n\n| Method | Endpoint | Auth | Description |\n|---|---|---|---|\n| `GET` | `/products` | — | List all products |\n| `GET` | `/products/:id` | — | Product detail |\n| `POST` | `/products` | ✓ | Create product (with images) |\n| `PUT` | `/products/:id` | ✓ | Update product |\n| `DELETE` | `/products/:id` | ✓ | Delete product |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCart\u003c/summary\u003e\n\n| Method | Endpoint | Auth | Description |\n|---|---|---|---|\n| `GET` | `/cart` | ✓ | Get cart |\n| `POST` | `/cart/items` | ✓ | Add item |\n| `PUT` | `/cart/items/:id` | ✓ | Update quantity |\n| `DELETE` | `/cart/items/:id` | ✓ | Remove item |\n| `DELETE` | `/cart` | ✓ | Clear cart |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eOrders\u003c/summary\u003e\n\n| Method | Endpoint | Auth | Description |\n|---|---|---|---|\n| `GET` | `/orders` | ✓ | User's orders |\n| `POST` | `/orders` | ✓ | Create order |\n| `GET` | `/orders/:id` | ✓ | Order detail |\n| `PUT` | `/orders/:id/status` | ✓ | Update status |\n| `PUT` | `/orders/:id/cancel` | ✓ | Cancel order |\n| `GET` | `/orders/admin/all` | ✓ Admin | All orders |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eReviews\u003c/summary\u003e\n\n| Method | Endpoint | Auth | Description |\n|---|---|---|---|\n| `GET` | `/reviews/product/:id` | — | Product reviews |\n| `POST` | `/reviews` | ✓ | Submit review |\n| `GET` | `/reviews` | ✓ Admin | All reviews |\n| `PUT` | `/reviews/:id/moderate` | ✓ Admin | Approve / reject |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eAddresses\u003c/summary\u003e\n\n| Method | Endpoint | Auth | Description |\n|---|---|---|---|\n| `GET` | `/users/me/addresses` | ✓ | List addresses |\n| `POST` | `/users/me/addresses` | ✓ | Add address |\n\n\u003c/details\u003e\n\n---\n\n## White-Labelling\n\n### Option A — Interactive wizard\n\n```bash\npnpm setup:client\n```\n\nPrompts for store name, primary color, logo, and support email. Writes `config/branding.ts`, `app/brand.css`, and `.env.local`.\n\n### Option B — Manual\n\n**`apps/web/config/branding.ts`**\n\n```ts\nexport const branding: BrandingConfig = {\n  store: {\n    name: \"Acme Store\",\n    tagline: \"Quality goods, fair prices.\",\n    logoText: \"Acme Store\",\n    logoAbbrev: \"AC\",\n  },\n  contact: { email: \"hello@acme.com\" },\n  social: { instagram: \"https://instagram.com/acme\" },\n  features: { darkMode: true, newsletter: true, reviews: true },\n  theme: { primaryColor: \"#7c3aed\", primaryColorDark: \"#a78bfa\" },\n};\n```\n\n**`apps/web/app/brand.css`**\n\n```css\n:root {\n  --color-primary-600: #7c3aed; /* your brand color */\n  /* full primary-50 → primary-900 scale */\n}\n.dark {\n  --color-primary-600: #a78bfa;\n}\n```\n\nEvery `bg-primary-*`, `text-primary-*`, and `border-primary-*` utility resolves through these variables — no component edits needed.\n\n---\n\n## SDK Usage\n\n```tsx\nimport { SdkProvider, useProducts, useAddToCart } from \"@react-shop/sdk\";\n\n// Wrap once at the root\n\u003cSdkProvider apiConfig={{ baseURL: \"http://localhost:5001\" }}\u003e\n  \u003cApp /\u003e\n\u003c/SdkProvider\u003e\n\n// Use anywhere\nfunction ProductCard({ id }: { id: string }) {\n  const { data: product } = useProduct(id);\n  const { mutate: addToCart } = useAddToCart();\n\n  return (\n    \u003cbutton onClick={() =\u003e addToCart({ productId: id, quantity: 1 })}\u003e\n      Add to cart — {product?.title}\n    \u003c/button\u003e\n  );\n}\n```\n\nAvailable hooks: `useProducts`, `useProduct`, `useCategories`, `useCart`, `useAddToCart`, `useUpdateCartItem`, `useRemoveFromCart`, `useClearCart`, `useOrders`, `useOrder`, `useCreateOrder`, `useCancelOrder`, `useProductReviews`, `useAllReviews`, `useCreateReview`, `useModerateReview`, `useMe`, `useLogin`, `useRegister`, `useLogout`, `useAddresses`, `useCreateAddress`, `useAllUsers`.\n\n---\n\n## Available Scripts\n\n```bash\n# Development\npnpm dev:app          # API (5001) + storefront/admin (3500)\npnpm dev              # Everything including Storybook\n\n# Build \u0026 lint\npnpm build            # Build all packages\npnpm lint             # Lint all packages\n\n# Database (run from repo root)\npnpm --filter @react-shop/api prisma:migrate   # Apply migrations\npnpm --filter @react-shop/api prisma:seed      # Seed database\npnpm --filter @react-shop/api prisma:studio    # Prisma Studio GUI\npnpm --filter @react-shop/api prisma:reset     # Reset and re-seed\n\n# Docker\ndocker compose up -d   # Start PostgreSQL\ndocker compose down    # Stop PostgreSQL\n\n# White-label\npnpm setup:client      # Interactive brand setup wizard\n```\n\n---\n\n## Dark Mode\n\nDark mode is class-based (`.dark` on `\u003chtml\u003e`). The header includes a sun/moon toggle that persists to `localStorage`. A blocking inline script applies the class before first paint — no flash of light theme on dark-preference browsers.\n\nTo change the default, edit `apps/web/app/providers/ThemeProvider.tsx`.\n\n---\n\n## Environment Variables\n\n### `apps/server/.env`\n\n| Variable | Default | Required |\n|---|---|---|\n| `PORT` | `5001` | — |\n| `NODE_ENV` | `development` | — |\n| `SECRET` | — | **Yes** — JWT signing secret |\n| `DATABASE_URL` | — | **Yes** — PostgreSQL connection string |\n\n### `apps/web/.env.local` (optional)\n\n| Variable | Default | Description |\n|---|---|---|\n| `NEXT_PUBLIC_API_URL` | `http://localhost:5001` | API base URL |\n\n---\n\n## Contributing\n\n1. Fork the repo and create a feature branch\n2. `pnpm install` + `docker compose up -d`\n3. Run `pnpm dev:app` and make your changes\n4. `pnpm lint` must pass before submitting a PR\n5. Follow conventional commits: `feat:`, `fix:`, `docs:`, `chore:`\n\n---\n\n## License\n\nMIT — free to use, modify, and distribute for personal and commercial projects.\n\n---\n\n\u003cp align=\"center\"\u003e\n  Built as a white-label e-commerce boilerplate · MIT License\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviniarruda%2Freact-ecommerce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fviniarruda%2Freact-ecommerce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviniarruda%2Freact-ecommerce/lists"}