Quick Start and Setup
Relevant source files
The following files were used as context for generating this wiki page:
Nordcom Commerce is a multi-tenant, headless e-commerce platform that utilizes Next.js 16, Shopify for commerce logic, and Convex for its data and content layer. The repository is structured as a TypeScript monorepo managed with pnpm workspaces and Turborepo.
The platform serves multiple tenants from a single deployment by resolving hostnames at the middleware level. This setup guide covers the prerequisites, installation steps, and environment configurations required to run the Storefront, Admin, and Landing applications locally.
Sources: README.md:1-25, README.md:104-111
Prerequisites and Local Environment
Before initializing the project, ensure the following tools are installed and configured:
- Node.js: Versions as specified in the
.nvmrcfile. - pnpm: Version 11.x is the required package manager.
- portless: Required for local development to handle local CA trust and HTTPS/wildcard proxying.
- Convex: The data layer. Local development uses a local-first backend that boots and seeds automatically.
Sources: README.md:31-35, README.md:73-77, CLAUDE.md:4-5
Local Proxy Setup
Portless is used to manage local development hostnames (e.g., *.localhost).
- Install portless globally:
npm install -g portless. - Trust the local CA:
portless trust(requires sudo). - The proxy starts automatically when running
pnpm dev.
Sources: README.md:73-77, package.json:16-17
Installation and Initial Build
The repository requires a specific sequence for a fresh checkout because applications import workspace packages from their built dist/ directories rather than source.
Setup Sequence
# 1. Install dependencies
pnpm install
# 2. Configure environment
cp .env.example .env
# 3. Build workspace packages (Crucial for lint/typecheck/tests)
pnpm build:packages
# 4. Start the development environment
pnpm dev
Sources: README.md:37-52, CLAUDE.md:10-11
The following diagram illustrates the local boot process triggered by pnpm dev.
This flow ensures the local database is available and seeded before the Next.js applications attempt to connect.
Sources: README.md:54-65, package.json:16-24
Environment Configuration
Environment variables are managed via dotenv. Top-level scripts automatically load .env and .env.local.
Core Environment Variables
| Variable | Purpose | Location |
|---|---|---|
AUTH_SECRET | NextAuth signing secret. Required for session management. | Root .env |
SERVICE_DOMAIN | Fallback hostname for unknown-shop rewrites. | Root .env |
CONVEX_URL | URL for the Convex deployment (defaults to :3210 locally). | Root .env |
ADMIN_DOMAIN | Canonical hostname for the admin dashboard. | apps/admin |
LANDING_DOMAIN | Canonical hostname for the marketing site. | apps/landing |
Sources: README.md:44-46, apps/admin/README.md:28-40, apps/landing/README.md:32-34
Identity and Authentication Setup
The Admin app requires CONVEX_AUTH_PRIVATE_KEY to mint operator tokens for CMS editing. If this is unset, CMS-editor pages (like /content/*) will throw a ConvexOperatorTokenMintError.
Sources: apps/admin/README.md:46-52
Development Workflow
Tooling Constraints
The project enforces strict tooling standards that differ from common defaults:
- Biome: Used exclusively for linting and formatting. No ESLint or Prettier.
- Portless Overrides:
portless.jsonmanages local ports and proxy settings. - Turborepo: All build and test tasks are orchestrated via Turbo for caching.
Sources: CLAUDE.md:6-9, package.json:71-72
Application Access
Once pnpm dev is running, the services are reachable at the following local URLs:
| Application | Local URL |
|---|---|
| Storefront | https://storefront.localhost |
| Admin | https://admin.localhost |
| Landing | https://landing.localhost |
Sources: README.md:67-71
Execution Logic
The development lifecycle involves multiple concurrent processes as visualized below:
Sources: README.md:54-65, package.json:16-24, CLAUDE.md:7-9
Testing and Quality Gates
Unit tests run per-package via Turbo to utilize the build cache. Integration and E2E suites boot ephemeral backends.
- Linting:
pnpm lint(Uses Biome). - Typechecking:
pnpm typecheck(Runstsc -noEmitvia Turbo). - Unit Tests:
pnpm test(Uses Vitest withhappy-dom). - E2E Tests:
pnpm test:e2e(Uses Playwright, requires local server).
Sources: README.md:120-142, CLAUDE.md:14-20
Repository Housekeeping
To reset the environment to a clean state:
- Clean build artifacts:
pnpm clean(Removesdist,.next,.turbo, andnode_modules). - Reset Data:
pnpm convex:local:reset(Wipes and reseeds the local Convex database).
Sources: README.md:144-146, package.json:44, package.json:59
Nordcom Commerce requires a specific boot order—proxying, data layer, and then application servers—to function correctly in a multi-tenant local environment. Correct configuration of the CONVEX_AUTH_PRIVATE_KEY and the use of portless are the most critical steps for a fully functional dashboard and storefront.