Skip to main content

Desktop App (Electron)

Optional Windows desktop client for TMA Cloud. Loads the same web app from your server URL; no separate frontend build.

Prerequisites​

  • Node.js (v25+)
  • TMA Cloud server running and reachable (e.g. https://your-tma-cloud.example.com)
  • npm

Run from Source​

Useful for development or testing without building an installer.

  1. Clone the repo and go to the Electron app:

    cd electron
    npm install

  2. Set the server URL. Create electron/src/config/build-config.json (copy from src/config/build-config.example.json if present) with:

    {
      "serverUrl": "https://your-tma-cloud.example.com",
      "updatorUrl": ""
    }

    Replace serverUrl with your TMA Cloud URL. updatorUrl is optional. Set it to the base URL where installers are hosted so the app can download updates (installer URL: <updatorUrl>/v<version>).

  3. Start the app:

    npm start

    The window opens and loads the server URL. If serverUrl is missing, the app shows a "Server URL not configured" page.

Build Installer (Windows)​

Builds a Windows installer with the server URL embedded so users do not need a config file.

Admin privilege required: Run your terminal (or IDE) as Administrator when building.

  1. In electron/, ensure src/config/build-config.json exists and contains your serverUrl. Set updatorUrl to the base URL for installer downloads if you want the packaged app to offer in-app desktop updates.

  2. Run the build:

    npm run build:client

    This runs prepare-client-build.js (copies src/main and src/preload into dist-electron/ and injects serverUrl into main config), then runs electron-builder. Output is in electron/dist-client/ (NSIS installer by default).

  3. For a portable executable (no installer):

    npm run build:client:win:portable

  4. For an unpacked folder (no installer, run exe from folder):

    npm run build:client:win:unpacked

Builds are unsigned by default. To sign the app, configure code signing and use the same build:client flow.

Install on Windows​

  • NSIS installer: Run the .exe from dist-client/. Choose installation directory and complete the wizard.
  • Portable: Copy the portable build and run the executable. No install step.
  • Unpacked: Run the executable inside the unpacked folder.

The server URL is embedded at build time only. No config file is needed after install.

Version and updates​

  • The desktop app version comes from electron/package.json and is shown under Settings → Updates → Desktop app.
  • The app uses the same update feed as the web UI (/api/version/latest), which returns frontend, backend, and electron versions.
  • When any signed-in user opens the app (web or desktop), a one-time background check compares the current versions to the feed.
  • If any component is outdated, an Updates Available notice appears in the left sidebar above Settings, listing the latest versions for backend, frontend, and Electron.
  • Desktop (Electron) updates: When the Electron version is outdated and updatorUrl was set at build time, a download icon appears next to Electron in that section. Any signed-in user can click it to download the update. After the download finishes, the installer is launched and the app quits so the user can complete setup. If updatorUrl is not configured, the sidebar still shows the latest version but the download action is not available.

Active desktop clients (admin view)​

  • Signed-in desktop clients send periodic heartbeats to the backend.
  • The admin can view active clients in Settings → Administration → Active Desktop Clients.
  • Each row includes user, platform, app version, IP, and last seen time.
  • Revoking sessions removes related heartbeat rows; stale rows are also purged automatically.

Desktop Editing and Open on Desktop (Windows)​

When you run the Windows desktop app, you can open supported files in their desktop applications and have changes sync back automatically.

  • Supported: .docx, .xlsx, .pptx, .pdf, and other types that Windows can open (including common image and video formats)
  • Where it works: Electron desktop app on Windows only

Open on Desktop​

  • Right-click a supported file (document, image, or video) → Open on desktop
  • Double-click behavior in the desktop app:
    • Office/OnlyOffice-supported files open in the default desktop application
    • Image and video files open in the default viewer for that type
  • A progress indicator (e.g. "Opening file… X%") appears while the file is prepared. Clicking the same file again while it is opening shows "Already opening this file on desktop. Please wait...".

How Sync Works​

  • The desktop app downloads an encrypted copy of the file to a temporary location (or reuses a copy for large files when the cloud version is unchanged).
  • The file is opened using the default application registered in Windows (for example, Word, Excel, PowerPoint, or another associated editor).
  • While the file is open, the desktop app watches it for changes.
  • When you press Save in the desktop editor, the updated content is uploaded back to TMA Cloud in the background.
  • The same file entry is updated (ID stays the same); the modified time and size reflect the new version.

If you open a document and close it without saving, no upload is performed and the stored version is unchanged.

  • Caching for large files: For files of about 6 MB or more, the desktop app may reuse a previously downloaded copy from the same session instead of re-downloading. Before reuse, it checks the current file size and modification time from the server and the copy is reused only if both match. If the file was changed on the server (for example by another device or user), it is re-downloaded.

Save As / Export (derived files)​

When you use Save As or Export in a desktop editor (for example, Word → Export to PDF or save a copy as .docx) while the file was opened via Open on desktop:

  • If the new file (for example, report.pdf or report-copy.docx) is saved into the same temporary folder that the desktop app used for the original file, the desktop app:
    • Detects the new file (supported document and export formats such as .pdf, .docx, .xlsx, .pptx, .csv, .rtf, and similar).
    • Uploads it as a new file in the same cloud folder as the original document.
    • Shows a status toast such as Saving exported file "report......pdf" (12.3 MB) and Exported file "report......pdf" when complete.
  • Large exports may take time and the file list updates automatically when the upload finishes.
  • If you choose a different location (for example, Desktop or Documents) in the Save As dialog, the file is saved only on your computer and is not uploaded automatically.

Clipboard Integration (Windows desktop app)​

The Windows desktop app uses a single Copy / Cut / Paste model that bridges the cloud and OS clipboards. One Copy covers both in-app pastes and Explorer pastes, and Paste figures out the right source automatically.

Context Menu​

  • Copy: Right-click one or more items → Copy. The selection goes to the in-app clipboard immediately so you can paste it into another folder inside TMA Cloud, and (in the desktop app) it is also written to the Windows clipboard in the background so you can paste in Explorer. Files larger than 200 MB total and folders are kept on the in-app clipboard only — those still paste between folders in TMA Cloud, but Explorer pastes are skipped. The toast tells you which path applied.
  • Cut: Right-click → Cut. In-app only. Cut items show a Windows-Explorer-style faded look until paste completes.
  • Paste: Right-click in a folder → Paste. If you copied or cut something inside TMA Cloud, the cloud clipboard is used (server-side copy/move — no re-upload). Otherwise files on the Windows clipboard are uploaded into the current folder. If you copy something in Explorer after a cloud Copy, Paste detects the change and uses the newer Windows-clipboard files instead.

The OS clipboard side of Paste supports Explorer copy, Outlook attachments, Snipping Tool, the OLE file clipboard used by other apps, and clipboard text containing file paths (e.g. Copy as path, IDE "Copy path/reference").

Keyboard Shortcuts​

  • Ctrl+A / Cmd+A: Select all files and folders in the current view.
  • Ctrl+C / Cmd+C: Unified Copy (cloud clipboard + Windows clipboard when files fit).
  • Ctrl+X / Cmd+X: Cut (cloud clipboard only).
  • Ctrl+V / Cmd+V: Smart Paste — cloud clipboard first, otherwise upload from the Windows clipboard.
  • Ctrl+Shift+I / Cmd+Shift+I: Open Get Info for the currently selected file or folder (desktop app only and single selection).

Folder navigation (back/forward)​

In the Windows desktop app, the file manager supports back/forward folder navigation.

  • Toolbar: Back and Forward buttons appear in the file manager header (left of the breadcrumbs). They move through the folder history.
  • Mouse: Mouse back/forward (side buttons, e.g. typical browser back/forward) trigger folder back/forward when the file manager is in use. They are ignored when the pointer is over an input, textarea, select, or a dialog.

Navigation history is updated when you open a folder, click a breadcrumb, or go to My Files. Forward history is cleared when you navigate to a new folder.

Desktop-only mode (optional)​

  • When the administrator enables Desktop app only access in Settings → Administration from the desktop app, the backend rejects browser access to the main app.
  • The desktop app continues to work because it sends the required HTTP header on its requests.
  • Share links (/s/*), /health, and /metrics still respond as normal.
  • Browsers that open the main URL see a simple page stating that the instance is configured for desktop app access only.