Linux Overview

Bini.js allows you to build native Linux desktop applications using Tauri v2. Your React app is wrapped in a WebKitGTK binary, providing a native experience with full system access.

Requirements

Building Linux desktop apps requires different tools depending on your operating system. See the section for your OS below.

• On Linux: Node.js, Rust, and the WebKitGTK / GTK 3 development libraries from your package manager - everything runs locally.
• On Windows or macOS: Node.js, Git, a GitHub account, and the ability to push a repo. The Linux build itself runs on GitHub Actions.

Linux

On Linux you can scaffold, develop, and build the app entirely on your own machine - no CI required.

Step 1: Install the tools

Install Node.js 20.19.0 or higher, Rust via rustup, and the WebKitGTK development libraries. Pick your distribution:

$ sudo apt update
$ sudo apt install -y libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev

Step 2: Create the project

Create the Project

Create a new Bini.js project targeting Linux and install its dependencies:

$ npx create-bini-app@latest my-app --platform linux
$ cd my-app
$ npm install

Or use the interactive prompt and select Linux Desktop:

$ npx create-bini-app@latest

? Select target platform:
Web Application
Windows Desktop
> Linux Desktop
macOS Desktop
Android
iOS
 
↑↓ navigate • ⏎ select

Step 3: Develop and build

Run tauri:dev to open your app in a native window, then tauri:build to produce the AppImage:

$ npx create-bini-app@latest my-app --platform linux
$ cd my-app
$ npm install
$ npm run tauri:dev
$ npm run tauri:build

Windows

A native Linux .AppImage can be produced on Windows, but only through CI - Tauri relies on Linux-only toolchains (WebKitGTK, GTK 3, AppImage tooling). The Tauri team's own recommendation is to build Linux apps on an ubuntu-latest runner in CI.

Step 1: Install the tools

Install Node.js 20.19.0 or higher and Git for Windows - Download.

Step 2: Create the project

Create the Project

Create a new Bini.js project targeting Linux and install its dependencies:

$ npx create-bini-app@latest my-app --platform linux
$ cd my-app
$ npm install

Or use the interactive prompt and select Linux Desktop:

$ npx create-bini-app@latest

? Select target platform:
Web Application
Windows Desktop
> Linux Desktop
macOS Desktop
Android
iOS
 
↑↓ navigate • ⏎ select

Add the Build Workflow

The scaffold does not ship with a GitHub Actions workflow. You need to add one manually. Create the file .github/workflows/build-linux.yml inside your project with the following content:

# .github/workflows/build-linux.yml
name: Build Linux App

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  build-linux:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install system dependencies
        run: |
          sudo apt update
          sudo apt install -y libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable

      - name: Install dependencies
        run: npm install

      - name: Build Tauri app
        uses: tauri-apps/tauri-action@v0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tagName: app-v__VERSION__
          releaseName: 'App v__VERSION__'
          releaseDraft: true

Push to GitHub

Run npm run deploy and choose Linux. This initializes the repo, commits, and pushes everything to GitHub in one step:

$ npm run deploy

Once pushed, the workflow runs on a real Ubuntu runner and builds the AppImage.

Download the App

1. Open your repository on GitHub and go to the Actions tab.
2. Open the latest Build Linux App run.
3. Under Artifacts, download linux-build. Or, if a release was created, download the .AppImage from the Releases page.

macOS

A native Linux .AppImage cannot be produced on macOS - Tauri relies on Linux-only toolchains (WebKitGTK, GTK 3, AppImage tooling). The Tauri team's own recommendation is to build Linux apps on an ubuntu-latest runner in CI.

Step 1: Install the tools

Install Node.js 20.19.0 or higher and Git. Git comes with the Xcode command line tools - run xcode-select --install if you do not have it yet.

Step 2: Create the project

Create the Project

Create a new Bini.js project targeting Linux and install its dependencies:

$ npx create-bini-app@latest my-app --platform linux
$ cd my-app
$ npm install

Or use the interactive prompt and select Linux Desktop:

$ npx create-bini-app@latest

? Select target platform:
Web Application
Windows Desktop
> Linux Desktop
macOS Desktop
Android
iOS
 
↑↓ navigate • ⏎ select

Add the Build Workflow

The scaffold does not ship with a GitHub Actions workflow. You need to add one manually. Create the file .github/workflows/build-linux.yml inside your project with the following content:

# .github/workflows/build-linux.yml
name: Build Linux App

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  build-linux:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install system dependencies
        run: |
          sudo apt update
          sudo apt install -y libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable

      - name: Install dependencies
        run: npm install

      - name: Build Tauri app
        uses: tauri-apps/tauri-action@v0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tagName: app-v__VERSION__
          releaseName: 'App v__VERSION__'
          releaseDraft: true

Push to GitHub

Run npm run deploy and choose Linux. This initializes the repo, commits, and pushes everything to GitHub in one step:

$ npm run deploy

Once pushed, the workflow runs on a real Ubuntu runner and builds the AppImage.

Download the App

1. Open your repository on GitHub and go to the Actions tab.
2. Open the latest Build Linux App run.
3. Under Artifacts, download linux-build. Or, if a release was created, download the .AppImage from the Releases page.

Development

Running tauri:dev opens your app in a native Linux window. This requires a Linux machine with the requirements installed (see the Linux section):

$ npm run tauri:dev

This launches your app in a native Linux window with:

• Hot reload for frontend changes
• Native window with system tray support
• Access to Linux APIs
• Devtools for debugging

Building

Build a distributable Linux application. On Linux this runs locally; on Windows and macOS it runs in GitHub Actions (see those sections):

$ npm run tauri:build

The build outputs land in src-tauri/target/release/bundle/:

Output Files

• appimage/*.AppImage - Portable executable (recommended for distribution)
• deb/*.deb - Debian/Ubuntu package
• rpm/*.rpm - Fedora/RHEL package

Code Signing

Bini.js supports signed AppImage and binary distribution via the Tauri updater signing key. Generate a signing key with the Tauri CLI:

$ npm run tauri signer generate -- -w ~/.tauri/my-app.key

Store the private key contents and its password as GitHub secrets, and reference them in the workflow. The tauri-action step reads them from environment variables:

GitHub Actions workflow with signing

# .github/workflows/build-linux.yml
name: Build Linux App

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  build-linux:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install system dependencies
        run: |
          sudo apt update
          sudo apt install -y libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable

      - name: Install dependencies
        run: npm install

      - name: Build Tauri app
        uses: tauri-apps/tauri-action@v0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
        with:
          tagName: app-v__VERSION__
          releaseName: 'App v__VERSION__'
          releaseDraft: true