Installation

Overview

NexusCommerce is a pnpm monorepo with four runnable services: a Next.js frontend, a NestJS API, Python AI workers, and a Fumadocs documentation site. Supporting infrastructure (Redis, ClickHouse, Grafana) runs via Docker Compose. The primary database and auth are hosted on Supabase Cloud.

For production deployment, see Deployment.

Key Concepts

Monorepo — All code lives in a single repository managed by pnpm workspaces and Turborepo. Running pnpm dev starts all services with hot reload.

Supabase Cloud — NexusCommerce uses managed Supabase for PostgreSQL, Auth, Storage, and Realtime. No local database setup required.

Docker Compose (dev) — Redis, ClickHouse, Python workers, and Grafana run as containers via infrastructure/docker-compose.yml.

Getting Started

Prerequisites

• Node.js 22+
• pnpm 10+ (corepack enable && corepack prepare pnpm@10 --activate)
• Docker Engine 24+ with Compose V2
• A Supabase Cloud project (free tier works)

Step 1: Clone and install

git clone https://github.com/your-org/nexuscommerce.git
cd nexuscommerce
pnpm install

Step 2: Configure environment

cp .env.example .env

Fill in the required values:

# Supabase (from your Supabase project settings)
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...
SUPABASE_DB_URL=postgresql://postgres:[email protected]:5432/postgres

# API
API_PORT=3001
FRONTEND_URL=http://localhost:3000

# Redis + ClickHouse (defaults work with Docker Compose)
REDIS_URL=redis://localhost:6379
CLICKHOUSE_URL=http://localhost:8123
CLICKHOUSE_USER=default

Step 3: Start infrastructure services

cd infrastructure && docker compose up -d

This starts Redis (6379), ClickHouse (8123), Python workers (8288), and Grafana (3333).

Step 4: Apply database migrations

npx supabase db push

This creates all 25+ tables with RLS policies and indexes.

Step 5: Start the development servers

pnpm dev

This runs all services via Turborepo:

Step 6: Verify

Open http://localhost:3000 to see the landing page. The API health endpoint is at http://localhost:3001/api/v1/health.

Features

Individual Service Commands

You can start services individually using pnpm filters:

pnpm --filter @nexuscommerce/web dev      # Frontend only
pnpm --filter @nexuscommerce/api dev      # API only
pnpm --filter @nexuscommerce/docs dev     # Docs only
pnpm --filter @nexuscommerce/ui storybook # Storybook on port 6006

Build and Typecheck

pnpm build       # Build all packages and apps
pnpm typecheck   # TypeScript compiler checks
pnpm lint        # ESLint across monorepo
pnpm test        # Run all tests

Load Testing

k6 load tests are available for smoke, load, stress, and soak profiles:

pnpm k6:smoke    # 1 VU, 30s — quick sanity check
pnpm k6:load     # 50 VUs, 5min — standard load
pnpm k6:stress   # 200 VUs, 10min — stress test
pnpm k6:soak     # 20 VUs, 30min — endurance test

Configuration

Health Checks

Environment Tiers

See Deployment for production setup.