Local Development¶

This guide walks through setting up the Trove platform on your local machine for development. If anything is missing or out of date, submit a request via the Wiki Update Requests list in ClickUp.

Prerequisites¶

Make sure you have the following installed before starting:

Tool	Version	Notes
Node.js	>= 22	Use nvm to manage versions
pnpm	>= 10	`npm install -g pnpm`
MySQL	8.x	Local instance or Docker
Git	Any recent	—

You will also need access to:

The wiki-and-docs GitHub repository (this wiki)
The main Trove application repository
An Auth0 development tenant (ask Joshua)
AWS credentials for a development environment (ask Joshua)

Step 1: Clone the Repository¶

git clone git@github.com:Elliephant-Gifting/trove.git
cd trove

Step 2: Install Dependencies¶

The monorepo uses pnpm workspaces. Install all dependencies from the root:

pnpm install

This installs dependencies for all apps and libraries in one step.

Step 3: Configure Environment Variables¶

Each app has its own .env file. Copy the example files and fill in your local values:

cp apps/api/.env.example apps/api/.env
cp apps/admin-portal/.env.example apps/admin-portal/.env
cp apps/customer-frontend/.env.example apps/customer-frontend/.env
cp apps/worker/.env.example apps/worker/.env

Key variables you will need to fill in:

Database (API)

DATABASE_HOST=localhost
DATABASE_PORT=3306
DATABASE_NAME=trove_dev
DATABASE_USER=root
DATABASE_PASSWORD=your_password

Auth0 (API + frontends)

AUTH0_DOMAIN=your-dev-tenant.au.auth0.com
AUTH0_AUDIENCE=https://your-api-identifier

AWS (API + Worker)

AWS_REGION=ap-southeast-2
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
AWS_S3_BUCKET=your-dev-bucket
AWS_SQS_QUEUE_URL=https://sqs.ap-southeast-2.amazonaws.com/...

Stripe (API)

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Ask Joshua for the development credentials for Auth0, AWS, and Stripe. Do not use production credentials locally.

Step 4: Set Up the Database¶

Create a local MySQL database:

CREATE DATABASE trove_dev CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Then run all migrations to bring the schema up to date:

pnpm nx run api:migration:up

Optionally, run the seeders to populate development data:

pnpm nx run api:seed

Step 5: Start the Applications¶

Each app runs independently. Open separate terminal windows for each one you need.

API (runs on http://localhost:3000)

pnpm nx serve api

Admin Portal (runs on http://localhost:8080)

pnpm nx serve admin-portal

Customer Frontend (runs on http://localhost:4200 by default)

pnpm nx serve customer-frontend

Worker

pnpm nx serve worker

Swagger / API Docs¶

When the API is running, the interactive Swagger documentation is available at:

http://localhost:3000/api/docs

Step 6: Multi-Tenant Admin Portal Setup¶

The Admin Portal is multi-tenant by subdomain. In development, each vendor is accessed via {vendor}.localhost:8080.

To test with a specific vendor, add an entry to your /etc/hosts file:

127.0.0.1   myvendor.localhost

Then open http://myvendor.localhost:8080 in your browser. The portal will load the configuration for that vendor from the API.

To edit /etc/hosts on macOS:

sudo nano /etc/hosts

Running Tests¶

# Run all tests
pnpm nx run-many --target=test --all

# Run tests for a specific app
pnpm nx test api
pnpm nx test admin-portal

# Run only tests affected by your changes
pnpm nx affected --target=test

Useful Nx Commands¶

# Visualise the dependency graph
pnpm nx graph

# Build all apps
pnpm nx run-many --target=build --all

# Clear the Nx cache
pnpm nx reset

Database Migrations¶

When you make changes to MikroORM entities, you need to generate and apply a migration:

# Generate a migration from entity changes
pnpm nx run api:migration:create

# Apply pending migrations
pnpm nx run api:migration:up

# Revert the last migration
pnpm nx run api:migration:down

Migration files are created in database/migrations/ and must be committed with your changes.

Common Issues¶

pnpm install fails with Node version error Make sure you are running Node >= 22. Check with node --version and switch using nvm if needed:

nvm install 22
nvm use 22

API fails to start with database connection error Make sure your local MySQL instance is running and the credentials in apps/api/.env match your local setup.

Admin portal shows wrong vendor or blank screen Check that your /etc/hosts entry is correct and that the vendor slug matches an existing vendor in your local database. Reseed the database if needed.

Migrations fail with "table already exists" Your database may be out of sync. Check the current migration state and resolve conflicts before re-running.