Skip to main content

​
Prerequisites

Before you begin developing for Modrinth, ensure you have the following tools installed:

​
Required Tools

Node.js

Version: 20.x or higherDownload Node.jsVerify installation:
node --version

pnpm

Version: 9.15.0Install globally:
npm install -g [email protected]
Verify installation:
pnpm --version

Rust

Version: 1.90.0 or higher (Edition 2024)Install RustVerify installation:
rustc --version
cargo --version

Docker

For local services (PostgreSQL, Redis, ClickHouse, etc.)Download DockerVerify installation:
docker --version
docker compose version

​
Optional Tools

If you plan to work on the desktop app, follow the Tauri prerequisites guide for your platform:macOS: Xcode Command Line Tools
xcode-select --install
Linux: Additional system dependencies
sudo apt install libwebkit2gtk-4.1-dev \
  build-essential curl wget file libssl-dev \
  libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev
Windows: Microsoft Visual Studio C++ Build Tools
Recommended IDE extensions:
  • VS Code: Rust Analyzer, Vue Language Features (Volar), ESLint, Prettier
  • IntelliJ IDEA: Rust plugin, Vue.js plugin
  • Rust Tools: rustfmt, clippy (installed with Rust)

​
Cloning the Repository

1

Clone the Repository

Clone the Modrinth monorepo to your local machine:
git clone https://github.com/modrinth/code.git
cd code
Or if you’ve forked it:
git clone https://github.com/YOUR_USERNAME/code.git
cd code
2

Check Node Version

The repository includes a .nvmrc file. If you use nvm:
nvm use
This will automatically use Node.js version specified in .nvmrc.

​
Installing Dependencies

1

Install JavaScript Dependencies

Install all frontend dependencies using pnpm:
pnpm install
This will install dependencies for all packages in the monorepo workspace.
2

Install Rust Dependencies

Rust dependencies are managed by Cargo and will be downloaded automatically when you build.Verify Rust toolchain:
rustc --version
# Should show 1.90.0 or higher

​
Running Development Servers

​
Web Interface (Frontend)

1

Copy Environment File

Navigate to the frontend directory and copy the environment template:
cd apps/frontend
cp .env.local .env
The .env.local file contains default development settings.
2

Start Development Server

From the root directory, run:
pnpm web:dev
The web interface will be available at http://localhost:3000

​
Desktop App

1

Copy Environment File

Navigate to the app-lib directory and copy the environment template:
cd packages/app-lib
cp .env.local .env
2

Start Development Server

From the root directory, run:
pnpm app:dev
This will compile the Rust backend (Theseus) and launch the Tauri app with hot-reloading for the Vue frontend.
The first build of the desktop app may take several minutes as Cargo compiles all dependencies.

​
Backend API (Labrinth)

See the Local Setup guide for detailed instructions on running Labrinth with all required services.

​
UI Component Library (Storybook)

pnpm storybook
Storybook will be available at http://localhost:6006 for developing and testing UI components.

​
Verify Your Setup

Run these commands to verify everything is working: 
# Check that all packages build
pnpm build

# Run linters
pnpm lint

# Run tests
pnpm test
If you encounter any errors, check that:
  • All prerequisites are installed
  • You’re using the correct Node.js version
  • You ran pnpm install from the root directory
  • Docker is running (if testing Labrinth)

​
Making Your First Contribution

Now that your environment is set up:
1

Find an Issue

Browse the issue tracker for issues labeled good first issue or help wanted.
2

Create a Branch

Create a new branch for your work:
git checkout -b feature/your-feature-name
3

Make Changes

Edit the code, following our Code Style guidelines.
4

Test Locally

Test your changes in the development server:
# For web changes
pnpm web:dev

# For app changes
pnpm app:dev
5

Run Pre-PR Checks

Before submitting a PR:For Frontend:
pnpm prepr
For Labrinth:
cd apps/labrinth
cargo clippy -p labrinth --all-targets
cargo sqlx prepare
6

Commit and Push

Commit your changes with a clear message:
git add .
git commit -m "feat: add description of your changes"
git push origin feature/your-feature-name
7

Create Pull Request

Go to GitHub and create a pull request from your branch.

​
Development Commands Reference

# Frontend development
pnpm web:dev              # Run web interface
pnpm app:dev              # Run desktop app
pnpm storybook            # Run component library

# Build commands
pnpm web:build            # Build web interface
pnpm app:build            # Build desktop app
pnpm build                # Build all packages

# Code quality
pnpm lint                 # Run linters
pnpm fix                  # Auto-fix linting issues
pnpm test                 # Run all tests

# Pre-PR checks
pnpm prepr                # All frontend checks
pnpm prepr:frontend:web   # Web only
pnpm prepr:frontend:app   # App only
pnpm prepr:frontend:lib   # Shared libraries only

​
Next Steps

Code Style

Learn about formatting, naming conventions, and commit messages

Architecture

Understand the monorepo structure and technology stack

Local Setup

Set up Labrinth backend with Docker services

Contributing

Read the full contribution guidelines

​
Getting Help

If you run into issues:
  • Check the README files in specific app/package directories
  • Join the Discord server and ask in #development
  • Open an issue on GitHub
  • Review the CLAUDE.md files for project-specific instructions