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
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

Skills (.claude/skills/)

Project-specific skill files with detailed patterns. Use them when the task matches:

• api-module — Adding a new API endpoint module to packages/api-client (types, module class, registry registration)
• cross-platform-pages — Building a page that needs to work in both the website (apps/frontend) and the desktop app (apps/app-frontend)
• dependency-injection — Creating or wiring up a provide/inject context for platform abstraction or deep component state sharing
• figma-mcp — Translating a Figma design into Vue components using the Figma MCP tools
• i18n-convert — Converting hardcoded English strings in Vue SFCs into the @modrinth/ui i18n system (defineMessages, formatMessage, IntlFormatted)
• multistage-modals — Building a wizard-like modal with multiple stages, progress tracking, and per-stage buttons using MultiStageModal
• tanstack-query — Fetching, caching, or mutating server data with @tanstack/vue-query (queries, mutations, invalidation, optimistic updates)

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.

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.

Skills

Project-specific skills (patterns, conventions, and implementation guides) are located in .claude/skills/. Each skill has a SKILL.md describing the pattern:

• Dependency Injection — Vue provide/inject DI layer using createContext
• Cross-Platform Pages — Shared component architecture across Nuxt and Tauri frontends
• Multistage Modals — Wizard-like modal flows with MultiStageModal
• Figma MCP — Translating Figma designs to Modrinth Vue components
• i18n Convert — Converting hard-coded strings to vue-i18n localization
• API Module — Adding new endpoint modules to @modrinth/api-client
• TanStack Query — Server state management with @tanstack/vue-query v5