Skip to main content
This guide will help you set up a local development environment for Monkeytype. Follow these steps if you need to test functionality changes, take screenshots, or work on features that require the full application stack.
If you only want to add languages, quotes, or themes without running the application locally, check out the Basic Contributions guide instead.

​
Prerequisites

Before you begin, ensure you have:
  • A computer with a stable internet connection
  • A text editor or IDE
  • Basic familiarity with Git and command line tools
  • Node.js version 24.11.0 LTS

​
Git Setup

Windows users: Run git config --global core.autocrlf false before cloning the repository to prevent CRLF errors.
Git is optional but highly recommended for contributing to Monkeytype. If you’re not comfortable with command-line Git, consider using Sourcetree, which provides a graphical interface. When installing Sourcetree, make sure to select the option to install Git alongside it.

​
Node.js and PNPM

Monkeytype currently uses Node.js version 24.11.0 LTS. Using nvm (recommended): 
nvm install 24.11.0
nvm use 24.11.0
Windows users should use nvm-windows.
Alternative: Download directly from the Node.js website. Install pnpm: Monkeytype uses pnpm for package management instead of npm or yarn: 
npm i -g [email protected]

​
Installation

1

Fork the Repository

Go to the Monkeytype repository and click the “Fork” button in the top-right corner to create your own copy.
2

Clone Your Fork

Clone your forked repository to your local machine:
git clone https://github.com/YOUR_USERNAME/monkeytype.git
cd monkeytype
3

Install Dependencies

Install all project dependencies:
pnpm i
4

Configure Firebase (Optional)

Skip this step if you won’t be working with the account system. You can always set it up later.
  1. Create a Firebase project
  2. Enable Firebase Authentication:
    • Go to Build > Authentication > Sign-in method
    • Enable Email/Password and Google sign-in
  3. Install Firebase CLI: 
    pnpm add -g firebase-tools
firebase login
  4. Configure Firebase in the frontend:
    • Duplicate frontend/src/ts/constants/firebase-config-example.ts
    • Rename to firebase-config.ts
    • Add your Firebase config from Project Settings > General > Your apps
  5. Set up .firebaserc:
    • Duplicate frontend/.firebaserc_example to .firebaserc
    • Update the project ID:
    {
  "projects": {
    "default": "your-firebase-project-id"
  }
}
5

Set Up Databases (Optional)

Only required if you’re working on the backend or account system.
  1. Copy backend/example.env to backend/.env
  2. Set up the database server:
Option 1: Docker (Recommended)Install Docker and run:
npm run docker-db-only
Option 2: Manual Installation
  1. (Optional) Install MongoDB Compass for visual database management
    • Connect using: mongodb://localhost:27017

​
Running Monkeytype Locally

You can run Monkeytype manually or with Docker.

​
Running Both Frontend and Backend

npm run dev
This starts:

​
Running Frontend Only

Manual: 
npm run dev-fe
Docker: 
cd frontend && npm run docker

​
Running Backend Only

Manual: 
npm run dev-be
Docker: 
cd backend && npm run docker
The development server automatically rebuilds when you make changes in the src/ directory. Rebuilding may take a moment depending on your machine.
Use Ctrl+C to stop the development servers.

​
Network Access (Optional)

To access the frontend from other devices on your network, create frontend/.env: 
BACKEND_URL="http://<Your IP>:5005"

​
Other Useful Commands

​
Linting and Formatting

# Lint all code
npm run lint

# Lint with auto-fix
npm run lint-fix

# Format check
npm run format-check

# Format fix
npm run format-fix

​
Testing

# Run all tests
npm run test

# Test frontend only
npm run test-fe

# Test backend only
npm run test-be

​
Building

# Build all
npm run build

# Build frontend only
npm run build-fe

# Build backend only
npm run build-be

​
Code Quality

Monkeytype uses Oxc (Oxfmt and Oxlint) for code formatting and linting. These tools run automatically when you make a commit via Git hooks.

​
Next Steps

​
Getting Help

If you have questions or run into issues:

Build docs developers (and LLMs) love

Get started for freeTalk to us