Modrinth-plus/CLAUDE.md

Modrinth Monorepo

This is the Modrinth monorepo — it contains all Modrinth projects, both frontend and backend. When entering a project, either to edit or analyse, you should read it's CLAUDE.md.

Architecture

• Monorepo tooling: Turborepo (turbo.jsonc) + pnpm workspaces (pnpm-workspace.yaml)
• Frontend: Vue 3 / Nuxt 3, Tailwind CSS v3
• Backend: Rust (Labrinth API), Postgres, Clickhouse
• Indentation: Use TAB everywhere, never spaces

Apps (apps/)

App	Description
frontend	Main Modrinth website (Nuxt 3)
app-frontend	Desktop/app frontend (Vue 3)
app	Desktop/app shell (Tauri)
app-playground	Testing playground for app
labrinth	Backend API service
daedalus_client	Daedalus client implementation
docs	Documentation site (Astro)

Packages (packages/)

Package	Description
ui	Shared Vue component library (@modrinth/ui)
assets	Styling and auto-generated icons (@modrinth/assets)
api-client	API client for Nuxt, Tauri, and Node/browser
app-lib	Shared app library
blog	Blog system and changelog data
utils	Shared utility functions (mostly deprecated)
moderation	Moderation utilities
daedalus	Daedalus protocol
tooling-config	ESLint, Prettier, TypeScript configs
ariadne	Analytics library
modrinth-log	Logging utilities
modrinth-maxmind	MaxMind GeoIP
modrinth-util	General utilities
muralpay	Payment processing
path-util	Path utilities
sqlx-tracing	SQLx query tracing

Pre-PR Commands

Run these from the root folder before opening a pull request - do not run these after each prompt the user gives you, only run when asked, ask the user a question if they want to run it if the user indicates that they are about to create a pull request.

• Website: pnpm prepr:frontend:web
• App frontend: pnpm prepr:frontend:app
• Frontend libs: pnpm prepr:frontend:lib
• All frontend (app+web): pnpm prepr
• Labrinth (backend): See apps/labrinth/CLAUDE.md

The website and app prepr commands

Dev Commands

• Website: pnpm web:dev (copy .env template in apps/frontend/ first)
• App: pnpm app:dev (copy .env template in packages/app-lib/ first)
• Storybook (packages/ui): pnpm storybook

Project-Specific Instructions

Each project may have its own CLAUDE.md with detailed instructions:

• apps/labrinth/CLAUDE.md — Backend API
• apps/frontend/CLAUDE.md - Frontend Website

Code Guidelines

Comments

• DO NOT use "heading" comments like: === Helper methods ===.
• Use doc comments, but avoid inline comments unless ABSOLUTELY necessary for clarity. Code should aim to be self documenting!

Bash Guidelines

Output handling

• DO NOT pipe output through head, tail, less, or more
• NEVER use | head -n X or | tail -n X to truncate output
• IMPORTANT: Run commands directly without pipes when possible
• IMPORTANT: If you need to limit output, use command-specific flags (e.g. git log -n 10 instead of git log | head -10)
• ALWAYS read the full output — never pipe through filters

General

• Do not create new non-source code files (e.g. Bash scripts, SQL scripts) unless explicitly prompted to
• For Frontend, when doing lint checks, only use the prepr commands, do not use typecheck or tsc etc.
• Types in @modrinth/utils are considered highly outdated, if a component needs them, check if you can switch said component to use types from packages/api-client
• When provided problems, do not say "I didn't introduce these problems" (shifting the blame/effort) - just fix them.

Edit Tool - Whitespace Handling (CLAUDE ONLY)

The Read tool uses → to mark where line numbers end and file content begins.

Rule: Copy the EXACT whitespace that appears after the → marker.

• Whatever appears between → and the code text is what's actually in the file
• That whitespace must be used EXACTLY in Edit tool's old_string
• Don't count arrows, don't interpret - just copy what's after the →

Example: 14→ private byte tag; For Edit, use: private byte tag; (copy everything after →, including the two tabs)

If Edit fails: Stop and explain the problem. Do not attempt sed/awk/bash workarounds.

IMPORTANT: Trust the Read tool output. Copy what's after → into Edit immediately. DO NOT verify with sed/od/grep first - that's wasting time and the instructions already tell you to stop if Edit fails, not to pre-verify.

Standards

Standards available at the @standards/ folder.