Skip to content

tauri-build.md

Latest commit

 

History

History
289 lines (220 loc) · 8.19 KB

tauri-build.md

File metadata and controls

289 lines (220 loc) · 8.19 KB
Raw

Building PearTree as a Desktop App (Tauri v2)

PearTree is wrapped with Tauri v2 to produce a native desktop application for macOS, Windows, and Linux from the existing plain HTML/JS frontend.

Prerequisites

All platforms

Tool Version Install
Rust stable (≥ 1.77) curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Node.js ≥ 18 LTS via nvm or direct installer

macOS extras

# Xcode Command Line Tools (provides clang, linker)
xcode-select --install

Linux extras

# Debian / Ubuntu
sudo apt update
sudo apt install -y \
  libwebkit2gtk-4.1-dev \
  libappindicator3-dev \
  librsvg2-dev \
  patchelf \
  build-essential \
  curl \
  libssl-dev \
  libgtk-3-dev \
  libayatana-appindicator3-dev

# Fedora / RHEL
sudo dnf install -y \
  webkit2gtk4.1-devel \
  openssl-devel \
  appimagetool \
  librsvg2-devel

Windows extras

Setup

  1. Clone / open the repository

    cd peartree

  2. Install Node dependencies (Tauri CLI)

    npm install

  3. Generate application icons

    Provide a square PNG source image (≥ 1024 × 1024 px, transparent background recommended):

    npx tauri icon path/to/your-icon.png

    This writes all required icon sizes into src-tauri/icons/.
    A temporary placeholder can be created with:

    # macOS / Linux – create a minimal 1024×1024 PNG if you don't have one yet
convert -size 1024x1024 xc:#005B68 \
  -fill '#BF4B43' -font Helvetica-Bold -pointsize 300 \
  -gravity center -annotate 0 'PT' \
  /tmp/peartree-icon.png
npx tauri icon /tmp/peartree-icon.png
# Or generate one from an existing image in the project:
npx tauri icon ui/img/peartree-icon.png

Development

Launches the app in a native window backed by a local file server with hot-reload of frontend assets:

npm run dev
# or
npx tauri dev

The window title, size, and CSP are taken from src-tauri/tauri.conf.json.

Note: The app loads Bootstrap CSS/Icons and marked.js from CDN. An active internet connection is required unless you vendor those assets locally (see Vendoring CDN assets below).

Production Build

npm run build
# or
npx tauri build

Bundles are written to src-tauri/target/release/bundle/:

Platform Format Location
macOS .app, .dmg macos/
Windows .exe (NSIS installer), .msi nsis/, msi/
Linux .AppImage, .deb, .rpm appimage/, deb/, rpm/

Build for specific target formats only

# macOS – .dmg only
npx tauri build --bundles dmg

# Linux – AppImage only
npx tauri build --bundles appimage

# Windows – NSIS installer only
npx tauri build --bundles nsis

Cross-compilation note: Tauri must be built on the target platform. Use CI (e.g. GitHub Actions) to produce builds for all three platforms from a single commit — see the Tauri GitHub Action.

Project Structure

peartree/
├── ui/                   ← all web assets (frontendDist)
│   ├── index.html        ← frontend entry point
│   ├── help.md           ← served as app content
│   ├── about.md          ← served as app content
│   ├── data/             ← bundled example tree files
│   ├── img/              ← images
│   └── js/               ← frontend ES modules
├── src-tauri/
│   ├── Cargo.toml        ← Rust crate manifest
│   ├── build.rs          ← Tauri build script
│   ├── tauri.conf.json   ← Tauri configuration
│   ├── capabilities/
│   │   └── default.json  ← permission capabilities
│   ├── icons/            ← generated by `tauri icon`
│   └── src/
│       ├── main.rs       ← native entry point
│       └── lib.rs        ← Tauri app setup
└── package.json          ← npm manifest (Tauri CLI)

Configuration

Key settings in src-tauri/tauri.conf.json:

Setting Default Description
app.windows[0].width 1400 Initial window width (px)
app.windows[0].height 900 Initial window height (px)
app.windows[0].minWidth 900 Minimum window width
app.windows[0].minHeight 600 Minimum window height
bundle.identifier org.articnetwork.peartree Reverse-domain bundle ID
bundle.category Science macOS App Store category

Vendoring CDN Assets (Optional)

To make the app work fully offline, replace the CDN links in index.html with locally bundled files:

  1. Download assets:

    mkdir -p vendor/css vendor/js
# Bootstrap (ARTIC theme)
curl -o vendor/css/bootstrap.min-artic.css \
  https://artic-network.github.io/sealion/bootstrap.min-artic.css
# Bootstrap Icons
curl -o vendor/css/bootstrap-icons.css \
  https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.1/font/bootstrap-icons.css
# Bootstrap Icons fonts
curl -o vendor/css/fonts/bootstrap-icons.woff2 \
  https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.1/font/fonts/bootstrap-icons.woff2
# marked.js
curl -o vendor/js/marked.min.js \
  https://cdn.jsdelivr.net/npm/marked@12/marked.min.js

  2. Update index.html <head> to use local paths:

    <link rel="stylesheet" href="vendor/css/bootstrap.min-artic.css" />
<link rel="stylesheet" href="vendor/css/bootstrap-icons.css" />
<script src="vendor/js/marked.min.js"></script>

GitHub Actions CI (cross-platform builds)

Create .github/workflows/release.yml:

name: Release

on:
  push:
    tags: ['v*']

jobs:
  release:
    permissions:
      contents: write
    strategy:
      fail-fast: false
      matrix:
        include:
          - platform: macos-latest
            args: '--target aarch64-apple-darwin'
          - platform: macos-latest
            args: '--target x86_64-apple-darwin'
          - platform: ubuntu-22.04
            args: ''
          - platform: windows-latest
            args: ''

    runs-on: ${{ matrix.platform }}
    steps:
      - uses: actions/checkout@v4

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

      - name: Install Rust stable
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.platform == 'macos-latest' && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}

      - name: Install Linux dependencies
        if: matrix.platform == 'ubuntu-22.04'
        run: |
          sudo apt-get update
          sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

      - run: npm install

      - uses: tauri-apps/tauri-action@v0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tagName: ${{ github.ref_name }}
          releaseName: 'PearTree ${{ github.ref_name }}'
          releaseBody: 'See the assets below for downloads.'
          releaseDraft: true
          prerelease: false
          args: ${{ matrix.args }}

Push a tag (git tag v0.1.0 && git push --tags) to trigger a draft release with installers for all platforms.

Troubleshooting

Problem Fix
tauri: command not found Run npm install first, then use npx tauri
error: linker 'cc' not found Install Xcode CLT (macOS) or build-essential (Linux)
WebKit not found Install libwebkit2gtk-4.1-dev (Linux)
Icons missing / build fails Run npx tauri icon <source.png> to generate src-tauri/icons/
CDN resources fail to load Check internet connection, or vendor assets locally (see above)
Window shows blank white page Ensure frontendDist in tauri.conf.json points to "../"