Skip to main content

Development Setup

This guide will help you set up your development environment for working with Solverhood projects. Follow these steps to get everything configured properly.

System Requirements​

Minimum Requirements​

  • Operating System: macOS 10.15+, Windows 10+, or Ubuntu 18.04+
  • Node.js: Version 18.0.0 or higher
  • npm: Version 8.0.0 or higher (comes with Node.js)
  • Git: Version 2.20.0 or higher
  • RAM: 8GB minimum (16GB recommended)
  • Storage: 10GB free space
  • Operating System: macOS 12+ or Ubuntu 20.04+
  • Node.js: Version 20.0.0 or higher
  • Package Manager: pnpm or yarn
  • Code Editor: Visual Studio Code with recommended extensions
  • RAM: 16GB or higher
  • Storage: SSD with 50GB+ free space

Installing Prerequisites​

1. Node.js and npm​

macOS (using Homebrew)​

# Install Homebrew if you haven't already
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js
brew install node

# Verify installation
node --version
npm --version

Windows​

  1. Download Node.js from nodejs.org
  2. Run the installer and follow the setup wizard
  3. Verify installation in Command Prompt:
node --version
npm --version

Ubuntu/Debian​

# Update package list
sudo apt update

# Install Node.js and npm
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version
npm --version

2. Git​

macOS​

# Git comes pre-installed on macOS
# If you need to update, use Homebrew:
brew install git

Windows​

  1. Download Git from git-scm.com
  2. Run the installer with default settings
  3. Verify installation:
git --version

Ubuntu/Debian​

sudo apt update
sudo apt install git
git --version
# Install pnpm globally
npm install -g pnpm

# Verify installation
pnpm --version

Yarn​

# Install Yarn globally
npm install -g yarn

# Verify installation
yarn --version

Development Tools​

1. Code Editor​

  1. Download from code.visualstudio.com
  2. Install recommended extensions:
    • ESLint - JavaScript linting
    • Prettier - Code formatting
    • GitLens - Git integration
    • Auto Rename Tag - HTML/JSX tag renaming
    • Bracket Pair Colorizer - Bracket matching
    • Thunder Client - API testing

Alternative Editors​

  • WebStorm - Full-featured IDE
  • Sublime Text - Lightweight editor
  • Vim/Neovim - Terminal-based editor

2. Terminal​

macOS​

  • iTerm2 (recommended): Download from iterm2.com
  • Terminal.app (built-in)

Windows​

  • Windows Terminal (recommended): Install from Microsoft Store
  • Git Bash: Comes with Git for Windows
  • PowerShell: Built-in

Ubuntu/Debian​

  • Terminal (built-in)
  • Terminator: sudo apt install terminator

3. Database Tools​

PostgreSQL​

# macOS
brew install postgresql
brew services start postgresql

# Ubuntu/Debian
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Windows
# Download from postgresql.org and run installer

Database GUI Tools​

  • pgAdmin - Official PostgreSQL admin tool
  • DBeaver - Universal database tool
  • TablePlus - Modern database client

Project Setup​

1. Clone the Repository​

# Clone the main repository
git clone https://github.com/solverhood/tech-docs.git
cd tech-docs

# Install dependencies
npm install
# or with pnpm
pnpm install

2. Environment Configuration​

Create a .env file in the project root:

# Copy the example environment file
cp .env.example .env

# Edit the file with your configuration
nano .env

Example .env configuration:

# Development Environment
NODE_ENV=development
PORT=3000

# Database
DATABASE_URL=postgresql://username:password@localhost:5432/solverhood_dev

# API Keys
SOLVERHOOD_API_KEY=your_development_api_key
SOLVERHOOD_SECRET_KEY=your_development_secret_key

# External Services
REDIS_URL=redis://localhost:6379
SENDGRID_API_KEY=your_sendgrid_key

# Application Settings
BASE_URL=http://localhost:3000
CORS_ORIGIN=http://localhost:3000

3. Database Setup​

# Create database
createdb solverhood_dev

# Run migrations
npm run db:migrate
# or
pnpm db:migrate

# Seed the database (if applicable)
npm run db:seed
# or
pnpm db:seed

4. Development Server​

# Start the development server
npm run dev
# or
pnpm dev

# The application should now be running at http://localhost:3000

Development Workflow​

1. Git Configuration​

# Set your Git identity
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Configure default branch
git config --global init.defaultBranch main

# Set up SSH keys (recommended)
ssh-keygen -t ed25519 -C "your.email@example.com"

2. Code Quality Tools​

ESLint Configuration​

# Install ESLint
npm install -g eslint

# Initialize ESLint in your project
eslint --init

Prettier Configuration​

Create .prettierrc:

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 80,
  "tabWidth": 2
}

3. Testing Setup​

# Install testing dependencies
npm install --save-dev jest @testing-library/react @testing-library/jest-dom

# Run tests
npm test
# or
npm run test:watch

Troubleshooting​

Common Issues​

Node.js Version Issues​

# Use nvm to manage Node.js versions
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

Permission Issues​

# Fix npm permissions on macOS/Linux
sudo chown -R $USER:$GROUP ~/.npm
sudo chown -R $USER:$GROUP ~/.config

Database Connection Issues​

# Check PostgreSQL status
sudo systemctl status postgresql

# Restart PostgreSQL
sudo systemctl restart postgresql

# Check connection
psql -h localhost -U postgres -d solverhood_dev

Port Already in Use​

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

Getting Help​

If you encounter issues:

  1. Check the logs: Look at console output and error messages
  2. Search existing issues: Check GitHub issues for similar problems
  3. Ask in community: Join our Discord or GitHub Discussions
  4. Contact support: Email support@solverhood.com

Next Steps​

Now that your development environment is set up:

  1. Create your first project
  2. Explore the API documentation
  3. Learn about best practices
  4. Join the community

Additional Resources​