Deployment

Apps

Each Next.js app is independently deployable. Apps share workspace packages via workspace:* dependencies and consume the compiled dist/ of each.

See .env.example at the repo root for the full variable list.

Environment setup

Set the minimum required variables before starting any app:

cp .env.example .env
# required for the storefront and admin:
CONVEX_URL=https://<deployment>.convex.cloud
CONVEX_SERVER_SECRET=<openssl rand -hex 32 — must match the Convex deployment's value>
AUTH_SECRET=<random 32-byte hex>
SERVICE_DOMAIN=yourdomain.com

The SERVICE_DOMAIN variable is the root domain used for the error help URL pattern (https://${SERVICE_DOMAIN}/docs/errors/<code>/) and the unknown-shop redirect target.

Connecting a shop's domain

After creating a shop, operators connect its customer-facing domain on Settings → Domain in the admin. The screen shows the DNS records to add and verifies the connection:

• With VERCEL_TOKEN and VERCEL_STOREFRONT_PROJECT_ID set (admin only; VERCEL_TEAM_ID optional), the admin adds the domain to the storefront's Vercel project and reads Vercel's verification/config status.
• Without those, it falls back to a DNS-over-HTTPS check confirming the domain points at SERVICE_DOMAIN (CNAME) or Vercel (cname.vercel-dns.com / 76.76.21.21). Apex domains use the A record; subdomains use the CNAME — either is accepted.
• *.localhost domains auto-verify in development.

Verification is informational: storefront routing is never gated on it, so a shop serves as soon as its domain resolves to the platform.

Documentation site

The docs site is a static Next.js export (output: 'export' in next.config.mjs). It is built and deployed to GitHub Pages via .github/workflows/docs.yml on every push to master.

The workflow:

1. Checks out the repository and runs bootstrap.
2. Builds the docs with pnpm --filter @nordcom/commerce-docs build, passing NEXT_PUBLIC_DOCS_BASE_PATH=/commerce and NEXT_PUBLIC_DOCS_CANONICAL_URL.
3. Uploads the apps/docs/out directory as a Pages artifact.
4. Deploys to GitHub Pages via actions/deploy-pages.

To enable GitHub Pages, go to Settings → Pages → Source and set it to GitHub Actions (not gh-pages branch). The static output directory is gitignored.

Vercel (storefront / admin / landing)

Each of the three product apps is deployed independently on Vercel. The vercel.json in each app's directory configures the project. Use separate Vercel projects, not a monorepo root deployment — the apps have different build commands and environment variable sets.