macOS Overview

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

Requirements

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

• On macOS: Node.js, Xcode Command Line Tools, Full Xcode, and Rust - everything runs locally.
• On Windows or Linux: Node.js, Git, a GitHub account, and the ability to push a repo. The macOS build itself runs on GitHub Actions.

macOS

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

Step 1: Install the tools

• Node.js 20.19.0 or higher
• Xcode Command Line Tools - run xcode-select --install
• Full Xcode (for building and notarization) - Download
• Rust via rustup

Step 2: Create the project

Create the Project

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

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

Or use the interactive prompt and select macOS 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 app bundle:

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

Windows

A native macOS .app cannot be produced on Windows - Tauri relies on macOS-only toolchains (Xcode, code signing, notarization). The Tauri team's own recommendation is to build macOS apps on a macos-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 macOS and install its dependencies:

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

Or use the interactive prompt and select macOS 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-macos.yml inside your project with the following content:

# .github/workflows/build-macos.yml
name: Build macOS App

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  build-macos:
    runs-on: macos-latest

    steps:
      - uses: actions/checkout@v4

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

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: aarch64-apple-darwin,x86_64-apple-darwin

      - 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 macOS. This initializes the repo, commits, and pushes everything to GitHub in one step:

$ npm run deploy

Once pushed, the workflow runs on a real macOS runner and builds the app bundle.

Download the App

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

Linux

A native macOS .app cannot be produced on Linux - Tauri relies on macOS-only toolchains (Xcode, code signing, notarization). The Tauri team's own recommendation is to build macOS apps on a macos-latest runner in CI.

Step 1: Install the tools

Install Node.js 20.19.0 or higher and Git with your package manager, for example sudo apt install git on Debian and Ubuntu.

Step 2: Create the project

Create the Project

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

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

Or use the interactive prompt and select macOS 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-macos.yml inside your project with the following content:

# .github/workflows/build-macos.yml
name: Build macOS App

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  build-macos:
    runs-on: macos-latest

    steps:
      - uses: actions/checkout@v4

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

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: aarch64-apple-darwin,x86_64-apple-darwin

      - 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 macOS. This initializes the repo, commits, and pushes everything to GitHub in one step:

$ npm run deploy

Once pushed, the workflow runs on a real macOS runner and builds the app bundle.

Download the App

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

Development

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

$ npm run tauri:dev

This launches your app in a native macOS window with:

• Hot reload for frontend changes
• Native window with menu bar integration
• Access to macOS APIs
• Devtools for debugging

Building

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

$ npm run tauri:build

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

Output Files

• macos/my-app.app - The app bundle
• dmg/*.dmg - Disk image for distribution (recommended)
• my-app.pkg - Installer package (if configured)

Code Signing

Bini.js supports Developer ID signing and notarization for macOS binaries. Configure signing in src-tauri/tauri.conf.json:

{
  "bundle": {
    "macOS": {
      "signingIdentity": "Developer ID Application: Your Name (TEAM_ID)",
      "entitlements": "entitlements.plist"
    }
  }
}

For GitHub Actions, store your Apple ID, app-specific password, and team ID as secrets and reference them in the workflow. The tauri-action step reads them from environment variables:

GitHub Actions workflow with signing

# .github/workflows/build-macos.yml
name: Build macOS App

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  build-macos:
    runs-on: macos-latest

    steps:
      - uses: actions/checkout@v4

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

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: aarch64-apple-darwin,x86_64-apple-darwin

      - name: Install dependencies
        run: npm install

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