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

> Discover the essential prerequisites for running Tolaria. Install Node.js, pnpm, Rust, and git CLI. Learn about Linux specific requirements like WebKit2GTK for a smooth setup.

- Repository: [Refactoring/tolaria](https://github.com/refactoringhq/tolaria)
- Tags: how-to-guide
- Published: 2026-05-04

---

**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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/pnpm-lock.yaml) and npm scripts defined in [`package.json`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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:

```bash

# 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`](https://github.com/refactoringhq/tolaria/blob/main/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):
   ```bash
   pnpm dev
   ```

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

2. **Desktop mode** (full Tauri application):
   ```bash
   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`](https://github.com/refactoringhq/tolaria/blob/main/pnpm-lock.yaml) file and scripts in [`package.json`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/docs/GETTING-STARTED.md) (lines 34-44) for specific troubleshooting steps regarding older AppImage builds and Wayland compatibility flags.