Getting Started with Desktopr

Easily build and sign lightweight desktop applications using web stacks, with Desktopr GitHub actions and a straightforward Node API.

Desktopr turns your web application into a cross-platform desktop application for macOS, Windows and Linux, using Rust and Tauri to produce lightweight, native apps.

Desktopr is free and open source (Apache 2.0). You build it yourself, on your machine or with GitHub Actions, and the resulting installers are yours. There is no account, backend or hosted service.

For more info check out: What is Desktopr?

Requirements

• Node.js 22 and npm
• Rust stable (rustup)
• Tauri CLI 2.11: cargo install tauri-cli --version 2.11.1 --locked
• jq
• The platform prerequisites from the Tauri guide. On Debian/Ubuntu: libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev libssl-dev libxdo-dev build-essential

Creating Your First Project

1. Fork or clone the repository:

   git clone https://github.com/suffro/desktopr.git
   cd desktopr
   npm ci

2. Run it against your web app in development:

   APP_URL=http://localhost:5173 npm run dev

   Without APP_URL the window shows the bundled local page in src-tauri/standalone/. Only the origin of APP_URL is granted access to the native bridge.

3. Install the SDK in your web app (npm install desktopr) to call native features. See the Bridge API.

4. Build the installers:

   APP_URL=https://app.example.com \
   APP_VERSION=1.0.0 \
   APP_IDENTIFIER=com.example.app \
   MAIN_WINDOW_TITLE="Example" \
   npm run build

   Bundles are written to src-tauri/target/release/bundle/. Other options (window size, deep link scheme, updater) are environment variables read by scripts/prod-conf.sh.

TIP

Try the bridge before wiring your own app: the Desktopr Companion loads any web app URL in a Desktopr window and includes a playground for the API.

Building with GitHub Actions

The repository ships a build workflow that builds the platforms you select, launches each app briefly as a smoke test and uploads the installers as workflow artifacts. Run it from the Actions tab of your fork, or call it from another workflow:

jobs:
  desktop:
    uses: suffro/desktopr/.github/workflows/build.yml@main
    with:
      platforms: linux,windows,macos
      app_name: Example
      app_identifier: com.example.app
      app_version: 1.0.0
      app_url: https://app.example.com
    secrets: inherit

Set release: true (with app_version) to also create a draft GitHub Release. Nothing is uploaded anywhere else.

If your web app lives in its own repository, use the build action instead: build your app as usual, then hand its output directory to Desktopr in the same job.

      - run: npm run build
      - uses: suffro/desktopr@v1
        with:
          app_name: Example
          app_identifier: com.example.app
          frontend_dist: dist

See Building with GitHub Actions for both approaches.

Signing is optional and uses only your own repository secrets; without them the build is unsigned. See Signing.

Building for Platforms

Desktopr supports building your app for multiple platforms with the following output formats:

Platform	Output Format
macOS	.dmg
Windows	.exe (NSIS), optional .msix
Linux	.AppImage, .deb, .rpm

Notes

TIP

Explore the documentation for the Bridge modules to extend your app’s functionality and integrate native features seamlessly.

WARNING

The first build takes a while because Rust compiles the whole runtime. Later builds reuse the src-tauri/target cache and are much faster.