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) or yarn v1.22+
  • PostgreSQL v12+ (for local development)
  • Git for version control
  • VS Code (recommended) or your preferred code editor

Optional Tools​

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

Project Structure Overview​

chirp/
├── docs/                     # Documentation (Docusaurus)
├── public/                   # Static assets
├── scripts/                  # Build and utility scripts
├── server/                   # Backend Node.js application
│   ├── .env                 # Environment variables (create from example)
│   ├── database/            # Database related files
│   │   ├── migrations/       # Knex.js migrations
│   │   └── seeds/           # Database seeds
│   ├── routes/              # REST API endpoints
│   ├── middleware/          # Express middleware
│   ├── utils/               # Server utilities
│   ├── socket.js            # Socket.IO configuration
│   └── uploads/             # File storage (auto-created)
├── src/                     # Frontend React application
│   ├── main/                # Electron main process
│   ├── preload/             # Electron preload scripts
│   └── renderer/            # React web application
│       ├── components/      # React components
│       ├── hooks/           # Custom React hooks
│       ├── lib/             # Utility libraries
│       ├── stores/          # Zustand state stores
│       └── utils/           # Frontend utilities
├── package.json             # Root package configuration
├── electron-builder.json    # Electron packaging 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 (root, web, server)
npm install

# This automatically installs dependencies for:
# - Root workspace dependencies
# - Web frontend (src/renderer)
# - Server backend (server/)
# - Electron main process (src/main)

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
cd server
cp .env.example .env

# Edit .env with your database credentials
# Example configuration:
# DB_HOST=localhost
# DB_PORT=5432
# DB_USER=chirp_dev
# DB_PASSWORD=chirp_dev_password
# DB_NAME=chirp_dev
# DB_SSL=false

3. Run Database Migrations​

# From the project root
npm run db:migrate

# Or manually from server directory
cd server
npx knex migrate:latest

4. Environment Configuration​

Server Environment (server/.env)​

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

# Application Configuration
NODE_ENV=development
PORT=3001
BASE_URL=http://localhost:3001
JWT_SECRET=your-development-jwt-secret-here

# Optional Services
TENOR_API_KEY=your-tenor-api-key  # For GIF search
ADMIN_KEY=your-admin-key           # For admin API access

Frontend Environment (Optional)​

Create .env.local in the project root for frontend overrides:

# API endpoint for development
VITE_API_URL=http://localhost:3001

5. Start Development Servers​

# This starts all services: server, web dev server, and Electron
npm run dev

This command runs:

Individual Services​

# Start only the backend server
npm run dev:server

# Start only the web frontend
npm run dev:web

# Start all + Electron app
npm run dev:electron

6. Verify Setup​

  1. Web Frontend: Visit http://localhost:5173
  2. Electron App: Should launch automatically

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

Development Workflow​

Code Organization​

  • Monorepo Structure: Single repository with multiple packages
  • 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​

# Create a new migration
npm run migrate:make your_migration_name

# Rollback last migration
npm run db:rollback

# Seed database with sample data
npm run db:seed

# Reset database (destructive!)
npm run db:reset

Testing​

# Run all frontend tests
npm test

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

Common Development Issues​

Port Conflicts​

If ports 3001 or 5173 are already in use:

# Kill processes using the ports
netstat -tulpn | grep :3001
kill -9 <PID>

# Or change ports in environment files

Database Connection Issues​

  • Ensure PostgreSQL is running
  • Verify database credentials in .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

Code Review Standards​

  • Maintain backward compatibility when possible
  • Follow security best practices
  • Ensure proper optimization
  • Ensure proper error handling
  • Add appropriate comments for complex logic
  • Keep PRs focused and reasonably sized

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

Happy coding! 🚀