Getting Started

Set up your development environment for Modrinth

Prerequisites

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

Required Tools

Node.js

Version: 20.x or higher

Download Node.js

Verify installation:

node --version

pnpm

Version: 9.15.0

Install globally:

npm install -g pnpm@9.15.0

Verify installation:

pnpm --version

Rust

Version: 1.90.0 or higher (Edition 2024)

Install Rust

Verify installation:

rustc --version
cargo --version

Docker

For local services (PostgreSQL, Redis, ClickHouse, etc.)

Download Docker

Verify installation:

docker --version
docker compose version

Optional Tools

Tauri Prerequisites (for Desktop App)

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

Development 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