Skip to main content
The desktop app uses Electron for the frontend shell and a PyInstaller-packaged backend for local APIs. It is intended for local use: you do not need to start browser-mode frontend/backend services manually, and you do not need Docker at runtime.
The desktop app still requires valid model provider credentials. On first launch, open Settings and configure the provider, models, and API key. The settings are stored in the local app data directory.

​
Install a Released Build

Download the installer for your platform from GitHub Releases. The desktop app stores its database, uploads, materials, and exports in a user-writable app data directory rather than in packaged resource directories. Back up important local projects before upgrading.

​
Local Packaging Requirements

Local packaging needs frontend, backend, and Electron dependencies:
  • Node.js 20+
  • Python 3.11
  • uv
  • PyInstaller
  • Electron dependencies installed under desktop/
  • macOS / Linux use platform FFmpeg/FFprobe binaries from the desktop npm dependencies by default; you can also set trusted FFMPEG_BIN / FFPROBE_BIN paths, or fall back to commands in PATH
  • Windows downloads a pinned static FFmpeg archive and verifies its SHA256 by default; you can also point FFMPEG_BIN / FFPROBE_BIN at trusted local binaries
desktop/electron-builder.yml currently targets Windows x64 NSIS, macOS arm64 DMG, and Linux x64 AppImage/deb. Prefer packaging on the matching OS or through GitHub Actions runners.

​
Local Packaging

Run these commands from the repository root:
For Windows packaging, run the final step in a Windows environment:
For Linux packaging:
npm run build:* first runs desktop/scripts/prepare-artifacts.js and desktop/scripts/sync-build-meta.js:
  • Copies frontend/dist/ to desktop/frontend/
  • Copies backend/dist/banana-backend/ to desktop/backend/
  • Copies or generates FFmpeg, macOS icon, and other packaging resources
  • Generates desktop/build-meta.json, which lets update checks compare the current build against GitHub Releases
Packaging output is written to desktop/dist/.

​
Release Flow

Desktop releases are driven by .github/workflows/release-desktop.yml. Pushing a v* tag triggers:
  1. Syncing the tag version into desktop/package.json.
  2. Building frontend static files.
  3. Installing backend dependencies with uv and packaging backend/banana-slides.spec with PyInstaller.
  4. Installing Electron dependencies.
  5. Running npm run build:win, npm run build:mac, and npm run build:linux on Windows, macOS, and Linux runners.
  6. Uploading desktop/dist/* to a GitHub draft Release.
Before publishing the draft Release, manually check artifact names, version numbers, platform coverage, and release notes. The desktop update check reads the latest GitHub Release from Anionex/banana-slides and uses build-meta.json commit timestamps to avoid showing older releases as updates.

​
Signing and Distribution Limits

The current configuration can generate installers, but that does not mean the app is fully signed for formal distribution.
  • Windows: unsigned installers can trigger SmartScreen or “unknown publisher” prompts. Formal distribution should sign both the installer and executables with a code-signing certificate.
  • macOS: a DMG / App without Apple Developer ID signing and notarization may be blocked by Gatekeeper. Formal distribution should add signing, notarization, and stapling.
  • Updates: the current implementation checks GitHub Releases and prompts users to download a new version; it is not silent delta auto-update.
  • Architecture limits: macOS is currently configured for arm64, and Windows for x64. Intel Mac or Windows arm64 support requires additional electron-builder targets.
Do not disable global security settings on a user’s machine just to bypass platform prompts. When validating unsigned packages, only use the per-app manual approval flow provided by Windows or macOS.

​
Windows EXE Verification

Windows verification should cover at least:
  1. Generate BananaSlides-<version>-Setup.exe on a GitHub Actions Windows runner or a local Windows environment.
  2. Confirm the installer opens, the install path can be selected, and desktop/start-menu shortcuts are created as configured.
  3. Launch the app and confirm the desktop window, splash screen, and bundled backend startup.
  4. Open Settings, save a model configuration, refresh, and confirm it persists.
  5. Create a project and exercise one preview-page export or download action.
  6. Quit the app and confirm the bundled backend process exits with it.
If CI is used for Windows packaging verification, record the successful workflow run link and artifact name in the PR or release notes.

​
macOS DMG Verification

macOS verification should cover at least:
  1. Run npm run build:mac on a macOS runner or local macOS machine and generate BananaSlides-<version>.dmg.
  2. Mount the DMG and confirm the app icon/name are correct and the app can be dragged into Applications.
  3. Launch the app from Applications; if macOS warns about an unidentified developer, continue only through the per-app approval flow.
  4. After the desktop window loads, confirm the bundled backend /health path is healthy and frontend requests use the actual desktop backend port.
  5. Verify at least one real workflow involving image URLs, long-running task polling or SSE, and export/download behavior.
  6. Quit the app and confirm no packaged backend process remains.

​
Troubleshooting

​
The App Says the Backend Is Unavailable

Confirm the installer includes desktop/backend/, and check whether security software blocked the bundled backend process. During development or packaging verification, also confirm PyInstaller generated backend/dist/banana-backend/.

​
Packaging Cannot Find Frontend or Backend Resources

Build frontend/dist/ and backend/dist/banana-backend/ first, then run npm run build:* from desktop/.

​
macOS Packaging Cannot Find FFmpeg

Install FFmpeg, or set:
Then rerun npm run build:mac.