Prerequisites for Running Tolaria: Complete Setup Guide for Node.js, Rust, and Tauri

To run Tolaria, you must install Node.js ≥18, pnpm, Rust ≥1.77.2, and the git CLI; Linux desktop builds additionally require WebKit2GTK 4.1 system libraries and related development headers.

Tolaria is a modern note-taking application built with React and Tauri that runs in the browser with mock data or as a native desktop application. Before compiling the project, you need to satisfy specific prerequisites for running Tolaria that cover both the JavaScript frontend toolchain and the Rust backend environment. This guide details the exact versions, system libraries, and verification steps required according to the official docs/GETTING-STARTED.md and source configuration files.

Core Software Stack

Node.js Runtime and Package Manager

The frontend codebase in src/ relies on Node.js ≥18 to power the React/TypeScript application, Vite bundler, Playwright end-to-end tests, and the optional MCP bridge. According to docs/GETTING-STARTED.md (lines 7-8), this version provides the JavaScript runtime necessary for modern ECMAScript features used throughout the project.

The repository strictly uses pnpm as its package manager, evidenced by the presence of pnpm-lock.yaml and npm scripts defined in package.json (lines 27-80). Using npm or yarn will not correctly resolve the dependency tree.

Rust Compiler for the Tauri Backend

Tolaria's desktop functionality depends on Rust ≥1.77.2 to compile the native backend located in src-tauri/. The src-tauri/Cargo.toml defines the crate configuration and Rust toolchain requirements. This backend exposes commands—such as vault scanning and Git operations—that the frontend invokes via Tauri's invoke() API.

Git Command Line Interface

Unlike many applications that use Git libraries, Tolaria calls the external git CLI directly for core functionality including cloning vaults, committing changes, pushing to remotes, and conflict resolution. The Git integration implementation in src-tauri/src/git/ requires the git binary to be accessible in your system's $PATH. As noted in docs/GETTING-STARTED.md (lines 9-10), this is mandatory for the sync features to function.

Linux-Specific System Libraries

WebKit2GTK and Build Dependencies

When running the Tauri desktop application on Linux, you must install WebKit2GTK 4.1 and associated development libraries because Tauri v2 uses WebKit as its rendering engine. According to docs/GETTING-STARTED.md (lines 13-30), the following packages are required on Debian/Ubuntu systems:

• libwebkit2gtk-4.1-dev
• build-essential (or base-devel on Arch)
• libssl-dev, libayatana-appindicator3-dev
• librsvg2-dev, libsoup-3.0-dev
• patchelf

These libraries provide the GTK-based web view and system tray integration necessary for src-tauri/src/lib.rs to initialize the application window.

Optional Wayland Configuration

Some older AppImage builds may encounter compositing issues under Wayland. The documentation suggests setting environment variables to disable problematic rendering paths, though this is only required for specific legacy builds (see docs/GETTING-STARTED.md, lines 34-44).

Installation Commands

Complete the setup by installing dependencies in sequence. The following commands install system libraries (Debian/Ubuntu example), Node.js, pnpm, and Rust, then verify the installation:

# Install Linux system prerequisites (Debian/Ubuntu)

sudo apt install \
  libwebkit2gtk-4.1-dev build-essential curl wget file \
  libxdo-dev libssl-dev libayatana-appindicator3-dev \
  librsvg2-dev libsoup-3.0-dev patchelf

# Install Node.js 18+ and pnpm

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
npm i -g pnpm

# Install Rust via rustup

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Verify git installation

git --version

# Clone repository and install JavaScript dependencies

git clone https://github.com/refactoringhq/tolaria.git
cd tolaria
pnpm install

These steps follow the Quick-Start section in docs/GETTING-STARTED.md (lines 50-66).

Running the Application

Once dependencies are installed, you can run Tolaria in two modes:

1. Browser mode (mock data only, no Rust required):

   pnpm dev

   This starts the Vite development server at http://localhost:5173.

2. Desktop mode (full Tauri application):

   pnpm tauri dev

   This compiles the Rust backend in src-tauri/ and launches the native window.

Summary

• Node.js ≥18 and pnpm are mandatory for the React frontend, Vite bundler, and testing tools.
• Rust ≥1.77.2 compiles the Tauri backend in src-tauri/ to create the native desktop binary.
• Git CLI must be available in $PATH because src-tauri/src/git/ modules invoke external git commands for vault synchronization.
• Linux users need WebKit2GTK 4.1 development libraries (libwebkit2gtk-4.1-dev, libsoup-3.0-dev, etc.) to support the Tauri web view.
• Install dependencies with pnpm install and run via pnpm dev (web) or pnpm tauri dev (desktop).

Frequently Asked Questions

Do I need Rust to run the web version of Tolaria?

No. If you only intend to run the browser-based version using mock data, you only need Node.js ≥18 and pnpm. Execute pnpm dev to start the Vite server without compiling any Rust code. The Rust toolchain is only required when running pnpm tauri dev to build the native desktop application.

Why does Tolaria require the system git binary instead of a library?

Tolaria's Git integration in src-tauri/src/git/ spawns external processes using the system git command to perform operations like cloning vaults, committing changes, and resolving merge conflicts. This design ensures compatibility with all Git authentication methods and remote protocols, but it requires the git CLI to be installed and accessible in your environment.

Can I use npm or yarn instead of pnpm?

No. The repository contains a pnpm-lock.yaml file and scripts in package.json that assume pnpm-specific features. Using npm or yarn may result in dependency resolution errors or missing scripts. Install pnpm globally via npm i -g pnpm before running pnpm install.

What if I encounter Wayland rendering issues on Linux?

If the desktop application displays rendering artifacts or crashes on Wayland, you may need to set environment variables to disable problematic compositing paths. Consult docs/GETTING-STARTED.md (lines 34-44) for specific troubleshooting steps regarding older AppImage builds and Wayland compatibility flags.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}