Skip to main content

​
Overview

This guide will help you set up your local development environment for contributing to UNS. The project uses a multi-layer architecture with Electron, React, and Python components.
Platform Requirements: While UNS runs on Windows, macOS, and Linux, some development steps may vary by platform. Platform-specific instructions are provided where applicable.

​
Prerequisites

Before starting, ensure you have the following installed:
1

Install Node.js 18+

Download and install Node.js from nodejs.org. Verify installation:
node --version
npm --version
The project uses npm for package management. While yarn/pnpm may work, npm is recommended for consistency.
2

Install Python 3.11+

Download Python from python.org or use your system’s package manager.
brew install [email protected]
Verify installation:
python --version  # or python3 --version
pip --version     # or pip3 --version
3

Install Platform-Specific Tools

macOS (Apple Silicon)Install Xcode Command Line Tools for native module compilation:
xcode-select --install
LinuxInstall build essentials:
sudo apt install build-essential
WindowsInstall Windows Build Tools (optional but recommended):
npm install -g windows-build-tools

​
Clone the Repository

1

Clone from GitHub

git clone https://github.com/OsamaTab/UNS.git
cd UNS
2

Install Root Dependencies

Install Electron and build tools:
npm install
This installs:
  • electron - Desktop app framework
  • electron-builder - Packaging tool
  • concurrently - Run multiple commands
  • wait-on - Wait for services to be ready
3

Install Frontend Dependencies

The frontend is a separate React app built with Vite:
cd frontend
npm install
cd ..
Key dependencies:
  • React 19 + React Router
  • Tailwind CSS for styling
  • Lucide React for icons
  • ePub.js for the built-in reader
4

Set Up Python Backend

Create a virtual environment and install dependencies:
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
The requirements.txt includes:
  • fastapi - API framework
  • uvicorn - ASGI server
  • botasaurus - Web automation utilities
  • ebooklib - EPUB generation
  • pyinstaller - Python to binary compiler
  • pydantic - Data validation
  • requests - HTTP client

​
Running in Development Mode

1

Build the Python Engine

Before running the app, you need to compile the Python backend into a standalone binary.
This step is required even in development mode because Electron expects a compiled engine binary.
cd backend
# Make sure your venv is activated!
python -m PyInstaller --onefile --windowed --name engine api.py
This creates backend/dist/engine (or engine.exe on Windows).macOS Users: Make the binary executable:
chmod +x dist/engine
2

Start Development Mode

From the project root:
npm run dev
This command does the following:
  1. Starts the Vite dev server on http://localhost:5173
  2. Waits for the dev server to be ready
  3. Launches Electron pointing to the dev server
  4. Electron automatically starts the Python engine
The first launch may take 10-15 seconds as Electron waits for the Python engine to boot.
3

Verify Everything Works

Once the app launches:
  1. Check the terminal for 🐍 Python: logs confirming the engine started
  2. The UI should load without errors
  3. Open DevTools (Cmd/Ctrl + Shift + I) to check for console errors
  4. Navigate to different pages (Library, Download, History) to ensure routing works

​
Development Scripts

The following npm scripts are available:
ScriptDescription
npm run devStart full development mode (frontend + Electron)
npm run startRun Electron with production build (no hot reload)
npm run start:frontendStart only the Vite dev server
npm run start:electronStart only Electron (expects frontend running)
npm run buildBuild frontend and package Electron app
npm run build:frontendBuild only the frontend
npm run build:electronPackage only the Electron app

​
Frontend Scripts

From the frontend/ directory:
ScriptDescription
npm run devStart Vite dev server on port 5173
npm run buildBuild production frontend to frontend/dist/
npm run previewPreview production build locally

​
Development Workflow

​
Making Frontend Changes

  1. Run npm run dev from the project root
  2. Edit files in frontend/src/
  3. Changes hot-reload automatically in Electron
  4. Check the browser DevTools for errors

​
Making Backend Changes

  1. Edit backend/api.py
  2. Rebuild the engine: 
    cd backend
source venv/bin/activate  # or venv\Scripts\activate on Windows
python -m PyInstaller engine.spec
  3. Restart the Electron app
Using engine.spec is faster for rebuilds as it caches dependencies.

​
Making Main Process Changes

  1. Edit main.js or preload.js
  2. Restart Electron (Cmd/Ctrl + Q and re-run npm run dev)
  3. Changes to main process files require a full restart

​
Troubleshooting

Make the binary executable:
chmod +x ./backend/dist/engine
If you get a security warning, go to System Preferences → Security & Privacy and click “Allow Anyway”.
Kill the process using the port:
# macOS/Linux
lsof -ti:5173 | xargs kill -9

# Windows
netstat -ano | findstr :5173
taskkill /PID <PID> /F
Ensure PyInstaller is running inside the activated virtual environment:
which python  # Should point to venv/bin/python
pip list | grep fastapi  # Should show installed packages
If packages are missing, reinstall:
pip install -r requirements.txt
  1. Check if the Vite dev server is running on port 5173
  2. Open DevTools and check the Console tab for errors
  3. Verify ELECTRON_START_URL is set correctly: 
    echo $ELECTRON_START_URL  # Should be http://localhost:5173
Try reinstalling dependencies:
# Root
rm -rf node_modules package-lock.json
npm install

# Frontend
cd frontend
rm -rf node_modules package-lock.json
npm install

# Backend
cd ../backend
rm -rf venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

​
Next Steps

Building the App

Learn how to create production builds for distribution

Project Structure

Understand the codebase architecture and file organization

Build docs developers (and LLMs) love

Get started for freeTalk to us