Development Setup

This guide will help you set up your development environment to contribute to Deadlock Mod Manager. The project is a monorepo built with modern tools and technologies.

Prerequisites

Before you begin, ensure you have the following tools installed:

Required Tools

Node.js (>= 24.8.0)

Download from nodejs.org or use a version manager:

# Using nvm (recommended)
nvm install 24
nvm use 24

# Using fnm
fnm install 24
fnm use 24

pnpm (>= 10.18.2)

Install the package manager:

npm install -g pnpm

# Verify installation
pnpm --version

Rust (Latest Stable)

Required for the Tauri desktop application:

# Install rustup (Rust installer)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Windows: Download from https://rustup.rs/
# Follow the installation prompts

# Verify installation
rustc --version
cargo --version

Docker

For local database development:

• Windows: Docker Desktop
• Linux: Docker Engine

# Verify installation
docker --version
docker compose --version

Platform-Specific Requirements

Windows

• Visual Studio Build Tools or Visual Studio Community with C++ support
• Windows 10 SDK (automatically installed with VS Build Tools)

Linux

Install system dependencies:

# Ubuntu/Debian
sudo apt update
sudo apt install -y \
    libwebkit2gtk-4.1-dev \
    libappindicator3-dev \
    librsvg2-dev \
    patchelf \
    build-essential \
    curl \
    wget \
    file \
    libssl-dev \
    libgtk-3-dev \
    libayatana-appindicator3-dev

# Arch Linux
sudo pacman -S \
    webkit2gtk-4.1 \
    gtk3 \
    librsvg \
    base-devel \
    curl \
    wget \
    file \
    openssl \
    appmenu-gtk-module \
    gtk3-print-backends \
    libappindicator-gtk3

# Fedora
sudo dnf install -y \
    webkit2gtk4.1-devel \
    gtk3-devel \
    librsvg2-devel \
    openssl-devel \
    curl \
    wget \
    file \
    libappindicator-gtk3-devel

Project Setup

1. Fork and Clone

1. Fork the repository on GitHub: deadlock-modmanager

2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/deadlock-modmanager.git
   cd deadlock-modmanager

2. Install Dependencies

Install all project dependencies:

# Install all dependencies for the monorepo
pnpm install

# This will install dependencies for all packages and apps

3. Environment Configuration

Copy the example environment file and configure it:

# Copy the example environment file
cp env.example .env

# Edit the file with your preferred editor
cursor .env # Cursor
code .env   # VS Code
nano .env   # Terminal editor

Required Environment Variables:

# Database configuration
DATABASE_URL=postgresql://turborepo:123456789@localhost:5435/turborepo
NODE_ENV=development

# Optional services (can be left empty for basic development)
REDIS_URL=redis://localhost:6379
SENTRY_DSN=your_sentry_dsn_here # you can put whatever text you want here

# API configuration (optional)
PORT=3001
HOST=localhost

4. Database Setup

Prefer managed Postgres?

For self-hosted deployments, or if you'd rather not run Postgres locally, we recommend Neon: serverless Postgres with a generous free tier and a proud sponsor of this project. Point DATABASE_URL at your Neon connection string and skip the Docker step below.

Start the development database using Docker:

# Start PostgreSQL and Redis containers
docker compose up -d

# Verify containers are running
docker compose ps

Apply the database schema:

# Push the database schema
pnpm db:push

# Optional: Seed with initial data
pnpm db:seed

5. Build VPK Analyzer

# Analyzer is needed for local API
pnpm vpk-parser:build

6. Verify Installation

Test that everything is working:

# Run type checking
pnpm check-types

# Run linting
pnpm lint

# Build all packages (this may take a while first time)
pnpm build

Development Commands

Core Commands

Quality Assurance

Database Commands

Build Commands

Development Workflow

1. Starting Development

For desktop app development (most common):

# Start the API server (in one terminal)
pnpm api:dev

# Start the desktop app (in another terminal)
pnpm desktop:dev

Impeccable is installed as a repository-local skill in .agents/skills/impeccable with project context in .agents/context. Run pnpm impeccable:detect for a fast static pass over the desktop UI.

For web development:

# Start the web app
pnpm www:dev

For documentation development:

# Start the docs site
pnpm docs:dev

2. Making Changes

1. Create a feature branch:

   git checkout -b feature/your-feature-name

2. Make your changes following the coding style guidelines

3. Test your changes:

   pnpm lint:Fix
   pnpm format:Fix
   pnpm check-types
   pnpm test  # If tests exist for your changes

4. Commit your changes:

   git add .
   git commit -m "feat: add your feature description"

3. Staying Updated

Keep your fork synchronized with the upstream repository:

# Fetch latest changes
git fetch upstream

# Merge upstream changes into your main branch
git checkout main
git merge upstream/main

# Push updates to your fork
git push origin main

IDE Configuration

Cursor / VS Code (Recommended)

The project includes VS Code configuration with recommended extensions:

1. Install recommended extensions when prompted
2. Enable format on save (already configured in workspace settings)
3. Use the integrated terminal for running commands

Recommended Extensions:

• Rust Analyzer
• Tauri
• TypeScript and JavaScript Language Features
• Tailwind CSS IntelliSense
• Biome (for linting/formatting)

Other IDEs

The project should work with any IDE that supports:

• TypeScript/JavaScript
• Rust
• EditorConfig
• Biome

CEF (Chromium Embedded Framework) Development

The desktop app supports an optional CEF runtime as an alternative to the system WebView (Wry). CEF builds use a forked Tauri CLI from the feat/cef branch.

CEF Setup

Install the CEF-enabled Tauri CLI (one-time, replaces the standard cargo-tauri):

pnpm --filter desktop cef:setup

CEF Commands

How It Works

The cef-patch.ts script injects a [patch.crates-io] block into Cargo.toml pointing Tauri dependencies at the feat/cef branch, and adds a cef feature flag. The --features cef flag must be passed both to the Tauri CLI (before --) for correct bundling, and to cargo (after --) for compilation.

On first build, the CEF binary distribution (~300MB) is downloaded automatically to your local cache directory. Subsequent builds reuse the cached binaries.

Verifying a CEF Build

A correctly bundled CEF NSIS installer will be significantly larger than a Wry build (~300MB vs ~21MB) because it includes libcef.dll and the full CEF redistribution. If the installer size is similar to the Wry build, CEF files were not bundled correctly.

Troubleshooting

Common Issues

"Command not found" errors

# Ensure pnpm is installed globally
npm install -g pnpm

# Refresh your shell
source ~/.bashrc  # or ~/.zshrc

Rust compilation errors

# Update Rust to latest stable
rustup update stable

# Clear Rust cache
cargo clean

# For Linux: ensure system dependencies are installed

Database connection issues

# Restart Docker containers
docker compose down
docker compose up -d

# Check container logs
docker logs postgres

Port conflicts

# Check what's running on ports
lsof -i :3001  # API port
lsof -i :3000  # Web port
lsof -i :1420  # Tauri dev port

# Kill processes if needed
kill -9 <PID>

Getting Help

If you encounter issues:

Next Steps

Once your development environment is set up: