docs: rewrite README for Electron migration
Update documentation to reflect the transition from Tauri to Electron: - Document Electron as primary desktop runtime - Update development workflow and npm scripts - Add project structure and security sections - Note packaging status (Electron Forge needed for releases) - Keep reference to legacy Tauri script
This commit is contained in:
drelich
164
README.md
164
README.md
@@ -1,85 +1,139 @@
|
|||||||
|
|
||||||
|
|
||||||
# Tauri + React + Typescript
|
# Nextcloud Notes Desktop
|
||||||
|
|
||||||
# Nextcloud Notes - Cross-Platform Desktop App
|
A desktop client for [Nextcloud Notes](https://apps.nextcloud.com/apps/notes) built with React, TypeScript, Vite, and Electron.
|
||||||
|
|
||||||
A modern, cross-platform desktop application for [Nextcloud Notes](https://apps.nextcloud.com/apps/notes) built with Tauri + React + TypeScript.
|
This project started life as a Tauri app and has now been migrated to Electron for desktop runtime support, PDF export, and simpler cross-platform desktop behavior during development.
|
||||||
|
|
||||||
## Features
|
## What It Does
|
||||||
|
|
||||||
- ✅ **Cross-platform**: macOS, Linux, Windows
|
- Sign in to a Nextcloud server with Notes enabled
|
||||||
- ✅ **Lightweight**: ~600KB binary (vs 150MB+ Electron)
|
- Sync notes from WebDAV and favorite state from the Notes API
|
||||||
- ✅ **Modern UI**: React + TailwindCSS
|
- Create, edit, move, rename, and delete notes
|
||||||
- ✅ **Full sync**: Create, edit, delete, favorite notes
|
- Organize notes into categories, including nested categories
|
||||||
- ✅ **Search & filter**: Find notes quickly, filter by favorites
|
- Mark notes as favorites
|
||||||
- ✅ **Auto-save**: Changes save automatically after 1.5s
|
- Cache notes locally for faster startup and offline viewing
|
||||||
- ✅ **Secure**: Credentials stored in system keychain (localStorage for now)
|
- Upload and render note attachments
|
||||||
- ✅ **Background sync**: Auto-sync every 5 minutes
|
- Preview Markdown while editing
|
||||||
|
- Export notes to PDF
|
||||||
|
- Use a focus mode for distraction-free editing
|
||||||
|
|
||||||
## Prerequisites
|
## Current Runtime
|
||||||
|
|
||||||
- **Rust**: Install from https://rustup.rs/
|
- Primary desktop runtime: Electron
|
||||||
- **Node.js**: v18+ recommended
|
- Frontend: React 19 + TypeScript + Vite
|
||||||
- **Nextcloud instance** with Notes app enabled
|
- Styling: Tailwind CSS
|
||||||
|
- Local cache: IndexedDB
|
||||||
|
- Nextcloud integration:
|
||||||
|
- WebDAV for note files, folders, attachments, and category color storage
|
||||||
|
- Notes API for favorite metadata
|
||||||
|
|
||||||
|
Some Tauri-related code and dependencies are still present in the repository, mainly because parts of the app were built during the earlier Tauri phase. The Electron path is the actively used desktop runtime.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Node.js 18 or newer
|
||||||
|
- npm
|
||||||
|
- A Nextcloud instance with the Notes app enabled
|
||||||
|
|
||||||
|
## Install
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
## Development
|
## Development
|
||||||
|
|
||||||
|
Run the Electron app with the Vite dev server:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Install dependencies
|
npm run dev:desktop
|
||||||
npm install
|
```
|
||||||
|
|
||||||
# Run in development mode
|
Useful scripts:
|
||||||
npm run tauri dev
|
|
||||||
|
|
||||||
# Build for production
|
```bash
|
||||||
npm run tauri build
|
npm run dev:renderer # Vite frontend only
|
||||||
|
npm run dev:electron # Electron only, expects renderer on port 1420
|
||||||
|
npm run build # TypeScript + Vite production build
|
||||||
|
npm run desktop # Run Electron against the built dist/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Production-Like Local Run
|
||||||
|
|
||||||
|
Build the frontend, then start Electron against the generated `dist/` files:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
npm run desktop
|
||||||
```
|
```
|
||||||
|
|
||||||
## First Launch
|
## First Launch
|
||||||
|
|
||||||
1. Enter your Nextcloud server URL (e.g., `https://cloud.example.com`)
|
1. Enter your Nextcloud server URL, for example `https://cloud.example.com`
|
||||||
2. Enter your username
|
2. Enter your username
|
||||||
3. Enter your password or **App Password** (recommended)
|
3. Enter your password or, preferably, a Nextcloud app password
|
||||||
- Generate at: Settings → Security → Devices & Sessions in Nextcloud
|
4. Wait for the initial sync to finish
|
||||||
4. Click **Connect**
|
|
||||||
|
|
||||||
## Building for Distribution
|
Using an app password is strongly recommended.
|
||||||
|
|
||||||
### macOS
|
## Notable Behavior
|
||||||
```bash
|
|
||||||
npm run tauri build
|
### Sync model
|
||||||
# Output: src-tauri/target/release/bundle/macos/
|
|
||||||
|
- Note files are synced through WebDAV
|
||||||
|
- Favorite status is synced through the Nextcloud Notes API
|
||||||
|
- Notes are cached locally and can still be viewed when offline
|
||||||
|
- Background sync runs periodically while the app is open
|
||||||
|
|
||||||
|
### PDF export
|
||||||
|
|
||||||
|
- In Electron, the toolbar export action saves a PDF directly to disk
|
||||||
|
- Embedded note images are resolved before export when possible
|
||||||
|
|
||||||
|
### Category colors
|
||||||
|
|
||||||
|
- Category color preferences are stored in `.category-colors.json` inside your Nextcloud Notes WebDAV folder
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```text
|
||||||
|
electron/ Electron main process and preload bridge
|
||||||
|
src/api/ Nextcloud API and WebDAV client logic
|
||||||
|
src/components/ React UI
|
||||||
|
src/db/ Local IndexedDB cache
|
||||||
|
src/services/ Desktop runtime helpers and sync logic
|
||||||
|
src/printExport.ts Shared print/PDF document generation
|
||||||
```
|
```
|
||||||
|
|
||||||
### Linux
|
## Security Notes
|
||||||
```bash
|
|
||||||
npm run tauri build
|
|
||||||
# Output: src-tauri/target/release/bundle/appimage/ or .deb
|
|
||||||
```
|
|
||||||
|
|
||||||
### Windows
|
- Electron runs with `contextIsolation: true`
|
||||||
```bash
|
- `nodeIntegration` is disabled in renderer windows
|
||||||
npm run tauri build
|
- Network requests that need desktop privileges are routed through Electron IPC instead of renderer-side browser fetch
|
||||||
# Output: src-tauri/target/release/bundle/msi/
|
|
||||||
```
|
|
||||||
|
|
||||||
## Tech Stack
|
Current limitation:
|
||||||
|
|
||||||
- **Tauri**: Rust-based native wrapper (~600KB)
|
- Login credentials are still persisted in `localStorage`
|
||||||
- **React 18**: UI framework
|
|
||||||
- **TypeScript**: Type safety
|
|
||||||
- **TailwindCSS**: Utility-first styling
|
|
||||||
- **Vite**: Fast build tool
|
|
||||||
|
|
||||||
## Advantages over Native Swift App
|
That is convenient for development, but it is not the right long-term storage mechanism for a production desktop app. A future improvement should move credentials into the OS keychain or another secure secret store.
|
||||||
|
|
||||||
- ✅ **Cross-platform**: One codebase for macOS, Linux, Windows
|
## Packaging Status
|
||||||
- ✅ **No SwiftUI state issues**: React's state management is mature
|
|
||||||
- ✅ **Smaller binary**: Tauri is much lighter than Electron
|
|
||||||
- ✅ **Easier to maintain**: Web technologies vs platform-specific code
|
|
||||||
- ✅ **No Xcode required**: Build on any platform
|
|
||||||
|
|
||||||
## Recommended IDE Setup
|
Electron packaging for release builds is not set up yet.
|
||||||
|
|
||||||
- [VS Code](https://code.visualstudio.com/) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)
|
Right now, the repository supports:
|
||||||
|
|
||||||
|
- local development with `npm run dev:desktop`
|
||||||
|
- local production-style execution with `npm run build && npm run desktop`
|
||||||
|
|
||||||
|
If you want distributable `.dmg`, `.AppImage`, `.deb`, or `.exe` artifacts, the next step is to add an Electron packaging tool such as Electron Forge or electron-builder.
|
||||||
|
|
||||||
|
## Legacy Tauri Script
|
||||||
|
|
||||||
|
There is still a `npm run tauri` script in `package.json`, but the README and current workflow are centered on Electron.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
No license file is currently included in this repository.
|
||||||
|
|||||||
Reference in New Issue
Block a user