Skip to main content

Development Setup

This guide will help you set up a complete development environment for contributing to Chirp. Whether you want to fix bugs, add features, or extend the platform, this guide covers everything you need.

Prerequisites​

Required Software​

  • Node.js v18+ (recommended v20 LTS)
  • npm v9+ (comes with Node.js)
  • PostgreSQL v12+ (for local development)
  • Redis (for caching and session management)
  • Git for version control
  • VS Code (recommended) or your preferred code editor

Optional Tools​

  • Docker and Docker Compose (for containerized development)
  • pgAdmin or similar PostgreSQL GUI client
  • Postman or Insomnia (API testing)
  • React Developer Tools (browser extension)

Project Structure Overview​

chirp/
├── docs/                     # Documentation (Docusaurus)
├── examples/                 # Example bots and integrations
├── packages/                 # SDK packages (e.g., chirp-sdk)
├── public/                   # Static assets
├── scripts/                  # Build and utility scripts
├── server/                   # Backend Node.js application
│   ├── .env                 # Environment variables (create from .env.example)
│   ├── database/            # Database related files
│   │   └── migrations/      # Knex.js migrations
│   ├── routes/              # REST API endpoints
│   ├── middleware/          # Express middleware
│   ├── utils/               # Server utilities
│   ├── socket.js            # Socket.IO configuration
│   └── uploads/             # File storage (auto-created)
├── src/                     # Frontend & Electron application
│   ├── main/                # Electron main process
│   ├── preload/             # Electron preload scripts
│   └── renderer/            # React web application
│       ├── components/      # React components (organized by feature)
│       │   ├── ai/          # AI chat integration
│       │   ├── auth/        # Authentication pages
│       │   ├── channel/     # Channel management
│       │   ├── chat/        # Chat interface
│       │   ├── collaborative/ # Collaborative editing
│       │   ├── dm/          # Direct messages
│       │   ├── events/      # Server events
│       │   ├── forum/       # Forum features
│       │   ├── friends/     # Friends system
│       │   ├── layout/      # Layout components
│       │   ├── media/       # Media browsing
│       │   ├── moderation/  # Moderation tools
│       │   ├── server/      # Server settings
│       │   ├── settings/    # User settings
│       │   ├── threads/     # Thread system
│       │   ├── ui/          # Shared UI components
│       │   ├── user/        # User profiles
│       │   └── voice/       # Voice channels
│       ├── hooks/           # Custom React hooks
│       ├── lib/             # Utility libraries
│       ├── stores/          # Zustand state stores
│       └── utils/           # Frontend utilities
├── package.json             # Root package configuration
├── docker-compose.yml       # Docker deployment config
└── vite.config.js           # Vite build configuration

Setup Process​

1. Clone and Install Dependencies​

# Clone the repository
git clone https://git.eidenz.moe/Eidenz/Chirp.git
cd chirp

# Install all dependencies
npm install

2. Database Setup​

Local PostgreSQL​

# Create PostgreSQL database and user
psql -U postgres
CREATE DATABASE chirp_dev;
CREATE USER chirp_dev WITH PASSWORD 'chirp_dev_password';
GRANT ALL PRIVILEGES ON DATABASE chirp_dev TO chirp_dev;
\q

# Copy environment configuration
cp server/.env.example server/.env

# Edit server/.env with your database credentials

3. Run Database Migrations​

# From the project root
npm run db:migrate

4. Environment Configuration​

Server Environment (server/.env)​

# Core
PORT=3001
NODE_ENV=development
CORS_ORIGIN=http://localhost:5173
BASE_URL=http://localhost:5173
JWT_SECRET=your-development-jwt-secret-here

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USER=chirp_dev
DB_PASSWORD=chirp_dev_password
DB_NAME=chirp_dev
DB_SSL=false

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
REDIS_URL=redis://localhost:6379

# Optional Services
TENOR_API_KEY=your-tenor-api-key  # For GIF search
MAX_SERVERS_PER_USER=15
MAX_BOTS_PER_USER=3

5. Start Development Servers​

# This starts backend server + web dev server
npm run dev

This runs concurrently:

With Electron​

# Starts backend + frontend + Electron desktop app
npm run dev:electron

Individual Services​

# Start only the backend server
npm run dev:server

# Start only the web frontend
npm run dev:web

6. Verify Setup​

  1. Web Frontend: Visit http://localhost:5173
  2. Electron App: Should launch automatically (when using dev:electron)

Create an account through the web interface to verify everything works.

Development Workflow​

Code Organization​

  • Monorepo Structure: Single repository with frontend, backend, and desktop app
  • Scripts: Centralized npm scripts for common operations
  • Hot Reload: Both frontend and backend support hot reloading

Git Workflow​

# Create a feature branch
git checkout -b feature/your-feature-name

# Make your changes
# ... (work on your feature)

# Stage and commit changes
git add .
git commit -m "feat: add your feature description"

# Push to your fork
git push origin feature/your-feature-name

# Create a pull request

Development Tips​

Database Management​

# Apply pending migrations
npm run db:migrate

# Rollback last migration
npm run db:rollback

# Seed database with sample data
npm run db:seed

Testing​

# Run all frontend tests
npm test

# Run all backend tests
npm run test:backend:sequential

# Run specific test suites
npm run test:frontend
npm run test:backend
npm run test:e2e
npm run test:integration

# Run with coverage
npm run test:coverage

Building​

# Build web assets
npm run build:web

# Build Electron app (Windows)
npm run build

# Build for Linux
npm run build:linux
npm run build:linux:deb

Common Development Issues​

Port Conflicts​

If ports 3001 or 5173 are already in use:

# Find and kill processes using the ports
# Linux/Mac:
lsof -ti:3001 | xargs kill -9

# Windows:
netstat -ano | findstr :3001
taskkill /PID <PID> /F

Database Connection Issues​

  • Ensure PostgreSQL is running
  • Ensure Redis is running
  • Verify database credentials in server/.env
  • Check if database was created properly

Node Module Issues​

# Clean node modules and reinstall
rm -rf node_modules package-lock.json
npm install

Contributing Guidelines​

Before You Start​

  1. Check existing issues for similar work
  2. Fork the repository and create a feature branch
  3. Follow the existing code style and patterns
  4. Write tests for new features
  5. Update documentation when needed

Pull Request Process​

  1. Description: Clearly describe what your PR does
  2. Testing: Explain how you tested your changes
  3. Screenshots: Include screenshots for UI changes
  4. Documentation: Update relevant documentation
  5. Breaking Changes: Clearly label any breaking changes

Architecture Understanding​

Before diving deep, understand these key concepts:

  • Monorepo: Frontend, backend, and desktop app in one repository
  • Real-time: Socket.IO for live updates and presence
  • State Management: Zustand for client state, TanStack Query for server state
  • Database: PostgreSQL with Knex.js migrations
  • Authentication: JWT-based with 2FA support
  • File Storage: Local file system with thumbnail generation
  • Desktop: Electron wrapper around the web app
  • Voice: WebRTC-based voice channels with TURN server support
  • Mobile: Capacitor-based Android app