Skip to content
Last updated Give Feedback

Quick Start

import { Steps, Code } from ‘@astrojs/starlight/components’;

Quick Start

Section titled “Quick Start”

Prerequisites

Section titled “Prerequisites”
  • Node.js 22 LTS — node --version must show v22.x.x
  • npm 10+ — included with Node.js 22
  • Git

No Docker required for local development. ecommus uses pglite — an in-process PostgreSQL-compatible database.

Installation

Section titled “Installation”

  1. Clone the repository

    Terminal window
    git clone https://github.com/MDLABS-cmd/ecommus.git
    cd ecommus

  2. Install all dependencies

    Terminal window
    npm install

    This installs all workspace packages: packages/*, apps/*, plugins/*.

  3. Configure environment

    Terminal window
    cp .env.example .env

    The defaults work for local development. Set the two JWT signing secrets (each 32+ random chars):

    .env
    JWT_ACCESS_SECRET=your-access-secret-32-chars-min
    JWT_REFRESH_SECRET=your-refresh-secret-32-chars-min
    DATABASE_MODE=pglite

    In production, the API refuses to boot if either secret is missing or starts with dev-. See Environment Variables for the full list.

  4. Start the dev servers

    Terminal window
    node scripts/dev.mjs

    This starts all four servers concurrently:

    ServerURLDescription
    APIhttp://localhost:4000Fastify REST API
    Adminhttp://localhost:3001Next.js Admin Panel
    Super-adminhttp://localhost:3002Next.js Operator Console
    Storefronthttp://localhost:3000Astro Storefront

  5. Seed the database (optional)

    Terminal window
    node --experimental-strip-types scripts/seed.ts

    Creates a demo tenant, admin user, and sample products.

  6. Open the admin panel

    Navigate to http://localhost:3001 and log in with the seeded credentials:

    • Email: admin@demo.local
    • Password: admin123

Project Structure

Section titled “Project Structure”
ecommus/
├── apps/
│   ├── api/              # Fastify REST API
│   ├── admin/            # Next.js 15 admin panel
│   ├── super-admin/      # Next.js 15 operator console
│   └── storefront-astro/ # Astro 5 public storefront
├── packages/
│   ├── core/             # Business logic (pricing, tax, events)
│   ├── db/               # Drizzle schema + migrations
│   ├── client/           # @ecommus/client — JavaScript SDK
│   ├── plugin-sdk/       # @ecommus/plugin-sdk — plugin framework
│   └── testing/          # @ecommus/testing — mock factories
├── plugins/              # Plugin packages (auto-discovered)
├── themes/               # Theme packages (auto-discovered)
└── scripts/              # Dev utilities

Next Steps

Section titled “Next Steps”