Skip to main content
Convert to it! can be packaged as a desktop application for Windows, macOS, and Linux using Electron. This allows users to run the converter offline without a browser.

​
Prerequisites

Before building the desktop app, ensure you have:
  • Bun runtime installed
  • Repository cloned with submodules (see local development)
  • Dependencies installed (bun install)

​
Build Configuration

The desktop build is configured in package.json using electron-builder: 
{
  "main": "src/electron.cjs",
  "build": {
    "appId": "com.p2r3.convert",
    "directories": {
      "output": "release"
    },
    "files": [
      "dist/**/*",
      "src/electron.cjs"
    ],
    "win": {
      "target": "nsis"
    },
    "mac": {
      "target": "dmg"
    },
    "linux": {
      "target": "AppImage"
    }
  }
}

​
Building for All Platforms

​
Windows

Build an NSIS installer for Windows:
1

Run the Windows build script

bun run desktop:dist:win
This command:
  1. Compiles TypeScript (tsc)
  2. Builds the app with Vite in desktop mode (IS_DESKTOP=true vite build)
  3. Generates the format cache (bun run cache:build)
  4. Packages with electron-builder for Windows
2

Find the installer

The Windows installer will be created in the release/ directory:
release/Convert to it! Setup <version>.exe
On non-Windows systems, you may need Wine installed to build Windows targets.

​
macOS

Build a DMG installer for macOS:
1

Run the macOS build script

bun run desktop:dist:mac
This creates a DMG disk image for macOS distribution.
2

Find the installer

The DMG file will be in the release/ directory:
release/Convert to it!-<version>.dmg
Building for macOS typically requires running on a Mac due to code signing and notarization requirements.

​
Linux

Build an AppImage for Linux:
1

Run the Linux build script

bun run desktop:dist:linux
This creates a portable AppImage file.
2

Find the AppImage

The AppImage will be in the release/ directory:
release/Convert to it!-<version>.AppImage

​
Development Workflow

For testing the desktop app during development:
1

Build the desktop app

bun run desktop:build
This compiles the application and generates the cache without packaging.
2

Preview with Electron

bun run desktop:preview
This launches the app in Electron for testing.
3

Build and preview in one command

bun run desktop:start
Combines both build and preview steps.

​
Available Scripts

Here are all desktop-related scripts from package.json:
ScriptCommandDescription
desktop:buildbun run desktop:buildBuild app with TypeScript, Vite, and cache generation
desktop:previewbun run desktop:previewLaunch built app in Electron
desktop:startbun run desktop:startBuild and preview in one command
desktop:dist:winbun run desktop:dist:winPackage Windows installer (NSIS)
desktop:dist:macbun run desktop:dist:macPackage macOS installer (DMG)
desktop:dist:linuxbun run desktop:dist:linuxPackage Linux installer (AppImage)

​
Environment Variables

The desktop build uses a special environment variable:
  • IS_DESKTOP=true - Tells Vite to build in desktop mode
This is automatically set by the desktop build scripts.

​
Output Directory Structure

After building, your project will have: 
convert/
├── dist/               # Vite build output
│   ├── cache.json     # Format support cache
│   └── ...
├── release/           # electron-builder output
│   ├── Convert to it!-<version>.dmg          # macOS
│   ├── Convert to it! Setup <version>.exe    # Windows
│   └── Convert to it!-<version>.AppImage     # Linux
└── src/
    └── electron.cjs   # Electron main process

​
Distribution

​
Code Signing

For production releases, you should sign your applications: Windows:
  • Use a code signing certificate
  • Configure in package.json under win.certificateFile
macOS:
  • Requires Apple Developer account
  • Configure signing identity in package.json under mac.identity
  • Notarization recommended for macOS 10.15+
Linux:
  • AppImages don’t require signing but can be verified

​
Auto-Updates

To enable auto-updates, configure electron-builder’s publish options: 
{
  "build": {
    "publish": [
      {
        "provider": "github",
        "owner": "p2r3",
        "repo": "convert"
      }
    ]
  }
}
Then build with the --publish flag: 
bun run desktop:build && electron-builder --mac --publish always
The default scripts use --publish never to prevent accidental releases.

​
Troubleshooting

​
Build fails on TypeScript compilation

Make sure all dependencies are installed: 
bun install

​
Cache generation fails

Ensure Chromium dependencies are available (needed for Puppeteer in buildCache.js): 
# On Debian/Ubuntu
sudo apt-get install -y chromium-browser

# On macOS
brew install chromium

​
AppImage won’t run on Linux

Make the AppImage executable: 
chmod +x "release/Convert to it!-*.AppImage"

​
Large bundle size

The desktop app includes all conversion tools and their dependencies (FFmpeg, ImageMagick WASM, etc.), resulting in a large bundle. This is expected and necessary for offline functionality.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us