Shopfront — Frontend (Nx monorepo)

An Nx monorepo (React + Vite + TypeScript) for the Shopfront ecommerce app. One application, and one self-contained library per module — each lib owns only its module's components / stores / controllers / apis / hooks / routes / types.

The backend is a separate repository: ../ecommerce-backend (Django + GraphQL + SQLite + Argon2id). See its own README.

Workspace layout

ecommerce-frontend/
├── apps/
│   ├── ecommerce-app/          # the application shell (main, router, providers, layout)
│   └── ecommerce-app-e2e/      # Playwright end-to-end tests
├── libs/
│   ├── shared/                 # design-system, api-client, i18n, types, utils, observability
│   ├── auth/                   # auth module (stores, apis, controllers, components, routes)
│   ├── items/                  # catalog module (canonical ItemsStore, catalog, detail)
│   ├── cart/                   # cart module
│   ├── orders/                 # checkout + orders module
│   └── mock-backend/           # in-browser fixture data layer (offline/demo fallback)
├── tsconfig.base.json          # path aliases: @ecommerce/*, and @shared/* @auth/* …
├── nx.json  eslint.config.js  tailwind.config.js  codegen.ts

Each lib is a real Nx project (project.json, own lint/test/build), imported via path aliases (@shared/*, @auth/*, @items/*, @cart/*, @orders/*, @backend/*).

Run it

# 1) Backend (separate repo) — first time
cd ../ecommerce-backend && ./.venv/bin/python manage.py runserver 8000

# 2) Frontend (this repo)
yarn install
yarn dev            # nx serve ecommerce-app → http://localhost:5173 (proxies /graphql → :8000)
# or run both at once:
yarn dev:all

Demo safety (fixtures)

libs/shared/src/api-client/apiConfig.ts has a top-level switch:

const USE_REAL_API = true   // true → real API (+ auto-fallback to fixtures on failure)
                            // false → offline fixtures (~300ms), no backend needed

So a backend hiccup never breaks a demo. Force offline mode with VITE_USE_REAL_API=false yarn dev.

Scripts (Nx targets)

yarn build      # nx build ecommerce-app
yarn test       # nx run-many -t test   (all projects)
yarn lint       # nx run-many -t lint
yarn e2e        # nx e2e ecommerce-app-e2e
yarn verify     # lint + test + build across the workspace
yarn schema:export && yarn codegen   # regenerate GraphQL types from the backend SDL

Useful Nx commands: npx nx graph, npx nx show projects, npx nx test auth, npx nx lint items.

Status (last run)

• nx run-many -t lint test build → 8 projects green
• 37 unit/integration tests, 2 Playwright e2e pass
• Dev app :5173 → Django :8000 verified (real GraphQL)