Nordcom Commerce

The public, multi-tenant storefront. A single Next.js 16 app that serves an arbitrary number of shops, resolves the tenant from the request hostname, and renders catalog, cart, account, and CMS pages backed by Shopify and the Convex-native CMS.

For the canonical reference, see the README on GitHub.

In this section

Overview — this page
Routing — multi-tenant routing
Data Fetching — Shopify + CMS patterns
Webhooks — cache invalidation
Locales — i18n

Conventions

Errors

All thrown errors route through @nordcom/commerce-errors. Never throw new Error(...) in app or package code — if no existing class fits, add a new one (plus its *ErrorKind enum value and a getErrorFromCode case) in packages/errors/src/index.ts and throw that. Errors carry statusCode, code, and help URLs the platform relies on for status pages and observability. The only throw new Error(...) calls left in the storefront tree are inside test fixtures that deliberately simulate non-@nordcom/commerce-errors failures.

Loaders

Every multi-call-site data fetch goes through src/api/_loaders.ts, which wraps the underlying function in React's cache() so concurrent callers within a single server render resolve once. Always import Shop, Locale, Locales, Countries, Product, Collection, Blog, Article, Header, Footer, InfoBar, ProductMetadata, CollectionMetadata, and Pages from @/api/_loaders rather than from their source modules. See Data Fetching for the full pattern, cache-tag scheme, and notes on adding a new loader.

Styling

Tailwind-only. There are no .scss files in src/ and no sass dependency. Component-local styles live in *.module.css; shared utilities live in src/app/globals.css under @layer utilities.

Removed dependencies

The storefront previously pulled in several packages it no longer needs. Notable removals from this cleanup:

@payloadcms/* and payload — removed entirely with the Convex migration (see .specs/2026-05-30-convex-migration/). The storefront reads CMS content from the Convex cms/read functions and only imports the pure block/render layer from @nordcom/commerce-cms.
nprogress — superseded by nextjs-toploader. The toploader still pulls in nprogress as a transitive on the client; that's intentional and unchanged.
sass — removed alongside the migration of .module.scss and the Sass-based app.scss globals to plain CSS Modules and Tailwind @theme / @layer utilities.

Additional unused packages were removed in an audit-driven sweep; see the chore/storefront-cleanup commit history for the full list.

Overview