ianshaloom
cc15338ad9
Completes the first milestone of The Pet Loft ecommerce platform: - apps/storefront: full customer-facing Next.js app with HeroUI (cart, checkout, orders, wishlist, product detail, shop, search, auth) - convex/: serverless backend with schema, queries, mutations, actions, HTTP routes, Stripe/Shippo integrations, and co-located tests - packages/types, packages/utils, packages/convex: shared workspace packages Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
124 lines
3.6 KiB
Markdown
124 lines
3.6 KiB
Markdown
# The Pet Loft — Ecommerce Monorepo
|
|
|
|
A full-stack ecommerce platform for pet supplies built with Next.js, Convex,
|
|
Clerk, and Turborepo.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
ecommerce/
|
|
├── apps/
|
|
│ ├── storefront/ # Customer-facing store (Next.js + HeroUI) — port 3000
|
|
│ └── admin/ # Admin dashboard (Next.js + ShadCN) — port 3001
|
|
├── convex/ # Convex backend (schema, functions, tests)
|
|
├── packages/
|
|
│ ├── types/ # Shared TypeScript types (Product, Order, User...)
|
|
│ ├── utils/ # Shared helper functions (formatPrice, slugify...)
|
|
│ └── convex/ # Shared Convex client provider (@repo/convex)
|
|
├── docs/ # Convex reference docs + project documentation
|
|
├── package.json # Root workspace config
|
|
└── turbo.json # Turborepo pipeline config
|
|
```
|
|
|
|
For detailed documentation, see [`docs/project-documentation/`](./docs/project-documentation/).
|
|
|
|
## Getting Started
|
|
|
|
### 1. Install dependencies
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### 2. Set up Convex
|
|
|
|
1. Go to [convex.dev](https://convex.dev) and create a new project
|
|
2. Run `npx convex dev` from the root — this will prompt you to log in and
|
|
link your project
|
|
|
|
### 3. Set up Clerk
|
|
|
|
1. Go to [clerk.com](https://clerk.com) and create a new application
|
|
2. In the Clerk Dashboard, create a JWT Template named `convex` (do **not**
|
|
rename it)
|
|
3. Copy your Publishable Key, Secret Key, and the JWT Issuer URL
|
|
4. Set `CLERK_JWT_ISSUER_DOMAIN` in the Convex Dashboard environment variables
|
|
|
|
### 4. Configure environment variables
|
|
|
|
Copy the example env files and fill in your credentials:
|
|
|
|
```bash
|
|
cp apps/storefront/.env.example apps/storefront/.env.local
|
|
cp apps/admin/.env.example apps/admin/.env.local
|
|
```
|
|
|
|
### 5. Run the development servers
|
|
|
|
```bash
|
|
# Terminal 1 — Convex backend
|
|
npx convex dev
|
|
|
|
# Terminal 2 — Both Next.js apps
|
|
npm run dev
|
|
```
|
|
|
|
- **Storefront** → http://localhost:3000
|
|
- **Admin** → http://localhost:3001
|
|
|
|
## Packages
|
|
|
|
### `@repo/types`
|
|
All shared TypeScript types used across both apps and the Convex backend.
|
|
|
|
```ts
|
|
import type { Product, Order, User } from "@repo/types";
|
|
```
|
|
|
|
### `@repo/utils`
|
|
Shared utility functions.
|
|
|
|
```ts
|
|
import { formatPrice, slugify, formatDate } from "@repo/utils";
|
|
|
|
formatPrice(1999) // → "$19.99"
|
|
slugify("Hello World!") // → "hello-world"
|
|
```
|
|
|
|
### `@repo/convex`
|
|
Shared Convex + Clerk provider. Both apps wrap their layout with this.
|
|
|
|
```tsx
|
|
import { ConvexClientProvider } from "@repo/convex";
|
|
```
|
|
|
|
## Authentication
|
|
|
|
This project uses **Clerk** for authentication and **Convex** for the backend.
|
|
|
|
- Clerk handles sign-in/sign-up UI and JWT tokens
|
|
- `ConvexProviderWithClerk` passes the JWT to the Convex backend
|
|
- Convex functions access the user identity via `ctx.auth.getUserIdentity()`
|
|
- Admin-only functions check the `role` field via `requireAdmin()`
|
|
- Clerk webhooks sync user changes to the Convex `users` table
|
|
|
|
## Scripts
|
|
|
|
| Script | What it does |
|
|
|--------|-------------|
|
|
| `npm run dev` | Run both apps in parallel via Turbo |
|
|
| `npm run dev:storefront` | Run only the storefront |
|
|
| `npm run dev:admin` | Run only the admin |
|
|
| `npm run build` | Build both apps |
|
|
| `npm run type-check` | TypeScript check across all workspaces |
|
|
| `npm run test:once` | Run all tests once |
|
|
| `npm run test` | Run tests in watch mode |
|
|
|
|
## Deployment
|
|
|
|
| App | Recommended Platform |
|
|
|-----|---------------------|
|
|
| Storefront | Vercel (root dir: `apps/storefront`) |
|
|
| Admin | Vercel (root dir: `apps/admin`) |
|
|
| Backend | Convex Cloud (`npx convex deploy`) |
|