184 lines
9.7 KiB
Markdown
184 lines
9.7 KiB
Markdown
|
# Tauri
|
||
|
|
|
||
|
|
**Tauri** allows building a native application that can be installed on Windows, macOS and Linux.
|
||
|
|
|
||
|
|
Since it's based on native OS WebView, you must compile application separately for each target platform, meaning you cannot build a macOS application on a Windows machine, or vice versa. Each build must be done on its respective platform.
|
||
|
|
|
||
|
|
## Table of contents
|
||
|
|
|
||
|
|
- [Installation](#installation)
|
||
|
|
- [Upgrading dependencies](#upgrading-dependencies)
|
||
|
|
- [NPM scripts](#npm-scripts)
|
||
|
|
- [Implementation specifics](#implementation-specifics)
|
||
|
|
- [Accessing the Tauri API](#accessing-the-tauri-api)
|
||
|
|
- [Custom header on MacOS](#custom-header-on-macos)
|
||
|
|
- [Multiple windows support](#multiple-windows-support)
|
||
|
|
- [Notifications](#notifications)
|
||
|
|
- [Browser devtool](#browser-devtools)
|
||
|
|
- [Capabilities](#capabilities)
|
||
|
|
- [Autoupdates](#autoupdates)
|
||
|
|
- [GitHub workflow for release](#github-workflow-for-release)
|
||
|
|
- [Important links](#important-links)
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
|
||
|
|
To run Tauri locally, ensure that [Rust is installed](https://tauri.app/start/prerequisites/#rust).
|
||
|
|
|
||
|
|
## Upgrading dependencies
|
||
|
|
|
||
|
|
- To detect available upgrades for NPM modules, run:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Get outdated module
|
||
|
|
npm outdated @tauri-apps/{MODULE} # e.g. npm outdated @tauri-apps/cli
|
||
|
|
# or list all available versions
|
||
|
|
npm view @tauri-apps/{MODULE} versions -json
|
||
|
|
|
||
|
|
# Install a specific version
|
||
|
|
npm install @tauri-apps/cli@{VERSION}
|
||
|
|
# or install the latest version
|
||
|
|
npm install @tauri-apps/cli@latest
|
||
|
|
```
|
||
|
|
|
||
|
|
- To upgrade Rust (Cargo) modules, run:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Install the cargo-edit module for easier upgrade
|
||
|
|
cargo install cargo-edit
|
||
|
|
|
||
|
|
# Change to the `/tauri` directory
|
||
|
|
cd tauri
|
||
|
|
|
||
|
|
# Run the upgrade
|
||
|
|
cargo upgrade
|
||
|
|
```
|
||
|
|
|
||
|
|
For details on upgrading Tauri dependencies, refer to the [official documentation](https://tauri.app/develop/updating-dependencies/).
|
||
|
|
|
||
|
|
## NPM scripts
|
||
|
|
|
||
|
|
- `npm run tauri:dev` — run Tauri in development mode.
|
||
|
|
|
||
|
|
- `npm run tauri` — placeholder, which allows you to run [Tauri CLI](https://v2.tauri.app/reference/cli/) commands with `npm run tauri {COMMAND}`.
|
||
|
|
|
||
|
|
## Implementation specifics
|
||
|
|
|
||
|
|
### Accessing the Tauri API
|
||
|
|
|
||
|
|
The Tauri API, including any integrated plugins, is accessible via the `window.tauri` object. For type definitions, refer to the `src/types/tauri.ts` file.
|
||
|
|
|
||
|
|
If you have implemented [custom commands](https://tauri.app/develop/calling-rust/), ensure they are properly registered in the `src/util/tauri/initTauriApi.ts`
|
||
|
|
|
||
|
|
### Custom header on MacOS
|
||
|
|
|
||
|
|
Tauri currently has [some problems](https://github.com/tauri-apps/tauri/issues/13044) with custom titlebar style. Current implementation that uses native window handle would be removed when those problems are fixed.
|
||
|
|
|
||
|
|
### Multiple windows support
|
||
|
|
|
||
|
|
The Tauri main process exposes the `open_new_window` command, available as `window.tauri.openNewWindow`. This method can be used to open a new "child" closable window:
|
||
|
|
|
||
|
|
```typescript
|
||
|
|
openNewWindow: (url: string) => Promise<void>
|
||
|
|
```
|
||
|
|
|
||
|
|
### Notifications
|
||
|
|
|
||
|
|
The Tauri notifications plugin [overrides the default Notification web API](https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/notification/guest-js/init.ts#L56), so no additional function needs to be called to send a notification to the user.
|
||
|
|
|
||
|
|
**Important:**
|
||
|
|
|
||
|
|
- Clicking on notifications to open the appropriate chat is currently not possible. More details in the [issue](https://github.com/tauri-apps/plugins-workspace/issues/1903).
|
||
|
|
|
||
|
|
### Browser devtools
|
||
|
|
|
||
|
|
Browser DevTools context menu can be enabled by adding the `devtools` feature to the `tauri/Cargo.toml` file:
|
||
|
|
|
||
|
|
```rust
|
||
|
|
[dependencies]
|
||
|
|
tauri = { version = "...", features = ["...", "devtools"] }
|
||
|
|
```
|
||
|
|
|
||
|
|
For debug builds, DevTools are included by default through the `includeDebug` flag in the GitHub action. [More info](https://tauri.app/develop/debug/#webview-console)
|
||
|
|
|
||
|
|
### Capabilities
|
||
|
|
|
||
|
|
The `tauri/capabilities` folder provides fine-grained control over application windows and access to Tauri core, application, or plugin commands. These capabilities can be configured for different environments such as `development`, `staging` and `production`.
|
||
|
|
Keep them at minimum. For complex logic, consider implementing own command in Rust, rather than giving permissions to JS side.
|
||
|
|
|
||
|
|
Learn more about [capabilities](https://tauri.app/reference/acl/capability/) and [how to configure them for different windows or platforms](https://tauri.app/learn/security/capabilities-for-windows-and-platforms/).
|
||
|
|
|
||
|
|
## Autoupdates
|
||
|
|
|
||
|
|
The application's autoupdate cycle is managed using the [Updater](https://tauri.app/plugin/updater/) plugin.
|
||
|
|
|
||
|
|
Each time the "Package & Publish" GitHub workflow runs successfully, a new release is created in the publish repository. This release includes build artifacts and a `latest.json` file with a [JSON file](https://tauri.app/plugin/updater/#static-json-file) containing download links for each platform and signature tokens.
|
||
|
|
|
||
|
|
The frontend application polls for updates every 10 minutes and displays an "Update" button if an update is available.
|
||
|
|
|
||
|
|
**Important**: In development mode and for local builds, autoupdates are not available. Keys and other information are dynamically added within the GitHub action during the `Define Tauri configuration overrides` step.
|
||
|
|
|
||
|
|
## GitHub workflow for release
|
||
|
|
|
||
|
|
The build and release process for a Tauri application is managed using a GitHub workflow that leverages the official [Tauri Action](https://github.com/tauri-apps/tauri-action).
|
||
|
|
|
||
|
|
### List of variables and secrets
|
||
|
|
|
||
|
|
### Variables
|
||
|
|
|
||
|
|
| **Variable Name** | **Description** |
|
||
|
|
|----------------------|-------------------------------------------------------------------------------------------------------------------------------|
|
||
|
|
| `PUBLISH_REPO` | `{OWNER}/{REPO}` repository where published releases with artifacts will be pushed. |
|
||
|
|
| `NODE_VERSION` | Node.js version on which NPM modules installation and Tauri build should happen. |
|
||
|
|
| `BASE_URL` | Remote URL from which application content will be loaded |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Secrets - Generic
|
||
|
|
|
||
|
|
| **Secret Name** | **Description** |
|
||
|
|
|------------------|--------------------------------------------------------------------------------------|
|
||
|
|
| `GH_TOKEN` | GitHub access token with `repo` scope/permission, required to publish new releases. |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Secrets - Application Updates
|
||
|
|
|
||
|
|
| **Secret Name** | **Description** |
|
||
|
|
|-----------------------|-------------------------------------------------------------------------------------------------------------------------|
|
||
|
|
| `UPDATER_GIST_URL` | URL to GitHub gist (e.g., `https://gist.githubusercontent.com/GitHubUser/GistID/raw/updater.json`). Ensure `GH_TOKEN` has read/write access. |
|
||
|
|
| `UPDATER_GIST_ID` | GitHub gist ID (`GistID` from `UPDATER_GIST_URL` example). |
|
||
|
|
| `UPDATER_PUBLIC_KEY` | Public key to validate artifacts before installation. [More info](https://tauri.app/plugin/updater/#signing-updates). |
|
||
|
|
| `UPDATER_PRIVATE_KEY` | Private key used to sign installer files (generated with the same command as public key). |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Secrets - MacOS Signing
|
||
|
|
|
||
|
|
| **Secret Name** | **Description** |
|
||
|
|
|------------------------------|-------------------------------------------------------------------------------------|
|
||
|
|
| `APPLE_CERTIFICATE_BASE64` | Base64 string of the `.p12` certificate, exported from the keychain. |
|
||
|
|
| `APPLE_CERTIFICATE_PASSWORD` | Password for the `.p12` certificate. |
|
||
|
|
| `APPLE_SIGNING_IDENTITY` | Name of the keychain entry that contains the signing certificate. |
|
||
|
|
| `APPLE_ID` | Apple account email. |
|
||
|
|
| `APPLE_APP_SPECIFIC_PASSWORD`| Apple account [app-specific password](https://support.apple.com/en-ca/102654). |
|
||
|
|
| `APPLE_TEAM_ID` | Apple account [team ID](https://developer.apple.com/account#MembershipDetailsCard). |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Secrets - Windows Signing
|
||
|
|
|
||
|
|
| **Secret Name** | **Description** |
|
||
|
|
|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
|
||
|
|
| `SM_CLIENT_CERT_FILE_B64` | Base64 encoded version of the [authentication certificate](https://docs.digicert.com/en/software-trust-manager/ci-cd-integrations/plugins/github-custom-action-for-keypair-signing.html#create-an-authentication-certificate-426026). |
|
||
|
|
| `SM_CLIENT_CERT_PASSWORD` | Password for the authentication certificate. |
|
||
|
|
| `SM_HOST` | [Path to the DigiCert ONE portal with client authorization](https://docs.digicert.com/en/software-trust-manager/general/requirements.html#host-environment-367442). |
|
||
|
|
| `SM_API_KEY` | [API token](https://docs.digicert.com/en/software-trust-manager/ci-cd-integrations/plugins/github-custom-action-for-keypair-signing.html#create-an-api-token-426026) created with the authentication certificate. |
|
||
|
|
| `KEYPAIR_ALIAS` | Keypair alias for the [certificate keylocker](https://one.digicert.com/signingmanager/certificates-keylocker). |
|
||
|
|
|
||
|
|
|
||
|
|
## Important links
|
||
|
|
|
||
|
|
- [Rust documentation for Tauri](https://docs.rs/tauri/latest/tauri/)
|
||
|
|
- [Plugins documentation](https://tauri.app/plugin/)
|
||
|
|
- [Plugins GitHub repository](https://github.com/tauri-apps/plugins-workspace)
|