Getting started

The storefront is the customer-facing app of the platform — a Next.js App Router application that consumes the Baxela Laravel API for catalog browsing, product pages (with a specifications tab from the catalog attribute system), cart, checkout, payments, the blog, support tickets, and customer accounts.

Multilingual by default: English and Farsi (RTL) via next-intl, with locale routing under app/[locale]/. Theming runs on two axes: the brand palette comes from the admin's storefront_theme setting (resolved server-side), and shoppers toggle light/dark/system through a flash-free, cookie-driven mode switch — the whole UI is built on a design-token layer.

Checkout offers the payment methods returned by GET /payment/user/methods — hosted drivers like Stripe, PayPal, Adyen, Mercado Pago, Checkout.com and Razorpay redirect to the gateway and land back on the /payment/return page, which polls the order's payment status (crypto invoices via NowPayments settle when the funds land). Carts are promotion-aware — sale prices and badges render from the API-injected promotion objects — and a coupon code can be applied at checkout. Signed-in customers also get notifications: a realtime header bell (Laravel Reverb) with unread badge, an inbox under /profile/notifications, optional OS-level browser notifications, and device sessions with real sign-out. Real 404 pages render for unknown routes.

Tech stack

Concern	Choice
Runtime	Next.js (App Router), React 19, TypeScript
Styling	Tailwind CSS v4
i18n	next-intl (en / fa, RTL-ready)
API	fetch wrapper in lib/api (server + client helpers)

Running it

The storefront runs as part of the monorepo develop stack:

# from the repo root
cp .env.example .env
docker compose up -d
# → http://localhost:3000 (storefront), :5173 (admin), :8085 (API)

No host Node needed; the container installs dependencies on first start. To run on the host instead:

pnpm install
cp .env.example .env.local   # then adjust the API URL
pnpm dev

Environment variables

Variable	Description
NEXT_PUBLIC_API_BASE_URL	Browser-facing API base URL (e.g. http://localhost:8085/api/v1)
SERVER_API_BASE_URL	Optional override for server-side (SSR) fetches — used inside the compose networks to reach nginx directly

Commands

pnpm dev      # start the dev server (HMR)
pnpm build    # production build (.next/standalone — used by the prod Docker image)
pnpm start    # serve the production build
pnpm lint     # ESLint

Project structure

app/[locale]/        # locale-scoped routes (shop pages, auth, account)
lib/api/             # fetch wrapper + server-side helpers, shared types

Full conventions — route organization, API layer patterns, i18n rules — are documented in the app's AGENTS.md. Read it before contributing.

Deployment

The production image (infrastructure/docker/production/storefront/ in the monorepo) builds the standalone server and runs server.js behind the port published by docker-compose.prod.yml. NEXT_PUBLIC_API_BASE_URL is baked in at build time; SERVER_API_BASE_URL is provided at runtime. See Production stack.