Monorepo Toolchain
Relevant source files
The following files were used as context for generating this wiki page:
The Nordcom Commerce monorepo toolchain is a unified system for managing a multi-tenant headless e-commerce platform. It leverages a modern TypeScript stack centered around pnpm workspaces for dependency management, Turborepo for build orchestration and caching, and Biome for consolidated linting and formatting. The architecture is designed to support multiple applications (Storefront, Admin, Landing) and various shared packages within a single repository while maintaining high performance and strict quality gates.
Sources: README.md:92-108, CLAUDE.md:1-15
Core Infrastructure
The monorepo is structured into two primary directories: apps/ for deployable services and packages/ for shared libraries and internal tools. Orchestration is handled via turbo and portless, providing a local development environment that mimics production multi-tenancy.
Workspace Orchestration
Turborepo (Turbo) serves as the primary task runner, managing complex dependency graphs and caching build outputs. This is complemented by portless, which auto-discovers packages and manages local proxying and wildcard HTTPS for subdomains like admin.localhost and storefront.localhost.
The diagram shows how the root workspace orchestrates applications and their shared dependencies through Turbo and Portless.
Sources: README.md:120-135, CLAUDE.md:9-15, package.json:20-40
Development & Build Workflow
The toolchain enforces a strict "build-before-use" policy where applications import workspace packages from their built dist/ directories rather than directly from source.
Initialization & Execution
Developers use pnpm dev to boot the entire stack. This process includes starting a local Convex backend, pushing functions, and applying seed fixtures before launching applications through the portless proxy.
| Command | Action |
|---|---|
pnpm install | Installs dependencies using pnpm 11.x. |
pnpm build:packages | Builds all packages in ./packages/*; required for lint/typecheck. |
pnpm dev | Runs all workspace dev scripts through portless with local Convex. |
pnpm generate | Runs codegen tasks like cms:gen and typegen. |
pnpm clean | Removes .next, dist, .turbo, and node_modules. |
Sources: package.json:11-30, CLAUDE.md:16-18, README.md:144-162
Environment Management
Top-level scripts are executed through dotenv -c -- turbo ..., which automatically loads .env and .env.local files. Environment-tier gating is handled via @nordcom/commerce-utils using functions like isProduction() or isDevelopment() to ensure consistency across Vercel previews and local runs.
Sources: CLAUDE.md:19-22, CLAUDE.md:113-120
Quality Control & Testing
The toolchain replaces traditional tools like ESLint and Prettier with Biome for both linting and formatting.
Unified Linting
Biome is used for all code quality checks. The configuration prevents the use of raw console.log (except in config/tests) and enforces the use of import type for type-only imports.
Multi-tiered Testing
Testing is distributed across package-level unit tests and application-level E2E suites.
The sequence shows the distributed testing flow where package results are cached by Turbo and then merged for global coverage gating.
Sources: CLAUDE.md:23-35, package.json:54-60
- Unit Testing: Runs through
turbo run testwith 50% concurrency to avoid core oversubscription. Each package generates its own coverage shard. - Coverage Gating:
scripts/coverage-gate.tsmerges shards and enforces coverage floors defined invitest.shared.ts. - E2E Testing: Playwright suites in
apps/admin/e2e/andapps/storefront/e2e/drive the real application against a seeded local backend.
Sources: CLAUDE.md:23-35, CLAUDE.md:129-145
Specialized Tooling
The repository includes custom generators and specialized services to maintain type safety and content synchronization.
CMS Codegen
pnpm cms:gen is a descriptor-driven generator that synchronizes:
- Admin editor-action wrappers.
- Storefront content types in
packages/cms/src/types/content-types.ts. - Convex table validators in
packages/convex/convex/tables/cms.ts.
Sources: CLAUDE.md:36-40, packages/cms/package.json:76-77
Versioning & Changesets
The toolchain uses Changesets to manage semantic versioning. Any change to a non-ignored package requires a changeset (pnpm changeset). Releases are automated via pnpm changeset:publish, which builds packages before publishing.
Sources: package.json:72-76, CLAUDE.md:154-158
Local Data Layer (Convex)
Local development utilizes a persistent anonymous Convex backend stored in .convex-local/.
pnpm convex:local: Boots and seeds the backend.pnpm convex:local:reset: Wipes and reseeds with canonical fixtures.- Integration tests use
@nordcom/commerce-test-convexto launch ephemeral backends.
Sources: README.md:164-168, package.json:65-70
Technical Standards Summary
| Standard | Tool / Implementation |
|---|---|
| Lint/Format | Biome 2.x (No ESLint/Prettier) |
| Type Safety | TypeScript 6.0+, noUncheckedIndexedAccess: true |
| Commit Style | Conventional Commits with scope |
| Git Policy | Always rebase; no merge commits |
| Documentation | JSDoc required for all functions; Markdown specs in .specs/ |
Sources: CLAUDE.md:80-92, CLAUDE.md:146-153, package.json:115-135
The Monorepo Toolchain provides a highly automated and strictly governed environment that ensures architectural consistency across the entire commerce platform while optimizing for developer productivity through caching and local-first data services.