nextcloud-notes-desktop-app/README.md

Nextcloud Notes Desktop

A desktop client for Nextcloud Notes built with React, TypeScript, Vite, and Electron.

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.

What It Does

• Sign in to a Nextcloud server with Notes enabled
• Sync notes from WebDAV and favorite state from the Notes API
• Create, edit, move, rename, and delete notes
• Organize notes into categories, including nested categories
• Mark notes as favorites
• Cache notes locally for faster startup and offline viewing
• Upload and render note attachments
• Preview Markdown while editing
• Export notes to PDF
• Use a focus mode for distraction-free editing

Current Runtime

• Primary desktop runtime: Electron
• Frontend: React 19 + TypeScript + Vite
• 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

npm install

Development

Run the Electron app with the Vite dev server:

npm run dev:desktop

Useful scripts:

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:

npm run build
npm run desktop

First Launch

1. Enter your Nextcloud server URL, for example https://cloud.example.com
2. Enter your username
3. Enter your password or, preferably, a Nextcloud app password
4. Wait for the initial sync to finish

Using an app password is strongly recommended.

Notable Behavior

Sync model

• 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

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

Security Notes

• Electron runs with contextIsolation: true
• nodeIntegration is disabled in renderer windows
• Network requests that need desktop privileges are routed through Electron IPC instead of renderer-side browser fetch

Current limitation:

• Login credentials are still persisted in localStorage

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.

Packaging Status

Electron packaging for release builds is not set up yet.

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.