Skip to main content
This guide is for contributors who want to make code changes that affect functionality, require testing, or need screenshots. You’ll need to set up a full local development environment.
For simple contributions like adding languages, quotes, or themes, check out the Basic Contributions guide.

​
Before You Start

Make sure you’ve completed the Getting Started guide to set up your development environment.

​
Technology Stack

Monkeytype is built with:
  • Frontend: TypeScript, HTML, CSS
  • Backend: Node.js
  • Database: MongoDB (user data)
  • Cache: Redis (leaderboards, jobs, OAuth state)
  • Authentication: Firebase
  • Code Quality: Oxc (Oxfmt and Oxlint)

​
Development Workflow

​
1. Fork and Clone

1

Fork the Repository

Click the Fork button on the Monkeytype repository.
2

Clone Your Fork

git clone https://github.com/YOUR_USERNAME/monkeytype.git
cd monkeytype
3

Create a Feature Branch

git checkout -b feature/your-feature-name

​
2. Make Your Changes

1

Start Development Server

# Both frontend and backend
npm run dev

# Frontend only
npm run dev-fe

# Backend only
npm run dev-be
The development server will automatically rebuild when you save changes.
2

Write Your Code

Make your changes in the src/ directory. The project structure is organized as:
  • frontend/ - Frontend application code
  • backend/ - Backend API and server code
  • packages/ - Shared packages and utilities
3

Test Your Changes

View your changes at:
Rebuilding after changes may take a moment depending on your machine’s performance. Be patient while the development server recompiles.

​
3. Code Quality

Monkeytype enforces code quality through automated tools.

​
Linting

# Lint all code
npm run lint

# Lint with auto-fix
npm run lint-fix

# Fast lint (without type checking)
npm run lint-fast

# Lint specific areas
npm run lint-fe      # Frontend only
npm run lint-be      # Backend only
npm run lint-pkg     # Packages only

​
Formatting

# Check formatting
npm run format-check

# Fix formatting
npm run format-fix

​
Pre-commit Hooks

Oxc automatically runs on every commit to format and lint your code. If there are issues, the commit will be blocked until they’re resolved.

​
4. Testing

Run tests to ensure your changes don’t break existing functionality. 
# Run all tests
npm run test

# Test specific areas
npm run test-fe      # Frontend tests
npm run test-be      # Backend tests (includes integration tests)
npm run test-pkg     # Package tests

​
5. Building

Before submitting, verify your code builds successfully. 
# Build all
npm run build

# Build specific areas
npm run build-fe     # Frontend only
npm run build-be     # Backend only
npm run build-pkg    # Packages only

​
6. Asset Validation

If you’ve modified languages, quotes, or themes, validate the JSON assets. 
# Check all assets
npm run check-assets

# Check specific asset types
npm run check-assets-quotes
npm run check-assets-languages
npm run check-assets-others

​
Working with Docker

Docker provides a consistent development environment across different operating systems.

​
Database Only

cd backend
npm run docker-db-only
This starts MongoDB and Redis in containers.

​
Full Backend

cd backend
npm run docker

​
Full Frontend

cd frontend
npm run docker

​
Firebase Development

If you’re working on authentication or user account features:

​
Initial Setup

  1. Create a Firebase project in the Firebase Console
  2. Enable Email/Password and Google authentication
  3. Configure frontend/src/ts/constants/firebase-config.ts with your project credentials

​
Backend Firebase Setup

For backend development:
  1. Go to Project Settings > Service Accounts in Firebase Console
  2. Click “Generate New Private Key”
  3. Save as backend/src/credentials/serviceAccountKey.json
Never commit serviceAccountKey.json or any Firebase credentials to the repository.

​
Database Management

​
MongoDB

Connect to your local MongoDB instance: 
mongodb://localhost:27017
Use MongoDB Compass for a visual interface.

​
Redis

Redis runs on the default port 6379 and stores:
  • Daily leaderboards
  • Background job queues (via BullMQ)
  • OAuth state parameters

​
Common Development Tasks

​
Adding a New Feature

1

Plan Your Feature

  • Discuss the feature in the #development Discord channel
  • Check if an issue exists or create one
  • Get feedback from maintainers
2

Implement

  • Create a feature branch
  • Write code following existing patterns
  • Add tests for new functionality
  • Update documentation if needed
3

Test Thoroughly

  • Test manually in your browser
  • Run automated tests
  • Test edge cases
  • Verify different configurations
4

Document

  • Add code comments for complex logic
  • Update user-facing documentation
  • Take screenshots if UI changed

​
Fixing a Bug

1

Reproduce the Bug

  • Verify the bug exists in the latest code
  • Document steps to reproduce
  • Identify the root cause
2

Fix

  • Make minimal changes to fix the issue
  • Add tests to prevent regression
  • Verify the fix works
3

Test

  • Confirm the bug is resolved
  • Check for side effects
  • Run the full test suite

​
TypeScript Tips

Monkeytype is written in TypeScript. Keep these tips in mind:
  • Use strict type checking
  • Avoid any types when possible
  • Define interfaces for complex objects
  • Use enums for fixed sets of values
  • Leverage type inference

​
Type Checking

# Run TypeScript compiler check
npm run ts-check

​
Submitting Your Changes

Once your changes are ready:
1

Commit Your Changes

git add .
git commit -m "feat: add new feature"
Follow the commit message guidelines.
2

Push to Your Fork

git push origin feature/your-feature-name
3

Create Pull Request

  1. Go to your fork on GitHub
  2. Click “Compare & pull request”
  3. Fill in the PR template
  4. Add screenshots for UI changes
  5. Reference related issues
  6. Submit the pull request

​
Pull Request Guidelines

  • Follow the PR naming conventions
  • Provide a clear description of changes
  • Include screenshots for visual changes
  • Link to related issues
  • Ensure all checks pass
  • Respond to review feedback promptly

​
Code Review Process

  1. Automated checks run on your PR (linting, tests, build)
  2. Maintainers review your code
  3. You may need to make changes based on feedback
  4. Once approved, a maintainer will merge your PR
Be patient and responsive during review. Maintainers may take time to review thoroughly.

​
Troubleshooting

​
Build Errors

  • Clear node_modules and reinstall: rm -rf node_modules && pnpm i
  • Check Node.js version: node --version (should be 24.11.0)
  • Verify pnpm version: pnpm --version (should be 10.28.1)

​
Development Server Issues

  • Kill any processes using port 3000 or 5005
  • Clear browser cache and cookies
  • Try running with sudo on UNIX systems if you get spawn errors

​
Database Connection Issues

  • Verify MongoDB and Redis are running
  • Check connection strings in .env files
  • Restart database services

​
Firebase Errors

  • Verify Firebase configuration in firebase-config.ts
  • Check authentication methods are enabled in Firebase Console
  • Ensure service account key is in the correct location

​
Getting Help

If you’re stuck:

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us