Building from Source

Building from Source

This guide walks you through building MiniFy from source code, whether you’re contributing to the project or creating a custom build.

Build Overview

┌───────────────────────────────────────────────────────────────────────────────┐
│                              Build Pipeline                                    │
├───────────────────────────────────────────────────────────────────────────────┤
│                                                                                │
│   Source Code                   Build Process                    Output        │
│   ────────────                  ─────────────                    ──────        │
│                                                                                │
│   ┌──────────────┐             ┌──────────────┐               ┌────────────┐  │
│   │  React/TS    │─── Vite ───▶│   Bundled    │               │            │  │
│   │  Frontend    │             │   JS/CSS     │───┐           │  Platform  │  │
│   └──────────────┘             └──────────────┘   │           │  Specific  │  │
│                                                    │─ Tauri ─▶│  Installer │  │
│   ┌──────────────┐             ┌──────────────┐   │           │            │  │
│   │   Rust       │─── Cargo ──▶│   Native     │───┘           │  .msi      │  │
│   │   Backend    │             │   Binary     │               │  .dmg      │  │
│   └──────────────┘             └──────────────┘               │  .deb      │  │
│                                                                └────────────┘  │
│                                                                                │
└────────────────────────────────────────────────────────────────────────────────┘

Prerequisites

All Platforms

Ensure you have the following installed:

Tool	Version	Installation
Node.js	20.19.0+	nodejs.org
pnpm	9+	npm install -g pnpm
Rust	Latest stable	rustup.rs
Git	Any recent	git-scm.com

Verify installations:

node --version   # Should be 20.19.0 or higher
pnpm --version   # Should be 9.x or higher
rustc --version  # Should be 1.70.x or higher
cargo --version  # Should match rustc version

Platform-Specific Requirements

Windows

Microsoft Visual Studio Build Tools

Required for compiling native Rust code:

# Using winget
winget install Microsoft.VisualStudio.2022.BuildTools

# Or download from:
# https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022

During installation, select:

• “Desktop development with C++”

WebView2 Runtime

Usually pre-installed on Windows 10/11. If not:

• Download from Microsoft

macOS

Xcode Command Line Tools

xcode-select --install

This provides:

• C/C++ compiler (clang)
• Development headers
• Build utilities

Note

Full Xcode is not required - just the Command Line Tools.

Linux

Debian/Ubuntu:

sudo apt update
sudo apt install -y \
  libwebkit2gtk-4.1-dev \
  build-essential \
  curl \
  wget \
  file \
  libxdo-dev \
  libssl-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev

Fedora:

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

Arch Linux:

sudo pacman -S --needed \
  webkit2gtk-4.1 \
  base-devel \
  curl \
  wget \
  file \
  openssl \
  appmenu-gtk-module \
  libappindicator-gtk3 \
  librsvg

Clone and Setup

1. Clone the repository

   git clone https://github.com/ModioStudio/MiniFy.git
   cd MiniFy

2. Install dependencies

   pnpm install

   This installs dependencies for all workspace packages:

   • apps/desktop - Desktop application
   • apps/www - Marketing website
   • apps/docs - Documentation site

Development Build

Run the desktop app in development mode with hot reload:

pnpm desktop:dev

This command:

1. Starts the Vite development server (port 1420)
2. Compiles the Rust backend in debug mode
3. Opens the development window
4. Enables hot module replacement (HMR) for React

┌───────────────────────────────────────────────────────────────────────────────┐
│                          Development Mode                                      │
├───────────────────────────────────────────────────────────────────────────────┤
│                                                                                │
│   Terminal Output:                                                             │
│                                                                                │
│   $ pnpm desktop:dev                                                          │
│                                                                                │
│   > @minify/desktop@0.1.0 dev                                                 │
│   > tauri dev                                                                 │
│                                                                                │
│        Info Watching for file changes...                                      │
│   ┌──────────────────────────────────────────┐                               │
│   │  VITE v5.x.x  ready in 500ms            │                               │
│   │  ➜  Local:   http://localhost:1420/     │                               │
│   └──────────────────────────────────────────┘                               │
│                                                                                │
│   Compiling minify v0.1.0...                                                  │
│   Finished `dev` profile [unoptimized + debuginfo]                           │
│                                                                                │
│   [Window opens with MiniFy application]                                      │
│                                                                                │
└────────────────────────────────────────────────────────────────────────────────┘

Tip

Hot Reload Behavior:

• Frontend (React) changes: Instant reload
• Rust backend changes: Requires rebuild (~10-30 seconds)
• Theme JSON changes: Requires app restart

Development with DevTools

Open the WebView DevTools for debugging:

# Press F12 in the app window
# Or right-click → Inspect Element

Production Build

Build optimized installers for distribution:

pnpm desktop:build

This creates platform-specific installers:

Output Locations

apps/desktop/src-tauri/target/release/bundle/
├── msi/                    # Windows installer
│   └── MiniFy_x.x.x_x64.msi
├── nsis/                   # Windows NSIS installer
│   └── MiniFy_x.x.x_x64-setup.exe
├── dmg/                    # macOS disk image
│   └── MiniFy_x.x.x_x64.dmg
├── macos/                  # macOS app bundle
│   └── MiniFy.app
├── deb/                    # Debian package
│   └── minify_x.x.x_amd64.deb
├── rpm/                    # Red Hat package
│   └── minify-x.x.x.x86_64.rpm
└── appimage/               # Universal Linux
    └── MiniFy_x.x.x_amd64.AppImage

Build with Embedded Client ID

For official releases, embed the Spotify Client ID at build time:

SPOTIFY_CLIENT_ID=your_client_id pnpm desktop:build

Caution

Never commit Client IDs to version control. Use environment variables or CI/CD secrets.

All Build Scripts

Script	Description
pnpm desktop:dev	Run desktop app in development mode
pnpm desktop:build	Build desktop app for production
pnpm desktop:clear	Clear all stored credentials (for testing)
pnpm www:dev	Run website in development mode
pnpm www:build	Build website for production
pnpm docs:dev	Run documentation in development mode
pnpm docs:build	Build documentation for production
pnpm build	Build all packages
pnpm dev	Run all packages in development mode
pnpm check	Run Biome linter and formatter check with safe fixes
pnpm lint	Run workspace lint
pnpm test	Run quality gates
pnpm format	Format all code with Biome

Environment Variables

Development

Create a .env file in apps/desktop/ for development:

# Optional: Custom Spotify Client ID for development
VITE_SPOTIFY_CLIENT_ID=your_development_client_id

Production

For production builds, set environment variables before building:

# Required for official releases
SPOTIFY_CLIENT_ID=production_client_id

# Optional: Enable debug logging
RUST_LOG=debug

CI/CD Secrets

For GitHub Actions, set these repository secrets:

Secret	Purpose
SPOTIFY_CLIENT_ID	Embedded in production builds
APPLE_SIGNING_IDENTITY	macOS code signing (optional)
APPLE_ID	macOS notarization (optional)
WINDOWS_CERTIFICATE	Windows code signing (optional)

Troubleshooting

Rust Compilation Fails

# Update Rust to latest stable
rustup update stable

# Clean Cargo cache and rebuild
cd apps/desktop/src-tauri
cargo clean
cd ../../..
pnpm desktop:dev

Node Module Issues

# Remove all node_modules and reinstall
rm -rf node_modules
rm -rf apps/*/node_modules
pnpm install

Tauri CLI Issues

# Update Tauri CLI
pnpm add -D @tauri-apps/cli@latest -w

# Or reinstall
pnpm remove @tauri-apps/cli
pnpm add -D @tauri-apps/cli

Platform-Specific Issues

Windows

“LINK : fatal error LNK1181”

• Install Visual Studio Build Tools with C++ support
• Restart your terminal after installation

WebView2 not found

• Download and install WebView2 from Microsoft
• Restart after installation

macOS

“xcrun: error: invalid active developer path”

xcode-select --install

Code signing issues

• For development, signing is not required
• For distribution, see Tauri signing docs

Linux

“webkit2gtk not found”

# Check if installed
pkg-config --modversion webkit2gtk-4.1

# Install if missing (Debian/Ubuntu)
sudo apt install libwebkit2gtk-4.1-dev

“libayatana-appindicator not found”

sudo apt install libayatana-appindicator3-dev

Build Performance

For faster builds during development:

# Use incremental compilation (default in dev mode)
pnpm desktop:dev

# For production, use release profile optimization
pnpm desktop:build

Cross-Compilation

Tauri supports limited cross-compilation. For best results, build on each target platform:

Build On	Can Target
Windows	Windows only
macOS	macOS only
Linux	Linux only

For multi-platform releases, use GitHub Actions with matrix builds:

jobs:
  build:
    strategy:
      matrix:
        include:
          - platform: windows-latest
          - platform: macos-latest
          - platform: ubuntu-22.04

Next Steps

Architecture

Understand the codebase →

Contributing

Submit your changes →

Desktop Overview

Learn about features →