> ## Documentation Index
> Fetch the complete documentation index at: https://anionex-feat-editable-text-only-export.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Desktop App

> Install the desktop app, package locally, and verify releases

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.

<Note>
  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.
</Note>

## Install a Released Build

Download the installer for your platform from [GitHub Releases](https://github.com/Anionex/banana-slides/releases).

| System  | Artifact                                                         | Installation                                                               |
| ------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Windows | `BananaSlides-<version>-Setup.exe`                               | Run the NSIS installer and follow the setup wizard                         |
| macOS   | `BananaSlides-<version>.dmg`                                     | Open the DMG and drag Banana Slides into Applications                      |
| Linux   | `BananaSlides-<version>.AppImage` / `BananaSlides-<version>.deb` | Make the AppImage executable, or install the deb with your package manager |

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

<Note>
  `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.
</Note>

## Local Packaging

Run these commands from the repository root:

```bash theme={null}
cd frontend
npm ci
npm run build

cd ../backend
uv sync
uv pip install pyinstaller
uv run pyinstaller banana-slides.spec --noconfirm

cd ../desktop
npm ci
npm run build:mac
```

For Windows packaging, run the final step in a Windows environment:

```powershell theme={null}
cd desktop
npm ci
npm run build:win
```

For Linux packaging:

```bash theme={null}
cd desktop
npm ci
npm run build:linux
```

`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.

<Warning>
  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.
</Warning>

## 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:

```bash theme={null}
export FFMPEG_BIN=/absolute/path/to/ffmpeg
export FFPROBE_BIN=/absolute/path/to/ffprobe
```

Then rerun `npm run build:mac`.