Development Setup

Set up your local development environment for contributing to SquirrelDisk

Development Setup

This guide will help you set up your local development environment to start contributing to SquirrelDisk.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v16 or higher)

SquirrelDisk’s frontend is built with React and Vite, which require Node.js.

Installation:

• Download from nodejs.org
• Or use a version manager like nvm or fnm

Verify installation:

node --version
npm --version

Rust (1.57 or higher)

SquirrelDisk’s backend is built with Rust. You’ll need the Rust toolchain installed.

Installation:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Verify installation:

rustc --version
cargo --version

Learn more at rust-lang.org

Tauri CLI

Tauri is the framework that bridges Rust and React in SquirrelDisk.

Installation: The Tauri CLI is included in the project’s dependencies and will be installed automatically with npm install.

Learn more at tauri.app

Platform-Specific Dependencies

Windows

• Microsoft Visual Studio C++ Build Tools: Required for Rust compilation
• Download from Visual Studio downloads
• Select “Desktop development with C++” during installation

macOS

• Xcode Command Line Tools: Required for development

xcode-select --install

Linux

Install required system libraries:

Debian/Ubuntu:

sudo apt update
sudo apt install libwebkit2gtk-4.0-dev \
  build-essential \
  curl \
  wget \
  libssl-dev \
  libgtk-3-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev

Fedora:

sudo dnf install webkit2gtk3-devel \
  openssl-devel \
  curl \
  wget \
  libappindicator-gtk3 \
  librsvg2-devel
sudo dnf group install "C Development Tools and Libraries"

Arch Linux:

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

Getting Started

1. Clone the Repository

First, fork the repository on GitHub, then clone your fork:

git clone https://github.com/YOUR_USERNAME/squirreldisk.git
cd squirreldisk

Add the upstream repository as a remote:

git remote add upstream https://github.com/adileo/squirreldisk.git

2. Install Dependencies

Install the Node.js dependencies:

npm install

This will install all required packages, including:

• React and React DOM
• Vite (build tool)
• D3.js (visualization library)
• Tauri CLI
• TypeScript and type definitions
• Tailwind CSS

Rust dependencies are managed by Cargo and will be downloaded automatically when you first build the project.

3. Run in Development Mode

Start the development server:

npm run tauri dev

This command will:

1. Start the Vite development server for the React frontend
2. Compile the Rust backend
3. Launch the SquirrelDisk application window
4. Enable hot module replacement (HMR) for frontend changes

The first build may take several minutes as Cargo downloads and compiles all Rust dependencies.

4. Making Changes

Frontend Changes

Frontend code is located in src/:

• src/components/ - React components (DiskList, DiskDetail, TitleBar, etc.)
• src/d3chart.ts - D3.js sunburst chart implementation
• src/App.tsx - Main application component
• src/main.tsx - Application entry point

Changes to React/TypeScript files will automatically reload with HMR.

Backend Changes

Backend code is located in src-tauri/src/:

• src-tauri/src/main.rs - Tauri app setup and command handlers
• src-tauri/src/scan.rs - Disk scanning logic
• src-tauri/src/window_style.rs - Native window styling

After changing Rust code, the app will automatically rebuild and restart.

Dependencies

Frontend dependencies in package.json:

npm install <package-name>

Backend dependencies in src-tauri/Cargo.toml:

[dependencies]
package-name = "version"

Then run cargo build or restart npm run tauri dev.

5. Building for Production

Create a production build:

npm run tauri build

This will:

1. Build the React frontend for production (TypeScript compilation + Vite build)
2. Compile the Rust backend with optimizations
3. Create platform-specific installers in src-tauri/target/release/:
   • Windows: .exe and .msi installers
   • macOS: .dmg and .app bundle
   • Linux: .deb, .appimage, and other formats

Production builds take significantly longer than development builds due to optimization passes.

Project Structure

Here’s an overview of the project structure:

squirreldisk/
├── src/                          # Frontend source code (React + TypeScript)
│   ├── components/               # React components
│   │   ├── DiskList.tsx         # Disk selection list
│   │   ├── DiskDetail.tsx       # Disk detail view with chart
│   │   ├── DiskItem.tsx         # Individual disk item
│   │   ├── FileLine.tsx         # File list item
│   │   ├── TitleBar.tsx         # Custom window title bar
│   │   └── ParentFolder.tsx     # Parent folder navigation
│   ├── assets/                  # Images and icons
│   ├── d3chart.ts              # D3.js sunburst chart logic
│   ├── pruneData.ts            # Data processing utilities
│   ├── App.tsx                 # Main app component
│   └── main.tsx                # Entry point
├── src-tauri/                   # Backend source code (Rust + Tauri)
│   ├── src/
│   │   ├── main.rs             # Tauri setup and commands
│   │   ├── scan.rs             # Disk scanning implementation
│   │   └── window_style.rs     # Window styling (shadows, rounded corners)
│   ├── Cargo.toml              # Rust dependencies
│   ├── tauri.conf.json         # Tauri configuration
│   └── icons/                  # Application icons
├── public/                      # Static assets
├── package.json                # Node.js dependencies and scripts
├── tsconfig.json               # TypeScript configuration
├── vite.config.ts              # Vite configuration
├── tailwind.config.cjs         # Tailwind CSS configuration
└── README.md                   # Project readme

Common Development Tasks

Opening DevTools

To debug the frontend, uncomment this line in src-tauri/src/main.rs:

window.open_devtools();

Then restart the app. The Chrome DevTools will open automatically.

Viewing Rust Logs

Rust logs are printed to the terminal where you ran npm run tauri dev.

Add logging with:

println!("Debug message: {:?}", variable);

Running Rust Tests

Run Rust tests from the src-tauri directory:

cd src-tauri
cargo test

Checking Code Style

TypeScript/React:

npm run build

This runs TypeScript type checking.

Rust:

cd src-tauri
cargo clippy
cargo fmt --check

Updating Dependencies

Frontend:

npm update

Backend:

cd src-tauri
cargo update

Troubleshooting

Build Fails on First Run

Solution:

• Ensure all prerequisites are installed correctly
• On Linux, double-check that all system libraries are installed
• Try cargo clean in the src-tauri directory and rebuild
• Check the Tauri prerequisites guide

Hot Reload Not Working

Solution:

• Restart the development server
• Check for TypeScript errors in the terminal
• Clear Vite cache: rm -rf node_modules/.vite

Rust Compilation Errors

Solution:

• Update Rust: rustup update
• Clear Cargo cache: cargo clean in src-tauri/
• Ensure you’re using Rust 1.57 or higher

Missing Dependencies

Solution:

• Delete node_modules and run npm install again
• Delete src-tauri/target and rebuild
• Check that your Node.js version is compatible (v16+)

Next Steps

Architecture

Learn about SquirrelDisk’s architecture and how components interact

Find Issues

Browse open issues and find something to work on