Development Setup - joinruach/JoinRuach GitHub Wiki

Development Setup

Prerequisites

Before you begin, ensure you have the following installed:

Required

Recommended

  • VS Code with recommended extensions (see below)
  • Docker Desktop (for containerized databases)
  • Postman or Insomnia (API testing)

Optional

  • GitHub CLI (for faster workflow)
  • Fig or Warp (enhanced terminal experience)

Initial Setup

1. Clone the Repository

# Clone via SSH (recommended)
git clone [email protected]:ruachstudios/joinruach.git

# Or via HTTPS
git clone https://github.com/ruachstudios/joinruach.git

# Navigate into the directory
cd joinruach

2. Install Dependencies

# Install all packages
pnpm install

# Or if you prefer npm
npm install

3. Set Up Environment Variables

Copy the example environment file:

cp .env.example .env.local

Edit .env.local with your credentials:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/ruachdb"

# Authentication
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secret-key-here"

# OAuth Providers (optional)
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# Email (optional)
RESEND_API_KEY="your-resend-api-key"

# CMS (optional)
SANITY_PROJECT_ID="your-sanity-project-id"
SANITY_DATASET="production"
SANITY_API_TOKEN="your-sanity-api-token"

# AI (optional)
OPENAI_API_KEY="your-openai-api-key"

Note: Contact the team if you need access to shared development credentials.

4. Set Up the Database

Option A: Local PostgreSQL

# Create a new database
createdb ruachdb

# Run migrations
pnpm prisma migrate dev

# Seed the database (optional)
pnpm prisma db seed

Option B: Docker (Recommended)

# Start PostgreSQL container
docker run --name ruachdb \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=ruachdb \
  -p 5432:5432 \
  -d postgres:16

# Run migrations
pnpm prisma migrate dev

Verify Database Connection

pnpm prisma studio

This opens Prisma Studio at http://localhost:5555 where you can view and edit data.

5. Start the Development Server

# Start Next.js dev server
pnpm dev

Visit http://localhost:3000 to see the app running.

Project Structure

joinruach/
├── src/
│   ├── app/              # Next.js App Router pages
│   ├── components/       # React components
│   ├── lib/              # Utilities and helpers
│   ├── server/           # Backend logic (tRPC, Prisma)
│   ├── styles/           # Global styles
│   └── types/            # TypeScript types
├── prisma/
│   ├── schema.prisma     # Database schema
│   └── migrations/       # Database migrations
├── public/               # Static assets
├── tests/                # Test files
├── .env.local            # Environment variables (not committed)
├── .env.example          # Example environment file
├── package.json          # Dependencies
├── tsconfig.json         # TypeScript config
└── README.md             # Project README

Development Workflow

1. Create a New Branch

# Create and switch to a new branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/bug-description

2. Make Your Changes

Edit files in your code editor. The dev server will hot-reload automatically.

3. Run Tests

# Run unit tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run end-to-end tests
pnpm test:e2e

4. Check Code Quality

# Lint code
pnpm lint

# Format code
pnpm format

# Type-check
pnpm type-check

5. Commit Your Changes

# Stage changes
git add .

# Commit with a meaningful message
git commit -m "feat: add user authentication"

Commit Message Format:

  • feat: — New feature
  • fix: — Bug fix
  • docs: — Documentation changes
  • style: — Code style changes (formatting, etc.)
  • refactor: — Code refactoring
  • test: — Adding or updating tests
  • chore: — Maintenance tasks

6. Push and Create a Pull Request

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

Then create a Pull Request on GitHub.

VS Code Setup

Recommended Extensions

Install these extensions for the best experience:

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "prisma.prisma",
    "ms-vscode.vscode-typescript-next",
    "usernamehw.errorlens",
    "christian-kohler.path-intellisense",
    "formulahendry.auto-rename-tag"
  ]
}

Workspace 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",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

Common Commands

Development

pnpm dev          # Start dev server
pnpm build        # Build for production
pnpm start        # Start production server

Database

pnpm prisma migrate dev       # Run migrations
pnpm prisma generate          # Generate Prisma Client
pnpm prisma studio            # Open Prisma Studio
pnpm prisma db seed           # Seed the database

Code Quality

pnpm lint         # Lint code
pnpm format       # Format code
pnpm type-check   # Check TypeScript types

Testing

pnpm test         # Run all tests
pnpm test:unit    # Run unit tests
pnpm test:e2e     # Run end-to-end tests

Troubleshooting

Port 3000 Already in Use

# Kill the process using port 3000
lsof -ti:3000 | xargs kill -9

# Or use a different port
PORT=3001 pnpm dev

Database Connection Errors

# Check if PostgreSQL is running
pg_isready

# Restart PostgreSQL (if using Docker)
docker restart ruachdb

# Check your DATABASE_URL in .env.local

Prisma Client Not Found

# Regenerate Prisma Client
pnpm prisma generate

Type Errors After Pulling Changes

# Reinstall dependencies
pnpm install

# Regenerate Prisma Client
pnpm prisma generate

Hot Reload Not Working

# Clear Next.js cache
rm -rf .next

# Restart dev server
pnpm dev

Getting Help

Documentation

Community

Next Steps

Once your environment is set up:

  1. Review the Technical Stack — Understand the architecture
  2. Read Contributing Code — Learn our workflow
  3. Pick an Issue — Find something to work on
  4. Submit a PR — Ship your first contribution

"Commit your work to the Lord, and your plans will be established." — Proverbs 16:3