Development Setup - Documentation

Prerequisites

Before starting development, ensure you have:

Node.js 18+

Download from nodejs.org

Docker Desktop

Required for local services

Git

For version control

Code Editor

VS Code recommended

Initial Setup

Fork Repository

Fork voxora-cloud/voxora on GitHub

Clone Your Fork

git clone https://github.com/<your-username>/voxora.git
cd voxora

Install Dependencies

npm install

Configure Environment

Copy development environment files:

cp apps/api/.env.development apps/api/.env
cp apps/web/.env.development apps/web/.env

Start Services

npm run dev:full

Development Workflow

Daily Development

# Start Docker + dev servers
npm run dev:full

Making Changes

Create Feature Branch

git checkout -b feature/your-feature-name

Make Changes

Edit files in your code editor

Test Locally

Verify changes work correctly

Lint & Format

npm run lint
npm run format

Commit Changes

git add .
git commit -m "feat: add new feature"

Development Tools

VS Code Extensions

Install these recommended extensions:

.vscode/extensions.json

{
  "recommendations": [
    "aaron-bond.better-comments",
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "bradlc.vscode-tailwindcss",
    "mongodb.mongodb-vscode",
    "ms-azuretools.vscode-docker"
  ]
}

VS Code Settings

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}

Git Hooks

Set up pre-commit hooks with Husky:

npm install -D husky lint-staged

# Initialize husky
npx husky install

# Add pre-commit hook
npx husky add .husky/pre-commit "npx lint-staged"

Add to package.json:

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,mdx}": [
      "prettier --write"
    ]
  }
}

Hot Reloading

Web App (Next.js)

Next.js automatically hot reloads on file changes:

Fast Refresh: Preserves component state
Turbopack: Ultra-fast bundling (Next.js 15)
Instant Updates: See changes immediately

API Server (Express)

API uses nodemon for auto-restart:

package.json

{
  "scripts": {
    "dev": "nodemon src/index.js"
  }
}

Install nodemon globally for better performance:

npm install -g nodemon

Database Management

MongoDB

Access MongoDB via:

Mongo Express
MongoDB Compass
CLI

Web UI at http://localhost:8081

Username: admin
Password: pass

Connection string:

mongodb://admin:password@localhost:27017/voxora?authSource=admin

docker exec -it voxora-mongodb mongosh -u admin -p password

Redis

Redis CLI
Redis Commander

docker exec -it voxora-redis redis-cli

# Common commands
KEYS *              # List all keys
GET key             # Get value
DEL key             # Delete key
FLUSHALL            # Clear all data

Install Redis Commander:

npm install -g redis-commander
redis-commander --redis-host localhost

Access at http://localhost:8081

Testing

Run Tests

npm run test

Writing Tests

Example test structure:

__tests__/api/auth.test.js

import request from 'supertest';
import app from '../../src/app';

describe('POST /api/v1/auth/login', () => {
  it('should login with valid credentials', async () => {
    const response = await request(app)
      .post('/api/v1/auth/login')
      .send({
        email: 'test@example.com',
        password: 'password123'
      });
      
    expect(response.status).toBe(200);
    expect(response.body).toHaveProperty('token');
  });
  
  it('should reject invalid credentials', async () => {
    const response = await request(app)
      .post('/api/v1/auth/login')
      .send({
        email: 'test@example.com',
        password: 'wrongpassword'
      });
      
    expect(response.status).toBe(401);
  });
});

Debugging

VS Code Debug Configuration

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug API",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "cwd": "${workspaceFolder}/apps/api",
      "console": "integratedTerminal"
    },
    {
      "name": "Debug Web",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "cwd": "${workspaceFolder}/apps/web",
      "console": "integratedTerminal"
    }
  ]
}

Server Logs

Enable detailed logging:

apps/api/.env

LOG_LEVEL=debug

View logs:

# Docker logs
docker logs voxora-mongodb
docker logs voxora-redis

# Application logs
npm run dev -w apps/api

Environment Variables

Required Variables

apps/api/.env
apps/web/.env

# Server
PORT=3002
NODE_ENV=development

# Database
MONGODB_URI=mongodb://admin:password@localhost:27017/voxora?authSource=admin

# Cache
REDIS_HOST=localhost
REDIS_PORT=6379

# Auth
JWT_SECRET=your-secret-key-change-in-production
JWT_EXPIRES_IN=7d

# CORS
CORS_ORIGIN=http://localhost:3000

# Email (MailHog for dev)
SMTP_HOST=localhost
SMTP_PORT=1025
EMAIL_FROM=noreply@voxora.cloud

# API
NEXT_PUBLIC_API_URL=http://localhost:3002
NEXT_PUBLIC_SOCKET_URL=http://localhost:3002

# Widget
NEXT_PUBLIC_WIDGET_URL=http://localhost:3002/widget

# Features
NEXT_PUBLIC_ENABLE_ANALYTICS=false

Common Tasks

Add a New Dependency

# To API
npm install express-validator -w apps/api

# To Web
npm install @radix-ui/react-dialog -w apps/web

# To root (build tools)
npm install -D typescript -w root

Update Dependencies

# Check for updates
npm outdated

# Update all
npm update

# Update specific package
npm update react -w apps/web

Clean & Rebuild

# Remove node_modules
rm -rf node_modules apps/*/node_modules

# Clean build artifacts
npm run clean

# Reinstall
npm install

# Rebuild
npm run build

Troubleshooting

Port already in use

Find and kill the process:

# Find process on port 3000
lsof -i :3000

# Kill it
kill -9 <PID>

Docker issues

Reset Docker:

npm run docker:stop
docker system prune -a
npm run docker:start

Module not found

Clear and reinstall:

rm -rf node_modules package-lock.json
npm install

Database connection error

Verify MongoDB is running:

docker ps | grep mongo

Check connection string in .env

Next Steps

Environment Variables

Complete environment configuration guide

Docker Services

Managing local Docker services

Scripts Reference

All available npm scripts

Contributing

How to contribute to Voxora

Getting Started

Core Concepts

Development

Deployment

​Prerequisites

Node.js 18+

Docker Desktop

Git

Code Editor

​Initial Setup

​Development Workflow

​Daily Development

​Making Changes

​Development Tools

​VS Code Extensions

​VS Code Settings

​Git Hooks

​Hot Reloading

​Web App (Next.js)

​API Server (Express)

​Database Management

​MongoDB

​Redis

​Testing

​Run Tests

​Writing Tests

​Debugging

​VS Code Debug Configuration

​Server Logs

​Environment Variables

​Required Variables

​Common Tasks

​Add a New Dependency

​Update Dependencies

​Clean & Rebuild

​Troubleshooting

​Next Steps

Environment Variables

Docker Services

Scripts Reference

Contributing

Prerequisites

Initial Setup

Development Workflow

Daily Development

Making Changes

Development Tools

VS Code Extensions

VS Code Settings

Git Hooks

Hot Reloading

Web App (Next.js)

API Server (Express)

Database Management

MongoDB

Redis

Testing

Run Tests

Writing Tests

Debugging

VS Code Debug Configuration

Server Logs

Environment Variables

Required Variables

Common Tasks

Add a New Dependency

Update Dependencies

Clean & Rebuild

Troubleshooting

Next Steps