Repository navigation
Releases
v0.8.0
Works with ecommerce-store-api v0.14.0 or later. The generated client matches API v0.14.0.
Added
- Shoppers can cancel eligible orders from the order details page. The Cancel order button requires the
cancel_own_ordersormanage_orderspermission and a cancellable status (pending_payment,payment_failed, orconfirmed). Needs an ecommerce-store-api withcancel_own_orders(API #408) (#149). - Home trust and shipping strip, plus Help footer links to Shipping, Privacy, and Contact pages (#153).
Changed
- Storefront order screens read the canonical order total field from the API (#162).
- Regenerated OpenAPI client for the shared API error body (
codeon errors is a non-exhaustive string with documented common values, including resource NOT_FOUND and SCREAMING auth codes). MSW auth and path not-found responses useUNAUTHORIZEDand*_NOT_FOUNDcodes. Shopper cancel for a missing order maps HTTP 404 /ORDER_NOT_FOUNDinstead of 422 (#154, #155). - Dependency updates: production dependencies including Next.js 16.4.3, react-hook-form 7.91.0, @hookform/resolvers 6.0.2, @tanstack/react-query 5.105.0, cn 0.5.1, and lucide-react 1.65.0 (#136, #156), Docker Node base image 26.13.0 (#157), and dev dependencies (#142, #158).
Fixed
- Destructive buttons use a solid red background with white label text so Cancel order and other danger actions meet WCAG AA color contrast (the soft tint style scored about 4:1).
- The checkout page shows its Checkout heading while the page is still loading (#161).
- The sitemap lists the Shipping and Privacy pages, and the Contact page is hidden from search engines until a real support email is set (#160).
- Storefront mobile layout and accessibility: larger tap targets, mobile drawer with cart/account/theme, readable order line items, cart and category chip overflow, stronger focus rings, and higher-contrast dark-mode secondary text (#151).
- Shopper date and times omit seconds, and checkout address fields no longer show sample-looking placeholders (#152).
- Checkout hides the page Checkout heading while confirmation is showing (#153).
- Account menu and drawer say Account (not Account Settings) to match sibling
/accountand/ordersroutes (#153). - Signed-in shoppers can change their password from the account menu, and account pages use shopper-facing wording and address labels (#147).
Upgrade notes
- Requires ecommerce-store-api 0.14.0 or later (shopper cancel, 404
ORDER_NOT_FOUND) (#149, #154, #155). - Set a real support email in
src/lib/shop.tsbefore going live. The Contact page reads this configuration and remains hidden from search engines while the placeholder support@example.com is in place (#153, #160).
Full changelog: v0.7.0...v0.8.0
v0.7.0
Works with ecommerce-store-api v0.10.0 or later. The generated client matches API v0.11.0.
Added
- Breaking (contributors): Pin npm 12.2.1 through
devEngines.packageManager(onFail: "error") as the single source for the npm version. The CI setup action and theDockerfiledeps and build stages install it frompackage.json, because no Node release bundles npm 12 yet.devEngines.runtime(node >=26.0.0) restores the Node guardrail, which npm 12 no longer enforces from rootengines. CONTRIBUTING gains an npm version policy (#129). - Node version guardrails:
.npmrcwithengine-strict=true, a Dependabotdockerentry that ignores Node majors, and a Node version policy in CONTRIBUTING (.nvmrcis the single source) (#128).
Changed
- MSW HTTP handlers import
httpandHttpResponsefrom themsw/httpentry point that msw 3 documents (passthroughstays on the rootmswexport, which is its only entry point) (#130). - CONTRIBUTING passes
prettier --checkand its Node version policy names every copy of the Node version (.nvmrc, theDockerfileFROMlines,engines.node,devEngines.runtime) and the pinned npm 12.2.1 (#130). - Breaking (contributors): Move to Node.js 26 LTS (npm 11.6+):
.nvmrc,engines, and theDockerfilebase image, now pinned tonode:26.12.1-alpine3.24by digest. The CI setup action usesactions/setup-nodev7.1.0 (#128). - Migrate to msw 3.0.3:
onUnhandledRequestis nowonUnhandledFrame, andpublic/mockServiceWorker.jsis regenerated (#124). - Dependency updates: production deps, including
@hookform/resolvers6.0.0 (#106, #120, #121); dev deps, including@babel/core8.0.7,globals17.13.0,hono,qs, and the dev-deps group (#109, #110, #113, #122, #123); transitivevite,fast-uri, andundici(#112, #114, #115); GitHub Actionsactions/cache6.1.0,actions/upload-artifact7.0.2, anddocker/login-action4.7.0 (#104, #105, #119). CITATION.cffis bumped to version 0.7.0, released 2026-10-28 (#131).- README: the placeholder Live demo section becomes Hosted demo: coming soon and points to the local ecommerce-platform stack (
docker compose up); local sign-in accounts link to the platform README Local demo sign-in section and the API SEEDING.md (#133).
Fixed
- The user menu trigger passes axe-core 4.14
label-content-name-mismatch: an sr-only label replaces itsaria-label, and the visible initial and email prefix arearia-hidden(#123).
Full changelog: v0.6.0...v0.7.0
v0.6.0
Storefront 0.6.0 adds a production Docker image published to GHCR (runtime API_BASE_URL / API_INTERNAL_BASE_URL), stops tracking generated next-env.d.ts, and tightens e2e stock headroom with typed refetch stubs and dash fallbacks.
Works with ecommerce-store-api v0.10.0 or later. The generated client matches API v0.11.0.
Added
- Production Docker image (Next.js standalone, port 3100) published to
ghcr.io/raouf-b-dev/ecommerce-store-webfor linux/amd64 and linux/arm64 on pushes to master andv*tags. Run-timeAPI_BASE_URL(browser) and server-onlyAPI_INTERNAL_BASE_URLoverride the build-time API origin, andNEXT_PUBLIC_ALLOW_LOOPBACK_ORIGIN/IMAGES_ALLOW_LOCAL_IPare explicit opt-ins, off by default (#100).
Changed
v0.5.0
Works with ecommerce-store-api v0.10.0 or later. The generated client matches v0.11.0.
Changed
- Breaking: production builds require
NEXT_PUBLIC_API_BASE_URLand fail without it instead of calling localhost; CI setshttps://api.test(#94). - Generated API client synced with API v0.11.0: order item SKU, customer name and shipping address may be null and render as
-; cart items carry a nullablesku(#94). - README storefront walkthrough image updated (#89).
- Dependency updates: production deps (TanStack Query, lucide-react, radix-ui, react-hook-form, zod) and dev deps (Playwright 1.64, Vitest 5.0.4, ESLint 10.12 and others) (#85, #86).
Fixed
v0.4.0
Works with ecommerce-store-api v0.10.0 or later. Checkout sends payment method CARD and an Idempotency-Key header; earlier API versions reject both. Deploy the API release before, or together with, this one.
Changed
- Breaking: checkout sends payment method
CARDand anIdempotency-Keyheader, so API v0.10.0 is required (#76, #77). - User profile menu overhaul: the header session links are now a dropdown user menu (#76).
- Tests use the production compiler, plus mobile Playwright projects (#74).
- Generated API client synced with API v0.10.0.
shadcnmoved to devDependencies with vulnerable subdependencies updated; Dependabot target and CI triggers cleaned up.- Agent check workflow for in-chat verification (#80) and slimmer agent guidance (#70).
- CI runs the full Playwright suite against a seeded API on pull requests into
masterand pushes tomaster, andCI Status Checkrequires it there. The production status spec runs on every pull request (#83). - README showcase screenshots and walkthrough regenerated for the user menu and contrast updates.
Fixed
- Add-to-cart errors are shown instead of silently creating a new cart (#75).
- No horizontal overflow on small checkout screens (#72).
- Custom address validation errors are shown (#71).
- Guest mobile nav shows on auth error; muted foreground and selected country combobox meet WCAG AA; checkout custom-address fade-in removed (#83).
v0.3.1
Patch 0.3.1.
- Image allow-list and error retry
- ESLint 10, Vitest 5
- Phase 14c is live API staging, not a hosted mock
v0.3.0
Release 0.3.0 (develop -> master).
Highlights
- Merchandising homepage with hero, categories and new arrivals
- Catalog moved to a dedicated route with a compact filter bar
- Explicit shipping costs, country combobox and order line images in cart/checkout
- Shop brand identity, theme tokens and product image placeholders
- Mock product images and one-click demo login
- Roadmap updates and dependency bumps
Works with ecommerce-store-api v0.9.0 or later (order line images use the new imageUrl field).
Full Changelog: v0.2.0...v0.3.0
Release v0.2.0
Release v0.2.0: Shopper storefront
First customer-complete storefront cut after the v0.1.0 foundation. Shoppers can register and sign in, browse the catalog, manage a cart, checkout against the mock payment adapter, poll order confirmation, and manage orders and addresses.
Targets ecommerce-store-api v0.8.0. Live Stripe and hosted staging are still out of scope. Playwright e2e still needs a live API; npm run dev:mock is the offline MSW preview.
Scope
| In this release | Not in this release |
|---|---|
| Auth, silent refresh, forced password change | Live Stripe Elements / real card capture |
| Catalog list/detail, filters, categories, SEO | Guest cart |
| Authenticated cart and checkout with order polling | Command palette / View Transitions |
| Orders history, account profile, address book | Hosted staging |
MSW dev:mock, release gate docs, visual showcase |
Shopper WebSocket feed |
| First-purchase empty states; Actions SHA pins; CONTRIBUTING / CoC / SECURITY |
Auth and session
- Login, register, in-memory access token, HttpOnly refresh cookie.
- Proactive / single-flight silent refresh.
- Forced password change for seeded customers (
mustChangePassword). - Customer chrome and route guards.
Catalog and SEO
- RSC catalog list and product detail against OpenAPI-typed client.
- Category pills, search, price bounds, sort; URL-driven filters.
- Declarative SEO foundation for catalog routes.
Cart and checkout
- Authenticated cart (
GET /v1/carts/current; 404 -> empty). - Checkout form with idempotency key and
?orderId=polling confirmation. - Pricing aligned with API money / shipping fields.
- Shared empty cart copy between cart and checkout.
Orders and account
- Own-order list and detail; filter-aware empty vs first-purchase empty.
GET /v1/users/meprofile and address book with shared empty shell.
Quality, preview, and docs
- Full shopper journey and a11y sweep; CI Playwright policy.
- Architecture boundary hardening and shopper contract consumption.
- MSW standalone preview (
npm run dev:mock). - Release gate runbook and visual showcase assets in README.
- Richer empty states / first-purchase guidance (catalog, cart, checkout, orders, addresses).
- GitHub Actions pinned to full commit SHAs; CONTRIBUTING, CODE_OF_CONDUCT, SECURITY reporting aligned with the API.
Stats
| Metric | Value |
|---|---|
| Since | v0.1.0 |
| Files changed | 342 |
| Insertions / deletions | +24,959 / -1,063 |
| Commits | 226 (209 excluding merges) |
Pull requests
| PR | Title |
|---|---|
| #31 | Empty states and repository hygiene |
| #29 | Visual showcase and hero media |
| #27 | Pricing alignment, MSW preview, and release docs |
| #26 | Harden architecture boundaries and shopper contracts |
| #25 | Quality sweep, e2e journey, and accessibility |
| #24 | Customer order history and account management |
| #20 | Checkout flow and order polling |
| #19 | Shopping cart and summary UI |
| #18 | Declarative SEO foundation |
| #17 | Catalog filtering and product detail |
| #16 | Forced password rotation and route guards |
| #15 | Authentication and proactive session refresh |
| #14 | Storefront shell, theme, and status diagnostics |
Full changelog: v0.1.0...v0.2.0
v0.1.0: Storefront Foundation and Agent Ecosystem
Release v0.1.0: Storefront Foundation and Agent Ecosystem
This cut establishes the Next.js 16 storefront foundation and locks the repository agent ecosystem, development conventions, and architecture decisions.
The application runs as a clean App Router shell on port 3100 using React 19, Tailwind CSS v4, strict TypeScript, and a pre-generated OpenAPI schema. Shopper authentication, catalog data fetching, cart management, and checkout flows remain intentionally out of scope for this milestone.
Scope
| In this release | Not in this release |
|---|---|
| Next.js 16 App Router shell, React 19, React Compiler, Cache Components | Shopper authentication, session context, token refresh |
| Tailwind CSS v4 setup, base shadcn primitives, Sonner | Catalog browsing, category filters, product detail pages |
| Vitest unit suite, Playwright smoke spec, ESLint flat config | Persistent cart state and line item mutations |
| Pre-generated OpenAPI TypeScript definitions (committed) | Checkout command, idempotency handling, order polling |
| Parallel CI workflow (lint, typecheck, unit, build, audit) and Dependabot | Customer profile and order history views |
| Canonical AGENT.md, project context, conventions, quality gates, six ADRs | Standalone MSW mock preview server |
| Port 3100 configuration and API CORS origin companion alignment | Full end-to-end multi-process CI test suites |
Core Application and Shell
- Scaffolded with Next.js 16.3.4 App Router, React 19, and Tailwind CSS v4 without modifying existing repository licenses or documentation.
- Configuration in
next.config.tsenablescacheComponents,reactCompiler, andtypedRoutes. - Baseline HTTP security headers configured in
next.config.ts:X-Content-Type-Options: nosniff,Referrer-Policy: strict-origin-when-cross-origin,X-Frame-Options: DENY, andContent-Security-Policy: frame-ancestors 'none'. - Strict
script-srcCSP is omitted for now to prevent breaking upcoming theme hydration scripts. - Base shadcn UI components installed (
button,input,card,alert,sonner) using the official compiledcnutility with@/lib/utilsre-export. - Standard document scrolling preserved. Fixed viewport overflow layouts are explicitly avoided.
Tooling, Quality Gates, and CI
- Node.js runtime set to 24 with matching
.nvmrcand package engines. - Strict TypeScript configuration with
noUncheckedIndexedAccessand path alias@/*mapping tosrc/*. - ESLint flat configuration mirroring the admin dashboard standard:
typescript-eslint,react-hooks(React 19),jsx-a11y, andconsistent-type-imports. - Vitest unit testing configured with jsdom, Testing Library, and an explicit path alias resolver.
- Playwright smoke test configured for port 3100 to verify that the home shell loads.
- GitHub Actions CI pipeline executing parallel jobs for
lint,typecheck,unit-tests,build, andaudit, reporting to a unifiedciaggregator. - Dependabot configuration for automated weekly npm and GitHub Actions dependency updates.
API Integration and Contract
- OpenAPI generator script ported from the admin dashboard to
scripts/generate-api-client.js. - Generated
schema.d.tscommitted directly to the repository so continuous integration builds offline without requiring a live backend. - Companion update applied to
ecommerce-store-api:http://localhost:3100added toCORS_ALLOWED_ORIGINSacross environment templates. - Environment bootstrap script in
scripts/generate-env.jstargeting.env.localand.secrets.
Agent Ecosystem and Governance
AGENT.mdestablishes canonical governance, order of authority, and the six non-negotiable project rules.- Thin adapter files (
AGENTS.md,CLAUDE.md,.cursor/rules/agent-rules.mdc) point directly toAGENT.mdwithout duplicating policy. - Comprehensive AI guidance committed under
docs/ai/:CONVENTIONS.md,GOVERNANCE-AND-QUALITY-GATES.md, andWORKFLOW-PLAYBOOK.md. - Six architectural decision records documented under
docs/architecture/adr/:- ADR-0001: RSC catalog, browser session client, and no BFF (Accepted).
- ADR-0002: In-memory access token with HttpOnly refresh cookie (Proposed).
- ADR-0003: Single-flight silent refresh (Proposed).
- ADR-0004: No guest cart (Proposed).
- ADR-0005: Checkout order polling (Proposed).
- ADR-0006: No proxy for auth or headers (Accepted).
- Delivery roadmap updated: Phase 0 and Phase 1 marked complete in
docs/ROADMAP.md.