ToDo

A cross-platform task manager: plan your day, track Do’s and Don’ts, sync across devices, and stay on top of what matters — with React + Vite, Express, and Tauri for desktop and mobile.

Features • Installation • Running & Building • GitHub Actions • Icons • Contributing

---

📖 Table of Contents

• About
• Features
• Technology Stack
• Prerequisites
• Installation
• Running the Application
• Building for Production
• GitHub Actions (Build & Release)
• Icons Generation
• Project Structure
• Configuration
• Contributing
• Support
• License
• About Roboticela

---

🌟 About

ToDo is a task management app from Roboticela to plan your day, track progress, and stay on top of what to do and what to avoid. Use Today, Calendar, and Analytics to organize tasks by time, set repeating schedules, and see how you’re doing — with sync across devices, offline support, themes, reminders, and account management.

Built with a React + TypeScript frontend (Vite), an Express backend API (Prisma), and Tauri 2 for desktop (Linux, Windows, macOS) and mobile (Android; iOS coming soon). It includes a GitHub Actions workflow for building and releasing installers across platforms, plus scripts for icon generation (desktop, Android, web).

Why ToDo?

• ✅ Day-focused — Today view with progress, Do’s / Don’ts, and filters
• ✅ Cross-Platform — Web, Linux, Windows, macOS (desktop); Android (and iOS planned)
• ✅ Sync & Offline — Account sync across devices with local-first offline support
• ✅ Reminders — Native notifications and customizable notification sounds
• ✅ CI/CD Ready — One workflow to build .deb, .rpm, .AppImage, .exe, .msi, .apk, .aab
• ✅ Icon Pipeline — Single SVG → desktop, Android adaptive, and web favicons

---

✨ Features

📋 Tasks & Planning

• Today view — Progress bar, Do’s and Don’ts, and filters
• Calendar view — See and manage tasks by date
• Time & duration tasks — Optional repeating schedules and end dates
• Analytics — Review completion and trends over time

🔐 Accounts & Sync

• Auth — Email/password, Google Sign-In, and desktop deep-link login
• Cloud sync — Tasks and preferences synced via the Express API
• Offline support — Work locally; sync when you’re back online
• Settings & subscription — Themes, reminders, account, and plan management

🖥️ Desktop, Mobile & Web

• Vite 7 — Fast HMR and optimized production builds
• React 19 + TypeScript — Type-safe UI
• Tauri 2 — Small binaries, system WebView; Android reminder service
• TailwindCSS 4 — Utility-first styling with multiple themes

🔧 Backend

• Express 5 — REST API in server/ (Prisma + PostgreSQL)
• Separate server/package.json and scripts: server:dev, server:build, server:start, plus db:* migrations

📦 Build & Release

• GitHub Actions — Manual workflow with inputs: environment, version, prerelease, draft, and per-platform toggles (Linux, Windows, Android; macOS/iOS placeholders)
• Multi-arch — Linux: x86_64, aarch64, armv7; Windows: x86_64, i686, aarch64; Android: all ABIs + AAB
• Checksums — SHA256 and SHA512 for release assets
• Android — APK (split per ABI) and AAB; optional keystore secrets for signing

🎨 Icons

• Single source — public/favicon.svg (or custom path)
• Tauri icon — Desktop and Windows Store assets
• Android — Adaptive icon with configurable background color and icon scale
• Web — Favicons and apple-touch-icon copied to public/

---

🛠️ Technology Stack

Layer	Technology
Frontend	React 19, TypeScript 5.x, Vite 7, TailwindCSS 4, React Router 7
Backend	Express 5 (Node.js), Prisma, PostgreSQL
Desktop/Mobile	Tauri 2, Rust
Tooling	ESLint, npm

---

📋 Prerequisites

Required

• Node.js (v20+, workflow uses 24) — Download
• npm — Node package manager
• Rust (latest stable) — Install

Platform-specific (for local builds)

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev \
  patchelf libsoup-3.0-dev libjavascriptcoregtk-4.1-dev

Linux (Fedora)

sudo dnf install webkit2gtk4.1-devel openssl-devel libappindicator-gtk3-devel librsvg2-devel

macOS

xcode-select --install

Windows

• Visual Studio C++ Build Tools
• WebView2 (usually on Windows 10/11)

Android (local)

• JDK 17, Android SDK, NDK (e.g. 27.0.12077973 as in workflow)
• npx tauri android init once; see Tauri Android
• Windows only: enable Developer Mode (Settings → System → For developers). Tauri links libapp_lib.so into src-tauri/gen/android/.../jniLibs with a symbolic link; without Developer Mode (or the “create symbolic links” privilege) the build fails with “Creation symbolic link is not allowed for this system” (upstream discussion). Keep the project on an NTFS drive (not exFAT/FAT32 on external disks).
• If Gradle/Kotlin reports “this and base files have different roots” (e.g. repo on D: and Cargo/registry on C:), the Kotlin daemon may fall back; builds can still succeed. If problems persist, put the project on the same drive as your user profile (where .cargo lives) or add kotlin.incremental=false in src-tauri/gen/android/gradle.properties after tauri android init (re-apply if you regenerate gen/android).

---

📥 Installation

git clone https://github.com/Roboticela/ToDo.git
cd ToDo
npm install
cd server && npm install && cd ..

Copy environment files and fill in values as needed:

cp .env.example .env
cp server/.env.example server/.env

Optional: build Rust for desktop once:

cd src-tauri && cargo build && cd ..

---

🚀 Running the Application

Frontend only (web)

npm run dev

Then open http://localhost:5173.

Desktop (Tauri + Vite dev server)

npm run tauri:dev
# or
npm run dev:desktop

Starts Vite and opens the Tauri window with hot-reload.

Android (device / emulator)

npm run dev:android

Backend API only

npm run server:dev

Runs Express from server/ (default port as in server/.env).

Web + backend together

Run in two terminals:

npm run dev
npm run server:dev

---

📦 Building for Production

Frontend

npm run build

Output: dist/.

Backend

npm run server:build
npm run server:start

Generates Prisma client and starts the API from server/.

Desktop (current platform)

npm run build
npm run tauri build

Or:

npm run build && npm run tauri:build

Output:

• Linux: src-tauri/target/<target>/release/bundle/ (deb, rpm, AppImage)
• Windows: src-tauri/target/<target>/release/bundle/ (nsis .exe, msi)
• macOS: src-tauri/target/<target>/release/bundle/ (dmg, app)

Desktop for a specific target (cross-compile)

Examples:

# Linux x86_64 (default on Linux)
npm run tauri:build -- --target x86_64-unknown-linux-gnu

# Linux ARM64
npm run tauri:build -- --target aarch64-unknown-linux-gnu

# Windows (from Linux/macOS with cross-compile setup)
npm run tauri:build -- --target x86_64-pc-windows-msvc

Rust targets must be installed (e.g. rustup target add <target>).

Android

Prerequisites: Android SDK, NDK, and npx tauri android init done once.

# APK (split per ABI)
npx tauri android build --apk --split-per-abi

# AAB (bundle for Play Store)
npx tauri android build --aab

Set NDK_HOME if needed (e.g. $ANDROID_HOME/ndk/<version>).

Build summary by platform

Platform	Command / note
Web	npm run build → dist/
Linux	npm run tauri:build (or --target x86_64-unknown-linux-gnu etc.)
Windows	npm run tauri:build on Windows (or cross-compile with MSVC target)
macOS	npm run tauri:build on macOS
Android	npx tauri android build --apk or --aab (after tauri android init)

---

🤖 GitHub Actions (Build & Release)

The workflow file is .github/workflows/build-release.yml. It is triggered manually (workflow_dispatch) and:

1. Validates — Checks the selected GitHub Environment has frontend/API URLs
2. Prepares — Patches version in package.json, server/package.json, src-tauri/tauri.conf.json, and src-tauri/Cargo.toml
3. Builds — Linux, Windows, and Android (each can be toggled on/off)
4. Releases — Creates a GitHub Release with artifacts and SHA256/SHA512 checksums

Workflow inputs (manual trigger)

Input	Type	Default	Description
environment	environment	—	GitHub Environment (vars/secrets for this build)
version	string	"0.1.0"	Release version (e.g. 1.0.0)
prerelease	boolean	false	Mark release as pre-release
draft	boolean	false	Create as draft release
build_linux	boolean	true	Build for Linux (.deb, .rpm, .AppImage)
build_windows	boolean	true	Build for Windows (.exe, .msi)
build_android	boolean	true	Build for Android (.apk, .aab)
build_macos	boolean	false	Reserved (coming soon)
build_ios	boolean	false	Reserved (coming soon)

Environment variables (workflow)

Set at the top level of the workflow:

Variable	Example	Description
APP_NAME	"ToDo"	Display name used in release title and Android signing DN
NDK_VERSION	"27.0.12077973"	Android NDK version installed via sdkmanager
NODE_VERSION	"24"	Node version for actions/setup-node

Required GitHub Environment variables (Settings → Environments → name → Variables):

Variable	Description
VITE_APP_URL	Frontend / deep-link base URL baked into the client
VITE_API_URL	Backend API base URL baked into the client

Fallbacks also accepted: APP_URL / FRONTEND_URL, API_URL / BACKEND_URL. Optional: VITE_GOOGLE_CLIENT_ID or GOOGLE_CLIENT_ID for native Google Sign-In.

Secrets (optional, for Android signing)

If you want release signing for Android (e.g. for Play Store), add these environment secrets:

Secret	Description
ANDROID_KEYSTORE_BASE64	Base64-encoded .keystore file (contents of the keystore binary)
ANDROID_KEY_ALIAS	Key alias inside the keystore
ANDROID_KEY_PASSWORD	Private key password
ANDROID_STORE_PASSWORD	Keystore password

If none of these are set, the workflow generates a self-signed keystore and uses it for the build (suitable for testing, not for Play Store distribution).

Built artifacts

Platform	Architectures	Formats
Linux	x86_64, aarch64, armv7	.deb, .rpm, .AppImage
Windows	x86_64, i686, aarch64	.exe (NSIS), .msi
Android	arm64-v8a, armeabi-v7a, x86, x86_64	.apk (per ABI), .aab

The release step uploads all artifacts and adds SHA256SUMS and SHA512SUMS to the release. Verify with:

sha256sum -c SHA256SUMS
# or
sha512sum -c SHA512SUMS

How to run the workflow

1. Open the repo on GitHub → Actions → Build and Release.
2. Click Run workflow.
3. Select an environment, fill in version (required), and optionally change prerelease, draft, and platform toggles.
4. Run; when all selected builds succeed, a release is created (or updated) with the given tag (e.g. v1.0.0).

---

🎨 Icons Generation

Icons are generated from a single source image (default: public/favicon.svg) so that desktop, Android, and web all stay in sync.

Command

npm run icons:generate

Or with a custom source path (relative to project root or absolute):

npm run icons:generate -- public/logo.svg
node scripts/icons-generate.js path/to/icon.svg

What it does

1. Prompts (interactive)

   • Android launcher background color — Hex color (e.g. #ffffff). Previous value is read from src-tauri/icons/android/values/ic_launcher_background.xml and used as default.
   • Android icon scale — Icon size as percentage of canvas (e.g. 50 = 50%). Stored in src-tauri/icons/android/icon-options.json and reused as default next time.

2. Standard Tauri icons
   Runs tauri icon "<inputPath>" to generate desktop icons (e.g. 32x32, 128x128, icon.ico, icon.icns) in src-tauri/icons/.

3. Android background color
   After tauri icon, overwrites the Android background color in src-tauri/icons/android/values/ic_launcher_background.xml with the color you chose (so tauri icon doesn’t override it).

4. Android mipmap icons
   Builds scaled, padded PNGs for Android adaptive icon:

   • Launcher: ic_launcher.png, ic_launcher_round.png (mdpi → xxxhdpi)
   • Foreground: ic_launcher_foreground.png (2.25× sizes for adaptive layer)

   Padding is applied so the icon is not clipped by the adaptive icon mask; the scale (e.g. 50%) controls how large the logo is within the canvas.

5. Web icons
   Runs node scripts/copy-vite-icons.js, which copies from src-tauri/icons/ to public/:

   • 32x32.png → public/favicon-32x32.png
   • 128x128.png → public/apple-touch-icon.png
   • icon.ico → public/favicon.ico

Icon options (saved)

Option	File	Description
Android background color	src-tauri/icons/android/values/ic_launcher_background.xml	<color name="ic_launcher_background">#rrggbb</color>
Scale (percent)	src-tauri/icons/android/icon-options.json	{ "scalePercent": 50 } — used as default for next run

Scale input format

When prompted for Android icon scale, you can enter:

• A number 1–100 (e.g. 50) → treated as percent.
• A number 0.01–1 (e.g. 0.5) → treated as fraction.
• With or without % (e.g. 50%).

Non-interactive / CI

The script is interactive by default. For CI or scripts, you would need to either:

• Pipe answers into it (e.g. echo -e " #ffffff\n 50" | npm run icons:generate), or
• Pre-create/update icon-options.json and values/ic_launcher_background.xml and adapt the script to read from env or args (not implemented in the current script).

---

📁 Project Structure

ToDo/
├── .github/
│   └── workflows/
│       └── build-release.yml    # Build & release workflow
├── public/
│   ├── favicon.svg              # Default icon source for icons:generate
│   └── sounds/                  # Notification sound library
├── server/                      # Express API
│   ├── routes/
│   ├── services/
│   ├── prisma/
│   ├── server.js
│   └── package.json
├── src/                         # React frontend
│   ├── components/
│   ├── contexts/
│   ├── pages/
│   │   ├── auth/
│   │   ├── todo/
│   │   └── admin/
│   ├── App.tsx
│   ├── main.tsx
│   └── ...
├── src-tauri/                   # Tauri + Rust
│   ├── src/
│   │   ├── main.rs
│   │   └── lib.rs
│   ├── icons/                   # Generated + Android custom
│   │   ├── 32x32.png, 128x128.png, icon.ico, icon.icns, ...
│   │   └── android/
│   │       ├── values/ic_launcher_background.xml
│   │       ├── icon-options.json
│   │       └── mipmap-*/        # Launcher & foreground PNGs
│   ├── Cargo.toml
│   ├── tauri.conf.json
│   └── ...
├── scripts/
│   ├── icons-generate.js        # Icon generation (tauri + Android + web)
│   ├── copy-vite-icons.js       # Copy Tauri icons → public/
│   └── sync-frontend-env.mjs    # Bake VITE_* URLs for Tauri builds
├── docker/                      # Optional deploy helpers
├── index.html
├── package.json
├── vite.config.ts
├── tsconfig.json
├── LICENSE
└── README.md

---

⚙️ Configuration

Tauri

• src-tauri/tauri.conf.json — App name, version, identifier, window size, beforeDevCommand / beforeBuildCommand, bundle targets and icon list. Change here for product name and desktop behavior.

Frontend

• vite.config.ts — Vite and React plugin; dev server port (default 5173).
• index.html — Title and favicon links (use npm run icons:generate to refresh favicons in public/).
• .env — VITE_APP_URL, VITE_API_URL, and optional Google client ID (see .env.example).

Backend

• server/.env — Database URL, JWT secrets, mail, OAuth, and related settings (see server/.env.example).

Version (for releases)

The GitHub Actions workflow patches version in:

• package.json
• server/package.json
• src-tauri/tauri.conf.json
• src-tauri/Cargo.toml

For local releases, keep these in sync manually or run your own patch step.

---

🤝 Contributing

1. Fork the repository.
2. Create a branch: git checkout -b feature/your-feature or fix/your-fix.
3. Make changes; follow existing style (ESLint, TypeScript, Rust fmt/clippy).
4. Commit with a clear message (e.g. Add: ..., Fix: ..., Docs: ...).
5. Push and open a Pull Request.

---

💬 Support

• Issues: GitHub Issues for bugs and feature requests.
• Repository: Roboticela/ToDo.
• Website: todo.roboticela.com.

---

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE for the full text.

---

🏢 About Roboticela

Roboticela builds cross-platform apps with Vite, Express, and Tauri. Star the repo if you find ToDo useful.

---

Built with ❤️ by Roboticela

⬆ Back to Top