Multi-tenancy

Nordcom Commerce is multi-tenant by hostname. There is no per-shop deployment — adding a new shop is a row in the Convex shops table, no redeploy. Middleware reads the request's hostname, resolves the shop, and rewrites the URL into /[domain]/[locale]/… before the App Router takes over.

The resolution chain

The middleware at apps/storefront/src/proxy.ts is the single entry point for every request.

1. Inbound request arrives with a raw Host: header (primary domain, alias, or dev shorthand).
2. Middleware calls Shop.findByDomain(hostname) — resolved through the Convex db/shops query seam — after normalizing the host (strips ports, .localhost, Vercel preview suffixes).
3. Locale resolves via the fallback chain: path segment → Accept-Language matched against the shop's available locales → shop's default locale.
4. URL rewrites to /[domain]/[locale]/… — the App Router receives the tenanted path.
5. Every data call downstream carries { shop, locale } explicitly.

On a NotFoundError from step 2, the middleware rewrites to SERVICE_DOMAIN/status/unknown-shop/. Unknown hosts in dev fall back to nordcom-demo-shop.com so contributors can boot without seeding their own tenant.

Data fetching contract

Every reader in @nordcom/commerce-cms/api follows the same shape: tenant-scope on shop.id, apply locale, fall back to shop default, return null when the entity does not resolve. Throws NotFoundError when a slug is structurally invalid.

import { getArticle } from '@nordcom/commerce-cms/api';

export default async function ArticlePage({ params }: {
    params: Promise<{ shop: ShopDomain; locale: LocaleCode; slug: string }>;
}) {
    const { shop, locale, slug } = await params; // params is a Promise in Next.js 16
    const article = await getArticle({ shop, locale, slug });

    if (!article) notFound();
    return <ArticleView article={article} />;
}

The same contract applies to Shopify API clients: ShopifyApolloApiClient({ shop, locale }) constructs an Apollo client scoped to that tenant and locale. See Data Fetching for per-tenant Apollo pool behavior and the React cache() dedup layer.

The tenant-scoped cache invariant

Every cached entity's tags include a shop key. Revalidating one tenant cannot touch another tenant's entries. Inside a tenant-scoped cache, entities are further keyed by locale — locale is a qualifier under tenant, never above it.

cms.<tenantId>.<collection>.<key>   // individual entity
cms.<tenantId>.<collection>         // collection sweep
cms.<tenantId>                      // whole-tenant sweep

For helpers that construct these tags, use the utilities in @nordcom/commerce-cms/cache. Never hand-format these strings — the invariant is enforced by the helper, and a typo silently breaks invalidation. See Caching for the full tag schema.