Skip to main content
This guide walks you through setting up a local development environment for Philo.

​
Prerequisites

Before you begin, ensure you have the following installed:

​
Required Tools

  • Node.js (v18 or later)
  • Bun (package manager) - Install Bun
  • Rust (stable toolchain) - Required for Tauri backend

​
Platform-Specific Dependencies

No additional dependencies required. Xcode Command Line Tools are recommended:
xcode-select --install

​
Installation

1

Clone the repository

Clone the Philo repository and initialize submodules:
git clone https://github.com/your-org/philo.git
cd philo
git submodule update --init --recursive
Philo uses a git submodule at vendor/hyprnote for editor styling and file-saving mechanisms.
2

Install dependencies

Install all JavaScript dependencies using Bun:
bun install --frozen-lockfile
3

Verify Rust setup

Verify that Rust and Cargo are properly installed:
cargo --version
rustc --version
4

Run the development server

Start the development server:
bun run dev
This will:
  • Start Vite dev server for the React frontend
  • Launch the Tauri app in development mode
  • Enable hot module replacement (HMR)

​
Development Commands

Here are the most commonly used development commands:

​
Frontend Development

# Start development server
bun run dev

# Type-check TypeScript files
bun run typecheck

# Format code with dprint
bun run fmt

# Check formatting without modifying files
bun run fmt:check

# Build frontend for production
bun run build

​
Rust Development

# Check Rust code for errors
cd src-tauri && cargo check

# Run clippy linter
cd src-tauri && cargo clippy

# Format Rust code
cd src-tauri && cargo fmt

# Check Rust formatting
cd src-tauri && cargo fmt --check

# Run tests
cd src-tauri && cargo test

​
Combined Checks

Run type checking and formatting together: 
bun run check
This runs both bun run typecheck and dprint fmt.

​
Project Structure

Key directories and files:
  • src/ - React frontend source code
  • src-tauri/ - Rust backend (Tauri app)
  • vendor/hyprnote/ - Git submodule for editor components
  • package.json - JavaScript dependencies and scripts
  • src-tauri/Cargo.toml - Rust dependencies
  • dprint.json - Code formatting configuration

​
Troubleshooting

​
Submodule Issues

If you encounter issues with the vendor/hyprnote submodule: 
git submodule update --init --recursive --force

​
Rust Compilation Errors

Ensure you’re using the stable Rust toolchain: 
rustup default stable
rustup update

​
Bun Lock File Conflicts

If you see dependency conflicts: 
rm bun.lock
bun install

​
Next Steps

Building for Production

Learn how to build desktop apps for macOS, Windows, and Linux

Contributing Guidelines

Understand our commit discipline and contribution workflow

Build docs developers (and LLMs) love

Get started for freeTalk to us