website/CONTEXT.md

Balout Pastry — Website (setup context)

Public storefront for شیرینی‌فروشی بلوط. React + Vite SPA that browses products and places orders via the NestJS API. Design matched to shirinibalout.com.

Repo: https://git.meshkee.com/BaloutPastry/website.git
API repo: https://git.meshkee.com/BaloutPastry/backend.git
Dashboards (customer login / account): https://git.meshkee.com/BaloutPastry/dashboards.git

Stack

• React 19 + TypeScript + Vite 8
• React Router 7
• Lucide icons
• Cart in localStorage (balout.cart)
• Auth session cookie balout.auth (shared with customer dashboard on *.baloutpastry.com)
• API client: src/lib/api.ts → VITE_API_BASE_URL

Prerequisites

• Node.js 20+ (LTS recommended)
• npm
• Running Backend API on port 3100
• Optional: customer dashboard on 5173 for login / account (SSO via cookie or hash handoff)

Setup on a new device

git clone https://git.meshkee.com/BaloutPastry/website.git
cd website

cp .env.example .env
# Edit if API / customer app URLs differ

npm install
npm run dev

Open http://localhost:5174 (or http://baloutpastry.com:5174 with local DNS).

Local hosts (recommended)

Add to /etc/hosts:

127.0.0.1 baloutpastry.com www.baloutpastry.com
127.0.0.1 admin.baloutpastry.com customer.baloutpastry.com

Then:

App	URL
Website	http://baloutpastry.com:5174
Customer dashboard	http://customer.baloutpastry.com:5173
Admin dashboard	http://admin.baloutpastry.com:5173
API	http://localhost:3100/api/v1

Backend CORS_ORIGIN must include the website origin(s), e.g.
http://baloutpastry.com:5174,http://www.baloutpastry.com:5174,http://localhost:5174

Backend must be up

From the backend repo:

cp .env.example .env
npm install
npm run db:up
npx prisma migrate deploy
npm run start:dev   # http://localhost:3100/api/v1

Scripts

Command	What it does
npm run dev	Vite dev server → http://localhost:5174
npm run build	Typecheck + production build → dist/
npm run preview	Serve production build locally
npm run lint	Oxlint

Environment

Variable	Required	Default	Notes
VITE_API_BASE_URL	no	http://localhost:3100/api/v1	Must include /api/v1
VITE_CUSTOMER_APP_URL	no	http://customer.baloutpastry.com:5173	Login / profile redirects
VITE_COOKIE_DOMAIN	no	.baloutpastry.com (when on that host)	Shared auth cookie domain

Copy from .env.example. Do not commit .env.

After changing env vars, restart npm run dev.

App routes

Path	Page
/	Home (hero, categories, featured products)
/products	Product list + filters
/products/:slugOrId	Category by slug or product detail by id
/quick-info	Quick info
/about-us	About
/contact-us	Contact

Cart drawer and toasts are global (not separate routes). Checkout / login hand off to the customer dashboard when needed.

Auth / cart notes

• Guest browsing and cart work without login
• Session cookie: balout.auth (also accepts #balout_auth=… hash handoff from customer app)
• Access token sent as Authorization: Bearer … on authenticated API calls
• Cart key: balout.cart in localStorage; change event balout:cart-change
• Prices are integer تومان

Project layout

src/
  App.tsx                 Routes + shell (Header / Footer / Cart / Toast)
  pages/                  Home, products, about, contact, quick-info
  components/             Header, Footer, CartDrawer, ProductCard, …
  lib/
    api.ts                HTTP client + catalog / checkout helpers
    auth.ts               Cookie session + customer-app redirects
    cart.ts               localStorage cart
    types.ts              Shared types + formatPriceFa
    ids.ts                cuid vs category-slug detection

Production build

cp .env.example .env   # set real API + customer app URLs
npm ci
npm run build
# Serve dist/ behind nginx/Caddy, or:
npm run preview

Set VITE_* before npm run build (they are baked into the bundle).

Common issues

Symptom	Likely cause
Empty catalog / fetch errors	Backend not running, or wrong VITE_API_BASE_URL
CORS errors in browser	Backend CORS_ORIGIN missing website origin (port 5174)
Port already in use	Another process on 5174 (strictPort: true)
Login redirect fails	Customer dashboard down, or wrong VITE_CUSTOMER_APP_URL
Auth not shared across apps	Missing /etc/hosts + VITE_COOKIE_DOMAIN=.baloutpastry.com

Related

• Backend setup: clone BaloutPastry/backend and read CONTEXT.md
• Customer / admin UI: clone BaloutPastry/dashboards and read CONTEXT.md