mirror of
https://github.com/tauri-apps/tauri-docs.git
synced 2026-01-31 00:35:16 +01:00
Lorenzo Lewis
@@ -46,14 +46,21 @@ export default defineConfig({
|
||||
link: '/2/guide/create/',
|
||||
},
|
||||
{
|
||||
label: 'Concepts & Best Practices',
|
||||
link: '#',
|
||||
label: 'Upgrade & Migration',
|
||||
link: '2/guide/upgrade-migrate',
|
||||
},
|
||||
{
|
||||
label: 'Core Concepts',
|
||||
link: '2/guide/upgrade',
|
||||
},
|
||||
{
|
||||
label: 'Troubleshooting',
|
||||
link: '/2/guide/troubleshoot',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
label: 'Workflows',
|
||||
collapsed: true,
|
||||
label: 'Guides',
|
||||
items: [
|
||||
{
|
||||
label: 'Develop',
|
||||
@@ -75,15 +82,10 @@ export default defineConfig({
|
||||
label: 'Distribute',
|
||||
link: '#',
|
||||
},
|
||||
{
|
||||
label: 'Troubleshooting',
|
||||
link: '/2/guide/troubleshoot',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
label: 'Features',
|
||||
collapsed: true,
|
||||
label: 'Features & Recipes',
|
||||
items: [
|
||||
{
|
||||
label: 'App Storage',
|
||||
@@ -106,51 +108,20 @@ export default defineConfig({
|
||||
link: '#',
|
||||
},
|
||||
{
|
||||
label: 'More Features',
|
||||
link: '/2/guide/list',
|
||||
label: 'More Features & Recipes',
|
||||
link: '/2/recipe/list',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
label: 'Recipes',
|
||||
label: 'References (Autogenerated)',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{
|
||||
label: 'App Storage',
|
||||
link: '#',
|
||||
},
|
||||
{
|
||||
label: 'Commands',
|
||||
link: '#',
|
||||
},
|
||||
{
|
||||
label: 'Multi-Window',
|
||||
link: '#',
|
||||
},
|
||||
{
|
||||
label: 'Updater',
|
||||
link: '#',
|
||||
},
|
||||
{
|
||||
label: 'Window Customization',
|
||||
link: '#',
|
||||
},
|
||||
{
|
||||
label: 'More Features',
|
||||
link: '/2/guide/list',
|
||||
},
|
||||
],
|
||||
},
|
||||
|
||||
{
|
||||
label: 'Reference (Autogenerated)',
|
||||
autogenerate: { directory: '2/reference' },
|
||||
},
|
||||
|
||||
{
|
||||
label: 'Tauri v1 (temporary)',
|
||||
collapsed: true,
|
||||
autogenerate: { directory: '1' },
|
||||
label: 'Tauri v1',
|
||||
link: 'https://tauri.app',
|
||||
},
|
||||
],
|
||||
locales,
|
||||
|
||||
@@ -1,359 +0,0 @@
|
||||
---
|
||||
title: cli
|
||||
---
|
||||
|
||||
import Command from '@theme/Command'
|
||||
import Tabs from '@theme/Tabs'
|
||||
import TabItem from '@theme/TabItem'
|
||||
|
||||
## `info`
|
||||
|
||||
<Command name="info" />
|
||||
|
||||
```
|
||||
Usage: cargo-tauri info [OPTIONS]
|
||||
|
||||
Options:
|
||||
--interactive Interactive mode to apply automatic fixes
|
||||
-v, --verbose... Enables verbose logging
|
||||
-h, --help Print help
|
||||
-V, --version Print version
|
||||
```
|
||||
|
||||
It shows a concise list of information about the environment, Rust, Node.js and their versions as well as some relevant configurations.
|
||||
|
||||
:::info
|
||||
This command is pretty helpful when you need to have a quick overview of your application. When requesting some help, it can be useful that you share this report with us.
|
||||
:::
|
||||
|
||||
## `init`
|
||||
|
||||
<Command name="init" />
|
||||
|
||||
```
|
||||
Usage: cargo-tauri init [OPTIONS]
|
||||
|
||||
Options:
|
||||
--ci
|
||||
Skip prompting for values
|
||||
-v, --verbose...
|
||||
Enables verbose logging
|
||||
-f, --force
|
||||
Force init to overwrite the src-tauri folder
|
||||
-l, --log
|
||||
Enables logging
|
||||
-d, --directory <DIRECTORY>
|
||||
Set target directory for init [default: /home/runner/work/tauri-docs/tauri-docs]
|
||||
-t, --tauri-path <TAURI_PATH>
|
||||
Path of the Tauri project to use (relative to the cwd)
|
||||
-A, --app-name <APP_NAME>
|
||||
Name of your Tauri application
|
||||
-W, --window-title <WINDOW_TITLE>
|
||||
Window title of your Tauri application
|
||||
-D, --dist-dir <DIST_DIR>
|
||||
Web assets location, relative to <project-dir>/src-tauri
|
||||
-P, --dev-path <DEV_PATH>
|
||||
Url of your dev server
|
||||
--before-dev-command <BEFORE_DEV_COMMAND>
|
||||
A shell command to run before `tauri dev` kicks in
|
||||
--before-build-command <BEFORE_BUILD_COMMAND>
|
||||
A shell command to run before `tauri build` kicks in
|
||||
-h, --help
|
||||
Print help
|
||||
-V, --version
|
||||
Print version
|
||||
```
|
||||
|
||||
## `plugin init`
|
||||
|
||||
<Command name="plugin init" />
|
||||
|
||||
```
|
||||
Usage: cargo-tauri plugin init [OPTIONS] --name <PLUGIN_NAME>
|
||||
|
||||
Options:
|
||||
-n, --name <PLUGIN_NAME> Name of your Tauri plugin
|
||||
-v, --verbose... Enables verbose logging
|
||||
--api Initializes a Tauri plugin with TypeScript API
|
||||
-d, --directory <DIRECTORY> Set target directory for init [default: /home/runner/work/tauri-docs/tauri-docs]
|
||||
-t, --tauri-path <TAURI_PATH> Path of the Tauri project to use (relative to the cwd)
|
||||
-a, --author <AUTHOR> Author name
|
||||
-h, --help Print help
|
||||
-V, --version Print version
|
||||
```
|
||||
|
||||
## `dev`
|
||||
|
||||
<Command name="dev" />
|
||||
|
||||
```
|
||||
Usage: cargo-tauri dev [OPTIONS] [ARGS]...
|
||||
|
||||
Arguments:
|
||||
[ARGS]... Command line arguments passed to the runner. Arguments after `--` are passed to the application
|
||||
|
||||
Options:
|
||||
-r, --runner <RUNNER> Binary to use to run the application
|
||||
-v, --verbose... Enables verbose logging
|
||||
-t, --target <TARGET> Target triple to build against
|
||||
-f, --features [<FEATURES>...] List of cargo features to activate
|
||||
-e, --exit-on-panic Exit on panic
|
||||
-c, --config <CONFIG> JSON string or path to JSON file to merge with tauri.conf.json
|
||||
--release Run the code in release mode
|
||||
--no-watch Disable the file watcher
|
||||
--no-dev-server Disable the dev server for static files
|
||||
--port <PORT> Specify port for the dev server for static files. Defaults to 1430 Can also be set using `TAURI_DEV_SERVER_PORT` env var
|
||||
-h, --help Print help
|
||||
-V, --version Print version
|
||||
```
|
||||
|
||||
This command will open the WebView in development mode. It makes use of the `build.devPath` property from your `src-tauri/tauri.conf.json` file.
|
||||
|
||||
If you have entered a command to the `build.beforeDevCommand` property, this one will be executed before the `dev` command.
|
||||
|
||||
**[See more about the configuration.](./config.md#build)**
|
||||
|
||||
:::caution Troubleshooting
|
||||
If you're not using `build.beforeDevCommand`, make sure your `build.devPath` is correct and, if using a development server, that it's started before using this command.
|
||||
:::
|
||||
|
||||
## `build`
|
||||
|
||||
<Command name="build" />
|
||||
|
||||
```
|
||||
Usage: cargo-tauri build [OPTIONS] [ARGS]...
|
||||
|
||||
Arguments:
|
||||
[ARGS]...
|
||||
Command line arguments passed to the runner
|
||||
|
||||
Options:
|
||||
-r, --runner <RUNNER>
|
||||
Binary to use to build the application, defaults to `cargo`
|
||||
|
||||
-v, --verbose...
|
||||
Enables verbose logging
|
||||
|
||||
-d, --debug
|
||||
Builds with the debug flag
|
||||
|
||||
-t, --target <TARGET>
|
||||
Target triple to build against.
|
||||
|
||||
It must be one of the values outputted by `$rustc --print target-list` or `universal-apple-darwin` for an universal macOS application.
|
||||
|
||||
Note that compiling an universal macOS application requires both `aarch64-apple-darwin` and `x86_64-apple-darwin` targets to be installed.
|
||||
|
||||
-f, --features [<FEATURES>...]
|
||||
Space or comma separated list of features to activate
|
||||
|
||||
-b, --bundles [<BUNDLES>...]
|
||||
Space or comma separated list of bundles to package.
|
||||
|
||||
Each bundle must be one of `deb`, `appimage`, `msi`, `app` or `dmg` on MacOS and `updater` on all platforms. If `none` is specified, the bundler will be skipped.
|
||||
|
||||
Note that the `updater` bundle is not automatically added so you must specify it if the updater is enabled.
|
||||
|
||||
-c, --config <CONFIG>
|
||||
JSON string or path to JSON file to merge with tauri.conf.json
|
||||
|
||||
--ci
|
||||
Skip prompting for values
|
||||
|
||||
-h, --help
|
||||
Print help (see a summary with '-h')
|
||||
|
||||
-V, --version
|
||||
Print version
|
||||
```
|
||||
|
||||
This command will bundle your application, either in production mode or debug mode if you used the `--debug` flag. It makes use of the `build.distDir` property from your `src-tauri/tauri.conf.json` file.
|
||||
|
||||
If you have entered a command to the `build.beforeBuildCommand` property, this one will be executed before the `build` command.
|
||||
|
||||
**[See more about the configuration.](./config.md#build)**
|
||||
|
||||
## `icon`
|
||||
|
||||
<Command name="icon" />
|
||||
|
||||
```
|
||||
Usage: cargo-tauri icon [OPTIONS] [INPUT]
|
||||
|
||||
Arguments:
|
||||
[INPUT] Path to the source icon (png, 1240x1240px with transparency) [default: ./app-icon.png]
|
||||
|
||||
Options:
|
||||
-o, --output <OUTPUT> Output directory. Default: 'icons' directory next to the tauri.conf.json file
|
||||
-v, --verbose... Enables verbose logging
|
||||
-p, --png <PNG> Custom PNG icon sizes to generate. When set, the default icons are not generated
|
||||
-h, --help Print help
|
||||
-V, --version Print version
|
||||
```
|
||||
|
||||
For more information, check out the complete [Tauri Icon Guide](../guides/features/icons.md).
|
||||
|
||||
## `completions`
|
||||
|
||||
<Command name="completions" />
|
||||
|
||||
```
|
||||
Usage: cargo-tauri completions [OPTIONS] --shell <SHELL>
|
||||
|
||||
Options:
|
||||
-s, --shell <SHELL> Shell to generate a completion script for. [possible values: bash, elvish, fish, powershell, zsh]
|
||||
-v, --verbose... Enables verbose logging
|
||||
-o, --output <OUTPUT> Output file for the shell completions. By default the completions are printed to stdout
|
||||
-h, --help Print help
|
||||
-V, --version Print version
|
||||
```
|
||||
|
||||
The Tauri CLI can generate shell completions for Bash, Zsh, PowerShell and Fish.
|
||||
|
||||
Here are some instructions to configure Bash, Zsh and PowerShell. If you face an issue, please follow your shell's instructions instead. Note that it is recommended to check the generated completions script before executing it for security reasons.
|
||||
|
||||
### Bash
|
||||
|
||||
Get the Bash completions and move to a known folder:
|
||||
|
||||
<Tabs groupId="package-manager">
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm run tauri completions -- --shell bash > tauri.sh
|
||||
mv tauri.sh /usr/local/etc/bash_completion.d/tauri.bash
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Yarn">
|
||||
|
||||
```shell
|
||||
yarn tauri completions --shell bash > tauri.sh
|
||||
mv tauri.sh /usr/local/etc/bash_completion.d/tauri.bash
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="pnpm">
|
||||
|
||||
```shell
|
||||
pnpm tauri completions --shell bash > tauri.sh
|
||||
mv tauri.sh /usr/local/etc/bash_completion.d/tauri.bash
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Cargo">
|
||||
|
||||
```shell
|
||||
cargo tauri completions --shell bash > tauri.sh
|
||||
mv tauri.sh /usr/local/etc/bash_completion.d/tauri.bash
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
Load the completions script by adding the following to `.bashrc`:
|
||||
|
||||
```shell
|
||||
source /usr/local/etc/bash_completion.d/tauri.bash
|
||||
```
|
||||
|
||||
### Zsh
|
||||
|
||||
Get the Zsh completions and move to a known folder:
|
||||
|
||||
<Tabs groupId="package-manager">
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm run tauri completions -- --shell zsh > completions.zsh
|
||||
mv completions.zsh $HOME/.completions/_tauri
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Yarn">
|
||||
|
||||
```shell
|
||||
yarn tauri completions --shell zsh > completions.zsh
|
||||
mv completions.zsh $HOME/.completions/_tauri
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="pnpm">
|
||||
|
||||
```shell
|
||||
pnpm tauri completions --shell zsh > completions.zsh
|
||||
mv completions.zsh $HOME/.completions/_tauri
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Cargo">
|
||||
|
||||
```shell
|
||||
cargo tauri completions --shell zsh > completions.zsh
|
||||
mv completions.zsh $HOME/.completions/_tauri
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
Load the completions folder using fpath adding the following to `.zshrc`:
|
||||
|
||||
```shell
|
||||
fpath=(~/.completions $fpath)
|
||||
autoload -U compinit
|
||||
```
|
||||
|
||||
### PowerShell
|
||||
|
||||
Get the PowerShell completions and add it to the `$profile` file to execute it on all sessions:
|
||||
|
||||
<Tabs groupId="package-manager">
|
||||
<TabItem value="npm">
|
||||
|
||||
```powershell
|
||||
npm run tauri completions -- --shell powershell > ((Split-Path -Path $profile)+"\_tauri.ps1")
|
||||
Add-Content -Path $profile -Value '& "$PSScriptRoot\_tauri.ps1"'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Yarn">
|
||||
|
||||
```powershell
|
||||
yarn tauri completions --shell powershell > ((Split-Path -Path $profile)+"\_tauri.ps1")
|
||||
Add-Content -Path $profile -Value '& "$PSScriptRoot\_tauri.ps1"'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="pnpm">
|
||||
|
||||
```powershell
|
||||
pnpm tauri completions --shell powershell > ((Split-Path -Path $profile)+"\_tauri.ps1")
|
||||
Add-Content -Path $profile -Value '& "$PSScriptRoot\_tauri.ps1"'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Cargo">
|
||||
|
||||
```powershell
|
||||
cargo tauri completions --shell powershell > ((Split-Path -Path $profile)+"\_tauri.ps1")
|
||||
Add-Content -Path $profile -Value '& "$PSScriptRoot\_tauri.ps1"'
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## `version`
|
||||
|
||||
<Command name="--version" />
|
||||
|
||||
```
|
||||
Description
|
||||
Returns the current version of tauri
|
||||
```
|
||||
|
||||
This command will show the current version of Tauri.
|
||||
|
||||
## CLI usage
|
||||
|
||||
See more about the usage through this [complete guide](../guides/development/development-cycle.md).
|
||||
@@ -1,958 +0,0 @@
|
||||
---
|
||||
title: config
|
||||
---
|
||||
|
||||
# Configuration
|
||||
|
||||
The Tauri configuration object. It is read from a file where you can define your frontend assets, configure the bundler, enable the app updater, define a system tray, enable APIs via the allowlist and more.
|
||||
|
||||
The configuration file is generated by the [`tauri init`](https://tauri.app/v1/api/cli#init) command that lives in your Tauri application source directory (src-tauri).
|
||||
|
||||
Once generated, you may modify it at will to customize your Tauri application.
|
||||
|
||||
## File Formats
|
||||
|
||||
By default, the configuration is defined as a JSON file named `tauri.conf.json`.
|
||||
|
||||
Tauri also supports JSON5 and TOML files via the `config-json5` and `config-toml` Cargo features, respectively. The JSON5 file name must be either `tauri.conf.json` or `tauri.conf.json5`. The TOML file name is `Tauri.toml`.
|
||||
|
||||
## Platform-Specific Configuration
|
||||
|
||||
In addition to the default configuration file, Tauri can read a platform-specific configuration from `tauri.linux.conf.json`, `tauri.windows.conf.json`, and `tauri.macos.conf.json` (or `Tauri.linux.toml`, `Tauri.windows.toml` and `Tauri.macos.toml` if the `Tauri.toml` format is used), which gets merged with the main configuration object.
|
||||
|
||||
## Configuration Structure
|
||||
|
||||
The configuration is composed of the following objects:
|
||||
|
||||
- [`package`](#packageconfig): Package settings
|
||||
- [`tauri`](#tauriconfig): The Tauri config
|
||||
- [`build`](#buildconfig): The build configuration
|
||||
- [`plugins`](#pluginconfig): The plugins config
|
||||
|
||||
```json title="Example tauri.config.json file"
|
||||
{
|
||||
"build": {
|
||||
"beforeBuildCommand": "",
|
||||
"beforeDevCommand": "",
|
||||
"devPath": "../dist",
|
||||
"distDir": "../dist"
|
||||
},
|
||||
"package": {
|
||||
"productName": "tauri-app",
|
||||
"version": "0.1.0"
|
||||
},
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"all": true
|
||||
},
|
||||
"bundle": {},
|
||||
"security": {
|
||||
"csp": null
|
||||
},
|
||||
"updater": {
|
||||
"active": false
|
||||
},
|
||||
"windows": [
|
||||
{
|
||||
"fullscreen": false,
|
||||
"height": 600,
|
||||
"resizable": true,
|
||||
"title": "Tauri App",
|
||||
"width": 800
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ---------------------- | ------------------------ |
|
||||
| <div className="anchor-with-padding" id="configuration.package">`package`<a class="hash-link" href="#configuration.package"></a></div> | [`PackageConfig`](#packageconfig) | [view](#packageconfig) | Package settings. |
|
||||
| <div className="anchor-with-padding" id="configuration.tauri">`tauri`<a class="hash-link" href="#configuration.tauri"></a></div> | [`TauriConfig`](#tauriconfig) | [view](#tauriconfig) | The Tauri configuration. |
|
||||
| <div className="anchor-with-padding" id="configuration.build">`build`<a class="hash-link" href="#configuration.build"></a></div> | [`BuildConfig`](#buildconfig) | [view](#buildconfig) | The build configuration. |
|
||||
| <div className="anchor-with-padding" id="configuration.plugins">`plugins`<a class="hash-link" href="#configuration.plugins"></a></div> | [`PluginConfig`](#pluginconfig) | [view](#pluginconfig) | The plugins config. |
|
||||
|
||||
### PackageConfig
|
||||
|
||||
The package configuration.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="packageconfig.productname">`productName`<a class="hash-link" href="#packageconfig.productname"></a></div> | string? | _null_ | App name. |
|
||||
| <div className="anchor-with-padding" id="packageconfig.version">`version`<a class="hash-link" href="#packageconfig.version"></a></div> | string? | _null_ | App version. It is a semver version number or a path to a `package.json` file containing the `version` field. If removed the version number from `Cargo.toml` is used. |
|
||||
|
||||
### TauriConfig
|
||||
|
||||
The Tauri configuration object.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| <div className="anchor-with-padding" id="tauriconfig.pattern">`pattern`<a class="hash-link" href="#tauriconfig.pattern"></a></div> | [`PatternKind`](#patternkind) | [view](#patternkind) | The pattern to use. |
|
||||
| <div className="anchor-with-padding" id="tauriconfig.windows">`windows`<a class="hash-link" href="#tauriconfig.windows"></a></div> | [`WindowConfig`](#windowconfig) | [] | The windows configuration. |
|
||||
| <div className="anchor-with-padding" id="tauriconfig.cli">`cli`<a class="hash-link" href="#tauriconfig.cli"></a></div> | [`CliConfig`](#cliconfig)? | [view](#cliconfig) | The CLI configuration. |
|
||||
| <div className="anchor-with-padding" id="tauriconfig.bundle">`bundle`<a class="hash-link" href="#tauriconfig.bundle"></a></div> | [`BundleConfig`](#bundleconfig) | [view](#bundleconfig) | The bundler configuration. |
|
||||
| <div className="anchor-with-padding" id="tauriconfig.allowlist">`allowlist`<a class="hash-link" href="#tauriconfig.allowlist"></a></div> | [`AllowlistConfig`](#allowlistconfig) | [view](#allowlistconfig) | The allowlist configuration. |
|
||||
| <div className="anchor-with-padding" id="tauriconfig.security">`security`<a class="hash-link" href="#tauriconfig.security"></a></div> | [`SecurityConfig`](#securityconfig) | [view](#securityconfig) | Security configuration. |
|
||||
| <div className="anchor-with-padding" id="tauriconfig.updater">`updater`<a class="hash-link" href="#tauriconfig.updater"></a></div> | [`UpdaterConfig`](#updaterconfig) | [view](#updaterconfig) | The updater configuration. |
|
||||
| <div className="anchor-with-padding" id="tauriconfig.systemtray">`systemTray`<a class="hash-link" href="#tauriconfig.systemtray"></a></div> | [`SystemTrayConfig`](#systemtrayconfig)? | [view](#systemtrayconfig) | Configuration for app system tray. |
|
||||
| <div className="anchor-with-padding" id="tauriconfig.macosprivateapi">`macOSPrivateApi`<a class="hash-link" href="#tauriconfig.macosprivateapi"></a></div> | boolean | `false` | MacOS private API configuration. Enables the transparent background API and sets the `fullScreenEnabled` preference to `true`. |
|
||||
|
||||
#### PatternKind
|
||||
|
||||
The application pattern.
|
||||
|
||||
Can be any **ONE** of the following types:
|
||||
|
||||
- `{ "use": "brownfield" }`: Brownfield pattern.
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ---------------------------------------------------------------------------------------------------------------------- | ----------------------- | ------- | ----------- |
|
||||
| <div className="anchor-with-padding" id="patternkind.use">`use`<a class="hash-link" href="#patternkind.use"></a></div> | "brownfield" (required) | | undefined |
|
||||
|
||||
- `{ "use": "isolation", "options": { "dir": string } }`: Isolation pattern. Recommended for security purposes.
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------- | ----------- |
|
||||
| <div className="anchor-with-padding" id="patternkind.use">`use`<a class="hash-link" href="#patternkind.use"></a></div> | "isolation" (required) | | undefined |
|
||||
| <div className="anchor-with-padding" id="patternkind.options">`options`<a class="hash-link" href="#patternkind.options"></a></div> | { "dir": string } (required) | | undefined |
|
||||
|
||||
#### WindowConfig
|
||||
|
||||
The window configuration object.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| <div className="anchor-with-padding" id="windowconfig.label">`label`<a class="hash-link" href="#windowconfig.label"></a></div> | string | _null_ | The window identifier. It must be alphanumeric. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.url">`url`<a class="hash-link" href="#windowconfig.url"></a></div> | [`WindowUrl`](#windowurl) | [view](#windowurl) | The window webview URL. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.useragent">`userAgent`<a class="hash-link" href="#windowconfig.useragent"></a></div> | string? | _null_ | The user agent for the webview |
|
||||
| <div className="anchor-with-padding" id="windowconfig.filedropenabled">`fileDropEnabled`<a class="hash-link" href="#windowconfig.filedropenabled"></a></div> | boolean | `true` | Whether the file drop is enabled or not on the webview. By default it is enabled.<br /><br />Disabling it is required to use drag and drop on the frontend on Windows. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.center">`center`<a class="hash-link" href="#windowconfig.center"></a></div> | boolean | `false` | Whether or not the window starts centered or not. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.x">`x`<a class="hash-link" href="#windowconfig.x"></a></div> | number? _(format: `double`)_ | _null_ | The horizontal position of the window's top left corner |
|
||||
| <div className="anchor-with-padding" id="windowconfig.y">`y`<a class="hash-link" href="#windowconfig.y"></a></div> | number? _(format: `double`)_ | _null_ | The vertical position of the window's top left corner |
|
||||
| <div className="anchor-with-padding" id="windowconfig.width">`width`<a class="hash-link" href="#windowconfig.width"></a></div> | number _(format: `double`)_ | `800` | The window width. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.height">`height`<a class="hash-link" href="#windowconfig.height"></a></div> | number _(format: `double`)_ | `600` | The window height. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.minwidth">`minWidth`<a class="hash-link" href="#windowconfig.minwidth"></a></div> | number? _(format: `double`)_ | _null_ | The min window width. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.minheight">`minHeight`<a class="hash-link" href="#windowconfig.minheight"></a></div> | number? _(format: `double`)_ | _null_ | The min window height. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.maxwidth">`maxWidth`<a class="hash-link" href="#windowconfig.maxwidth"></a></div> | number? _(format: `double`)_ | _null_ | The max window width. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.maxheight">`maxHeight`<a class="hash-link" href="#windowconfig.maxheight"></a></div> | number? _(format: `double`)_ | _null_ | The max window height. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.resizable">`resizable`<a class="hash-link" href="#windowconfig.resizable"></a></div> | boolean | `true` | Whether the window is resizable or not. When resizable is set to false, native window's maximize button is automatically disabled. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.maximizable">`maximizable`<a class="hash-link" href="#windowconfig.maximizable"></a></div> | boolean | `true` | Whether the window's native maximize button is enabled or not. If resizable is set to false, this setting is ignored.<br /><br />## Platform-specific<br /><br />- **macOS:** Disables the "zoom" button in the window titlebar, which is also used to enter fullscreen mode.<br />- **Linux / iOS / Android:** Unsupported. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.minimizable">`minimizable`<a class="hash-link" href="#windowconfig.minimizable"></a></div> | boolean | `true` | Whether the window's native minimize button is enabled or not.<br /><br />## Platform-specific<br /><br />- **Linux / iOS / Android:** Unsupported. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.closable">`closable`<a class="hash-link" href="#windowconfig.closable"></a></div> | boolean | `true` | Whether the window's native close button is enabled or not.<br /><br />## Platform-specific<br /><br />- **Linux:** "GTK+ will do its best to convince the window manager not to show a close button. Depending on the system, this function may not have any effect when called on a window that is already visible"<br />- **iOS / Android:** Unsupported. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.title">`title`<a class="hash-link" href="#windowconfig.title"></a></div> | string | _null_ | The window title. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.fullscreen">`fullscreen`<a class="hash-link" href="#windowconfig.fullscreen"></a></div> | boolean | `false` | Whether the window starts as fullscreen or not. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.focus">`focus`<a class="hash-link" href="#windowconfig.focus"></a></div> | boolean | `true` | Whether the window will be initially focused or not. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.transparent">`transparent`<a class="hash-link" href="#windowconfig.transparent"></a></div> | boolean | `false` | Whether the window is transparent or not.<br /><br />Note that on `macOS` this requires the `macos-private-api` feature flag, enabled under `tauri > macOSPrivateApi`. WARNING: Using private APIs on `macOS` prevents your application from being accepted to the `App Store`. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.maximized">`maximized`<a class="hash-link" href="#windowconfig.maximized"></a></div> | boolean | `false` | Whether the window is maximized or not. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.visible">`visible`<a class="hash-link" href="#windowconfig.visible"></a></div> | boolean | `true` | Whether the window is visible or not. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.decorations">`decorations`<a class="hash-link" href="#windowconfig.decorations"></a></div> | boolean | `true` | Whether the window should have borders and bars. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.alwaysontop">`alwaysOnTop`<a class="hash-link" href="#windowconfig.alwaysontop"></a></div> | boolean | `false` | Whether the window should always be on top of other windows. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.contentprotected">`contentProtected`<a class="hash-link" href="#windowconfig.contentprotected"></a></div> | boolean | `false` | Prevents the window contents from being captured by other apps. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.skiptaskbar">`skipTaskbar`<a class="hash-link" href="#windowconfig.skiptaskbar"></a></div> | boolean | `false` | If `true`, hides the window icon from the taskbar on Windows and Linux. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.theme">`theme`<a class="hash-link" href="#windowconfig.theme"></a></div> | [`Theme`](#theme)? | [view](#theme) | The initial window theme. Defaults to the system theme. Only implemented on Windows and macOS 10.14+. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.titlebarstyle">`titleBarStyle`<a class="hash-link" href="#windowconfig.titlebarstyle"></a></div> | [`TitleBarStyle`](#titlebarstyle) | [view](#titlebarstyle) | The style of the macOS title bar. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.hiddentitle">`hiddenTitle`<a class="hash-link" href="#windowconfig.hiddentitle"></a></div> | boolean | `false` | If `true`, sets the window title to be hidden on macOS. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.acceptfirstmouse">`acceptFirstMouse`<a class="hash-link" href="#windowconfig.acceptfirstmouse"></a></div> | boolean | `false` | Whether clicking an inactive window also clicks through to the webview on macOS. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.tabbingidentifier">`tabbingIdentifier`<a class="hash-link" href="#windowconfig.tabbingidentifier"></a></div> | string? | _null_ | Defines the window [tabbing identifier](https://developer.apple.com/documentation/appkit/nswindow/1644704-tabbingidentifier) for macOS.<br /><br />Windows with matching tabbing identifiers will be grouped together. If the tabbing identifier is not set, automatic tabbing will be disabled. |
|
||||
| <div className="anchor-with-padding" id="windowconfig.additionalbrowserargs">`additionalBrowserArgs`<a class="hash-link" href="#windowconfig.additionalbrowserargs"></a></div> | string? | _null_ | Defines additional browser arguments on Windows. By default wry passes `--disable-features=msWebOOUI,msPdfOOUI,msSmartScreenProtection` so if you use this method, you also need to disable these components by yourself if you want. |
|
||||
|
||||
##### WindowUrl
|
||||
|
||||
An URL to open on a Tauri webview window.
|
||||
|
||||
Can be any of the following types:
|
||||
|
||||
- `string` _(format: `uri`)_: An external URL.
|
||||
- `string`: The path portion of an app URL. For instance, to load `tauri://localhost/users/john`, you can simply provide `users/john` in this configuration.
|
||||
|
||||
##### Theme
|
||||
|
||||
System theme.
|
||||
|
||||
Can be any **ONE** of the following types:
|
||||
|
||||
- "Light": Light theme.
|
||||
- "Dark": Dark theme.
|
||||
|
||||
##### TitleBarStyle
|
||||
|
||||
How the window title bar should be displayed on macOS.
|
||||
|
||||
Can be any **ONE** of the following types:
|
||||
|
||||
- "Visible": A normal title bar.
|
||||
- "Transparent": Makes the title bar transparent, so the window background color is shown instead.
|
||||
|
||||
Useful if you don't need to have actual HTML under the title bar. This lets you avoid the caveats of using `TitleBarStyle::Overlay`. Will be more useful when Tauri lets you set a custom window background color.
|
||||
|
||||
- "Overlay": Shows the title bar as a transparent overlay over the window's content.
|
||||
|
||||
Keep in mind:
|
||||
|
||||
- The height of the title bar is different on different OS versions, which can lead to window the controls and title not being where you don't expect.
|
||||
- You need to define a custom drag region to make your window draggable, however due to a limitation you can't drag the window when it's not in focus <https://github.com/tauri-apps/tauri/issues/4316>.
|
||||
- The color of the window title depends on the system theme.
|
||||
|
||||
#### CliConfig
|
||||
|
||||
describes a CLI configuration
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="cliconfig.description">`description`<a class="hash-link" href="#cliconfig.description"></a></div> | string? | _null_ | Command description which will be shown on the help information. |
|
||||
| <div className="anchor-with-padding" id="cliconfig.longdescription">`longDescription`<a class="hash-link" href="#cliconfig.longdescription"></a></div> | string? | _null_ | Command long description which will be shown on the help information. |
|
||||
| <div className="anchor-with-padding" id="cliconfig.beforehelp">`beforeHelp`<a class="hash-link" href="#cliconfig.beforehelp"></a></div> | string? | _null_ | Adds additional help information to be displayed in addition to auto-generated help. This information is displayed before the auto-generated help information. This is often used for header information. |
|
||||
| <div className="anchor-with-padding" id="cliconfig.afterhelp">`afterHelp`<a class="hash-link" href="#cliconfig.afterhelp"></a></div> | string? | _null_ | Adds additional help information to be displayed in addition to auto-generated help. This information is displayed after the auto-generated help information. This is often used to describe how to use the arguments, or caveats to be noted. |
|
||||
| <div className="anchor-with-padding" id="cliconfig.args">`args`<a class="hash-link" href="#cliconfig.args"></a></div> | [`CliArg`](#cliarg)? | _null_ | List of arguments for the command |
|
||||
| <div className="anchor-with-padding" id="cliconfig.subcommands">`subcommands`<a class="hash-link" href="#cliconfig.subcommands"></a></div> | [`CliConfig`](#cliconfig)? | _null_ | List of subcommands of this command |
|
||||
|
||||
##### CliArg
|
||||
|
||||
A CLI argument definition.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="cliarg.short">`short`<a class="hash-link" href="#cliarg.short"></a></div> | string? | _null_ | The short version of the argument, without the preceding -.<br /><br />NOTE: Any leading `-` characters will be stripped, and only the first non-character will be used as the short version. |
|
||||
| <div className="anchor-with-padding" id="cliarg.name">`name`<a class="hash-link" href="#cliarg.name"></a></div> | string (required) | | The unique argument name |
|
||||
| <div className="anchor-with-padding" id="cliarg.description">`description`<a class="hash-link" href="#cliarg.description"></a></div> | string? | _null_ | The argument description which will be shown on the help information. Typically, this is a short (one line) description of the arg. |
|
||||
| <div className="anchor-with-padding" id="cliarg.longdescription">`longDescription`<a class="hash-link" href="#cliarg.longdescription"></a></div> | string? | _null_ | The argument long description which will be shown on the help information. Typically this a more detailed (multi-line) message that describes the argument. |
|
||||
| <div className="anchor-with-padding" id="cliarg.takesvalue">`takesValue`<a class="hash-link" href="#cliarg.takesvalue"></a></div> | boolean | `false` | Specifies that the argument takes a value at run time.<br /><br />NOTE: values for arguments may be specified in any of the following methods<br />- Using a space such as -o value or --option value<br />- Using an equals and no space such as -o=value or --option=value<br />- Use a short and no space such as -ovalue |
|
||||
| <div className="anchor-with-padding" id="cliarg.multiple">`multiple`<a class="hash-link" href="#cliarg.multiple"></a></div> | boolean | `false` | Specifies that the argument may have an unknown number of multiple values. Without any other settings, this argument may appear only once.<br /><br />For example, --opt val1 val2 is allowed, but --opt val1 val2 --opt val3 is not.<br /><br />NOTE: Setting this requires `takes_value` to be set to true. |
|
||||
| <div className="anchor-with-padding" id="cliarg.multipleoccurrences">`multipleOccurrences`<a class="hash-link" href="#cliarg.multipleoccurrences"></a></div> | boolean | `false` | Specifies that the argument may appear more than once. For flags, this results in the number of occurrences of the flag being recorded. For example -ddd or -d -d -d would count as three occurrences. For options or arguments that take a value, this does not affect how many values they can accept. (i.e. only one at a time is allowed)<br /><br />For example, --opt val1 --opt val2 is allowed, but --opt val1 val2 is not. |
|
||||
| <div className="anchor-with-padding" id="cliarg.numberofvalues">`numberOfValues`<a class="hash-link" href="#cliarg.numberofvalues"></a></div> | integer? _(format: `uint`)_ | _null_ | Specifies how many values are required to satisfy this argument. For example, if you had a `-f <file>` argument where you wanted exactly 3 'files' you would set `number_of_values = 3`, and this argument wouldn't be satisfied unless the user provided 3 and only 3 values.<br /><br />**NOTE:** Does _not_ require `multiple_occurrences = true` to be set. Setting `multiple_occurrences = true` would allow `-f <file> <file> <file> -f <file> <file> <file>` where as _not_ setting it would only allow one occurrence of this argument.<br /><br />**NOTE:** implicitly sets `takes_value = true` and `multiple_values = true`. |
|
||||
| <div className="anchor-with-padding" id="cliarg.possiblevalues">`possibleValues`<a class="hash-link" href="#cliarg.possiblevalues"></a></div> | array? | _null_ | Specifies a list of possible values for this argument. At runtime, the CLI verifies that only one of the specified values was used, or fails with an error message. |
|
||||
| <div className="anchor-with-padding" id="cliarg.minvalues">`minValues`<a class="hash-link" href="#cliarg.minvalues"></a></div> | integer? _(format: `uint`)_ | _null_ | Specifies the minimum number of values for this argument. For example, if you had a -f `<file>` argument where you wanted at least 2 'files', you would set `minValues: 2`, and this argument would be satisfied if the user provided, 2 or more values. |
|
||||
| <div className="anchor-with-padding" id="cliarg.maxvalues">`maxValues`<a class="hash-link" href="#cliarg.maxvalues"></a></div> | integer? _(format: `uint`)_ | _null_ | Specifies the maximum number of values are for this argument. For example, if you had a -f `<file>` argument where you wanted up to 3 'files', you would set .max_values(3), and this argument would be satisfied if the user provided, 1, 2, or 3 values. |
|
||||
| <div className="anchor-with-padding" id="cliarg.required">`required`<a class="hash-link" href="#cliarg.required"></a></div> | boolean | `false` | Sets whether or not the argument is required by default.<br /><br />- Required by default means it is required, when no other conflicting rules have been evaluated<br />- Conflicting rules take precedence over being required. |
|
||||
| <div className="anchor-with-padding" id="cliarg.requiredunlesspresent">`requiredUnlessPresent`<a class="hash-link" href="#cliarg.requiredunlesspresent"></a></div> | string? | _null_ | Sets an arg that override this arg's required setting i.e. this arg will be required unless this other argument is present. |
|
||||
| <div className="anchor-with-padding" id="cliarg.requiredunlesspresentall">`requiredUnlessPresentAll`<a class="hash-link" href="#cliarg.requiredunlesspresentall"></a></div> | array? | _null_ | Sets args that override this arg's required setting i.e. this arg will be required unless all these other arguments are present. |
|
||||
| <div className="anchor-with-padding" id="cliarg.requiredunlesspresentany">`requiredUnlessPresentAny`<a class="hash-link" href="#cliarg.requiredunlesspresentany"></a></div> | array? | _null_ | Sets args that override this arg's required setting i.e. this arg will be required unless at least one of these other arguments are present. |
|
||||
| <div className="anchor-with-padding" id="cliarg.conflictswith">`conflictsWith`<a class="hash-link" href="#cliarg.conflictswith"></a></div> | string? | _null_ | Sets a conflicting argument by name i.e. when using this argument, the following argument can't be present and vice versa. |
|
||||
| <div className="anchor-with-padding" id="cliarg.conflictswithall">`conflictsWithAll`<a class="hash-link" href="#cliarg.conflictswithall"></a></div> | array? | _null_ | The same as conflictsWith but allows specifying multiple two-way conflicts per argument. |
|
||||
| <div className="anchor-with-padding" id="cliarg.requires">`requires`<a class="hash-link" href="#cliarg.requires"></a></div> | string? | _null_ | Tets an argument by name that is required when this one is present i.e. when using this argument, the following argument must be present. |
|
||||
| <div className="anchor-with-padding" id="cliarg.requiresall">`requiresAll`<a class="hash-link" href="#cliarg.requiresall"></a></div> | array? | _null_ | Sts multiple arguments by names that are required when this one is present i.e. when using this argument, the following arguments must be present. |
|
||||
| <div className="anchor-with-padding" id="cliarg.requiresif">`requiresIf`<a class="hash-link" href="#cliarg.requiresif"></a></div> | array? | _null_ | Allows a conditional requirement with the signature [arg, value] the requirement will only become valid if `arg`'s value equals `${value}`. |
|
||||
| <div className="anchor-with-padding" id="cliarg.requiredifeq">`requiredIfEq`<a class="hash-link" href="#cliarg.requiredifeq"></a></div> | array? | _null_ | Allows specifying that an argument is required conditionally with the signature [arg, value] the requirement will only become valid if the `arg`'s value equals `${value}`. |
|
||||
| <div className="anchor-with-padding" id="cliarg.requireequals">`requireEquals`<a class="hash-link" href="#cliarg.requireequals"></a></div> | boolean? | _null_ | Requires that options use the --option=val syntax i.e. an equals between the option and associated value. |
|
||||
| <div className="anchor-with-padding" id="cliarg.index">`index`<a class="hash-link" href="#cliarg.index"></a></div> | integer? _(format: `uint`, minimum: `1`)_ | _null_ | The positional argument index, starting at 1.<br /><br />The index refers to position according to other positional argument. It does not define position in the argument list as a whole. When utilized with multiple=true, only the last positional argument may be defined as multiple (i.e. the one with the highest index). |
|
||||
|
||||
#### BundleConfig
|
||||
|
||||
Configuration for tauri-bundler.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="bundleconfig.active">`active`<a class="hash-link" href="#bundleconfig.active"></a></div> | boolean | `false` | Whether Tauri should bundle your application or just output the executable. |
|
||||
| <div className="anchor-with-padding" id="bundleconfig.targets">`targets`<a class="hash-link" href="#bundleconfig.targets"></a></div> | [`BundleTarget`](#bundletarget) | [view](#bundletarget) | The bundle targets, currently supports ["deb", "appimage", "nsis", "msi", "app", "dmg", "updater"] or "all". |
|
||||
| <div className="anchor-with-padding" id="bundleconfig.identifier">`identifier`<a class="hash-link" href="#bundleconfig.identifier"></a></div> | string (required) | | The application identifier in reverse domain name notation (e.g. `com.tauri.example`). This string must be unique across applications since it is used in system configurations like the bundle ID and path to the webview data directory. This string must contain only alphanumeric characters (A–Z, a–z, and 0–9), hyphens (-), and periods (.). |
|
||||
| <div className="anchor-with-padding" id="bundleconfig.publisher">`publisher`<a class="hash-link" href="#bundleconfig.publisher"></a></div> | string? | _null_ | The application's publisher. Defaults to the second element in the identifier string. Currently maps to the Manufacturer property of the Windows Installer. |
|
||||
| <div className="anchor-with-padding" id="bundleconfig.icon">`icon`<a class="hash-link" href="#bundleconfig.icon"></a></div> | string[] | [] | The app's icons |
|
||||
| <div className="anchor-with-padding" id="bundleconfig.resources">`resources`<a class="hash-link" href="#bundleconfig.resources"></a></div> | array? | _null_ | App resources to bundle. Each resource is a path to a file or directory. Glob patterns are supported. |
|
||||
| <div className="anchor-with-padding" id="bundleconfig.copyright">`copyright`<a class="hash-link" href="#bundleconfig.copyright"></a></div> | string? | _null_ | A copyright string associated with your application. |
|
||||
| <div className="anchor-with-padding" id="bundleconfig.category">`category`<a class="hash-link" href="#bundleconfig.category"></a></div> | string? | _null_ | The application kind.<br /><br />Should be one of the following: Business, DeveloperTool, Education, Entertainment, Finance, Game, ActionGame, AdventureGame, ArcadeGame, BoardGame, CardGame, CasinoGame, DiceGame, EducationalGame, FamilyGame, KidsGame, MusicGame, PuzzleGame, RacingGame, RolePlayingGame, SimulationGame, SportsGame, StrategyGame, TriviaGame, WordGame, GraphicsAndDesign, HealthcareAndFitness, Lifestyle, Medical, Music, News, Photography, Productivity, Reference, SocialNetworking, Sports, Travel, Utility, Video, Weather. |
|
||||
| <div className="anchor-with-padding" id="bundleconfig.shortdescription">`shortDescription`<a class="hash-link" href="#bundleconfig.shortdescription"></a></div> | string? | _null_ | A short description of your application. |
|
||||
| <div className="anchor-with-padding" id="bundleconfig.longdescription">`longDescription`<a class="hash-link" href="#bundleconfig.longdescription"></a></div> | string? | _null_ | A longer, multi-line description of the application. |
|
||||
| <div className="anchor-with-padding" id="bundleconfig.appimage">`appimage`<a class="hash-link" href="#bundleconfig.appimage"></a></div> | [`AppImageConfig`](#appimageconfig) | [view](#appimageconfig) | Configuration for the AppImage bundle. |
|
||||
| <div className="anchor-with-padding" id="bundleconfig.deb">`deb`<a class="hash-link" href="#bundleconfig.deb"></a></div> | [`DebConfig`](#debconfig) | [view](#debconfig) | Configuration for the Debian bundle. |
|
||||
| <div className="anchor-with-padding" id="bundleconfig.macos">`macOS`<a class="hash-link" href="#bundleconfig.macos"></a></div> | [`MacConfig`](#macconfig) | [view](#macconfig) | Configuration for the macOS bundles. |
|
||||
| <div className="anchor-with-padding" id="bundleconfig.externalbin">`externalBin`<a class="hash-link" href="#bundleconfig.externalbin"></a></div> | array? | _null_ | A list of—either absolute or relative—paths to binaries to embed with your application.<br /><br />Note that Tauri will look for system-specific binaries following the pattern "binary-name{-target-triple}{.system-extension}".<br /><br />E.g. for the external binary "my-binary", Tauri looks for:<br /><br />- "my-binary-x86_64-pc-windows-msvc.exe" for Windows<br />- "my-binary-x86_64-apple-darwin" for macOS<br />- "my-binary-x86_64-unknown-linux-gnu" for Linux<br /><br />so don't forget to provide binaries for all targeted platforms. |
|
||||
| <div className="anchor-with-padding" id="bundleconfig.windows">`windows`<a class="hash-link" href="#bundleconfig.windows"></a></div> | [`WindowsConfig`](#windowsconfig) | [view](#windowsconfig) | Configuration for the Windows bundle. |
|
||||
|
||||
##### BundleTarget
|
||||
|
||||
Targets to bundle. Each value is case insensitive.
|
||||
|
||||
Can be any of the following types:
|
||||
|
||||
- `"all"`: Bundle all targets.
|
||||
- [`BundleType`](#bundletype): A list of bundle targets.
|
||||
- [`BundleType`](#bundletype): A single bundle target.
|
||||
|
||||
###### BundleType
|
||||
|
||||
A bundle referenced by tauri-bundler.
|
||||
|
||||
Can be any **ONE** of the following types:
|
||||
|
||||
- "deb": The debian bundle (.deb).
|
||||
- "appimage": The AppImage bundle (.appimage).
|
||||
- "msi": The Microsoft Installer bundle (.msi).
|
||||
- "nsis": The NSIS bundle (.exe).
|
||||
- "app": The macOS application bundle (.app).
|
||||
- "dmg": The Apple Disk Image bundle (.dmg).
|
||||
- "updater": The Tauri updater bundle.
|
||||
|
||||
##### AppImageConfig
|
||||
|
||||
Configuration for AppImage bundles.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="appimageconfig.bundlemediaframework">`bundleMediaFramework`<a class="hash-link" href="#appimageconfig.bundlemediaframework"></a></div> | boolean | `false` | Include additional gstreamer dependencies needed for audio and video playback. This increases the bundle size by ~15-35MB depending on your build system. |
|
||||
|
||||
##### DebConfig
|
||||
|
||||
Configuration for Debian (.deb) bundles.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="debconfig.depends">`depends`<a class="hash-link" href="#debconfig.depends"></a></div> | array? | _null_ | The list of deb dependencies your application relies on. |
|
||||
| <div className="anchor-with-padding" id="debconfig.files">`files`<a class="hash-link" href="#debconfig.files"></a></div> | object | _null_ | The files to include on the package. |
|
||||
| <div className="anchor-with-padding" id="debconfig.desktoptemplate">`desktopTemplate`<a class="hash-link" href="#debconfig.desktoptemplate"></a></div> | string? | _null_ | Path to a custom desktop file Handlebars template.<br /><br />Available variables: `categories`, `comment` (optional), `exec`, `icon` and `name`. |
|
||||
|
||||
##### MacConfig
|
||||
|
||||
Configuration for the macOS bundles.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="macconfig.frameworks">`frameworks`<a class="hash-link" href="#macconfig.frameworks"></a></div> | array? | _null_ | A list of strings indicating any macOS X frameworks that need to be bundled with the application.<br /><br />If a name is used, ".framework" must be omitted and it will look for standard install locations. You may also use a path to a specific framework. |
|
||||
| <div className="anchor-with-padding" id="macconfig.minimumsystemversion">`minimumSystemVersion`<a class="hash-link" href="#macconfig.minimumsystemversion"></a></div> | string? | _null_ | A version string indicating the minimum macOS X version that the bundled application supports. Defaults to `10.13`.<br /><br />Setting it to `null` completely removes the `LSMinimumSystemVersion` field on the bundle's `Info.plist` and the `MACOSX_DEPLOYMENT_TARGET` environment variable.<br /><br />An empty string is considered an invalid value so the default value is used. |
|
||||
| <div className="anchor-with-padding" id="macconfig.exceptiondomain">`exceptionDomain`<a class="hash-link" href="#macconfig.exceptiondomain"></a></div> | string? | _null_ | Allows your application to communicate with the outside world. It should be a lowercase, without port and protocol domain name. |
|
||||
| <div className="anchor-with-padding" id="macconfig.license">`license`<a class="hash-link" href="#macconfig.license"></a></div> | string? | _null_ | The path to the license file to add to the DMG bundle. |
|
||||
| <div className="anchor-with-padding" id="macconfig.signingidentity">`signingIdentity`<a class="hash-link" href="#macconfig.signingidentity"></a></div> | string? | _null_ | Identity to use for code signing. |
|
||||
| <div className="anchor-with-padding" id="macconfig.providershortname">`providerShortName`<a class="hash-link" href="#macconfig.providershortname"></a></div> | string? | _null_ | Provider short name for notarization. |
|
||||
| <div className="anchor-with-padding" id="macconfig.entitlements">`entitlements`<a class="hash-link" href="#macconfig.entitlements"></a></div> | string? | _null_ | Path to the entitlements file. |
|
||||
|
||||
##### WindowsConfig
|
||||
|
||||
Windows bundler configuration.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="windowsconfig.digestalgorithm">`digestAlgorithm`<a class="hash-link" href="#windowsconfig.digestalgorithm"></a></div> | string? | _null_ | Specifies the file digest algorithm to use for creating file signatures. Required for code signing. SHA-256 is recommended. |
|
||||
| <div className="anchor-with-padding" id="windowsconfig.certificatethumbprint">`certificateThumbprint`<a class="hash-link" href="#windowsconfig.certificatethumbprint"></a></div> | string? | _null_ | Specifies the SHA1 hash of the signing certificate. |
|
||||
| <div className="anchor-with-padding" id="windowsconfig.timestampurl">`timestampUrl`<a class="hash-link" href="#windowsconfig.timestampurl"></a></div> | string? | _null_ | Server to use during timestamping. |
|
||||
| <div className="anchor-with-padding" id="windowsconfig.tsp">`tsp`<a class="hash-link" href="#windowsconfig.tsp"></a></div> | boolean | `false` | Whether to use Time-Stamp Protocol (TSP, a.k.a. RFC 3161) for the timestamp server. Your code signing provider may use a TSP timestamp server, like e.g. SSL.com does. If so, enable TSP by setting to true. |
|
||||
| <div className="anchor-with-padding" id="windowsconfig.webviewinstallmode">`webviewInstallMode`<a class="hash-link" href="#windowsconfig.webviewinstallmode"></a></div> | [`WebviewInstallMode`](#webviewinstallmode) | [view](#webviewinstallmode) | The installation mode for the Webview2 runtime. |
|
||||
| <div className="anchor-with-padding" id="windowsconfig.webviewfixedruntimepath">`webviewFixedRuntimePath`<a class="hash-link" href="#windowsconfig.webviewfixedruntimepath"></a></div> | string? | _null_ | Path to the webview fixed runtime to use. Overwrites `webview_install_mode` if set.<br /><br />Will be removed in v2, prefer the `webview_install_mode` option.<br /><br />The fixed version can be downloaded [on the official website](https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download-section). The `.cab` file must be extracted to a folder and this folder path must be defined on this field. |
|
||||
| <div className="anchor-with-padding" id="windowsconfig.allowdowngrades">`allowDowngrades`<a class="hash-link" href="#windowsconfig.allowdowngrades"></a></div> | boolean | `true` | Validates a second app installation, blocking the user from installing an older version if set to `false`.<br /><br />For instance, if `1.2.1` is installed, the user won't be able to install app version `1.2.0` or `1.1.5`.<br /><br />The default value of this flag is `true`. |
|
||||
| <div className="anchor-with-padding" id="windowsconfig.wix">`wix`<a class="hash-link" href="#windowsconfig.wix"></a></div> | [`WixConfig`](#wixconfig)? | [view](#wixconfig) | Configuration for the MSI generated with WiX. |
|
||||
| <div className="anchor-with-padding" id="windowsconfig.nsis">`nsis`<a class="hash-link" href="#windowsconfig.nsis"></a></div> | [`NsisConfig`](#nsisconfig)? | [view](#nsisconfig) | Configuration for the installer generated with NSIS. |
|
||||
|
||||
###### WebviewInstallMode
|
||||
|
||||
Install modes for the Webview2 runtime. Note that for the updater bundle `DownloadBootstrapper` is used.
|
||||
|
||||
For more information see <https://tauri.app/v1/guides/building/windows>.
|
||||
|
||||
Can be any **ONE** of the following types:
|
||||
|
||||
- `{ "type": "skip" }`: Do not install the Webview2 as part of the Windows Installer.
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------- | ----------- |
|
||||
| <div className="anchor-with-padding" id="webviewinstallmode.type">`type`<a class="hash-link" href="#webviewinstallmode.type"></a></div> | "skip" (required) | | undefined |
|
||||
|
||||
- `{ "type": "downloadBootstrapper", "silent": boolean }`: Download the bootstrapper and run it. Requires an internet connection. Results in a smaller installer size, but is not recommended on Windows 7.
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------- | ----------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="webviewinstallmode.type">`type`<a class="hash-link" href="#webviewinstallmode.type"></a></div> | "downloadBootstrapper" (required) | | undefined |
|
||||
| <div className="anchor-with-padding" id="webviewinstallmode.silent">`silent`<a class="hash-link" href="#webviewinstallmode.silent"></a></div> | boolean | `true` | Instructs the installer to run the bootstrapper in silent mode. Defaults to `true`. |
|
||||
|
||||
- `{ "type": "embedBootstrapper", "silent": boolean }`: Embed the bootstrapper and run it. Requires an internet connection. Increases the installer size by around 1.8MB, but offers better support on Windows 7.
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ------- | ----------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="webviewinstallmode.type">`type`<a class="hash-link" href="#webviewinstallmode.type"></a></div> | "embedBootstrapper" (required) | | undefined |
|
||||
| <div className="anchor-with-padding" id="webviewinstallmode.silent">`silent`<a class="hash-link" href="#webviewinstallmode.silent"></a></div> | boolean | `true` | Instructs the installer to run the bootstrapper in silent mode. Defaults to `true`. |
|
||||
|
||||
- `{ "type": "offlineInstaller", "silent": boolean }`: Embed the offline installer and run it. Does not require an internet connection. Increases the installer size by around 127MB.
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ------- | -------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="webviewinstallmode.type">`type`<a class="hash-link" href="#webviewinstallmode.type"></a></div> | "offlineInstaller" (required) | | undefined |
|
||||
| <div className="anchor-with-padding" id="webviewinstallmode.silent">`silent`<a class="hash-link" href="#webviewinstallmode.silent"></a></div> | boolean | `true` | Instructs the installer to run the installer in silent mode. Defaults to `true`. |
|
||||
|
||||
- `{ "type": "fixedRuntime", "path": string }`: Embed a fixed webview2 version and use it at runtime. Increases the installer size by around 180MB.
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="webviewinstallmode.type">`type`<a class="hash-link" href="#webviewinstallmode.type"></a></div> | "fixedRuntime" (required) | | undefined |
|
||||
| <div className="anchor-with-padding" id="webviewinstallmode.path">`path`<a class="hash-link" href="#webviewinstallmode.path"></a></div> | string (required) | | The path to the fixed runtime to use.<br /><br />The fixed version can be downloaded [on the official website](https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download-section). The `.cab` file must be extracted to a folder and this folder path must be defined on this field. |
|
||||
|
||||
###### WixConfig
|
||||
|
||||
Configuration for the MSI bundle using WiX.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="wixconfig.language">`language`<a class="hash-link" href="#wixconfig.language"></a></div> | [`WixLanguage`](#wixlanguage) | [view](#wixlanguage) | The installer languages to build. See <https://docs.microsoft.com/en-us/windows/win32/msi/localizing-the-error-and-actiontext-tables>. |
|
||||
| <div className="anchor-with-padding" id="wixconfig.template">`template`<a class="hash-link" href="#wixconfig.template"></a></div> | string? | _null_ | A custom .wxs template to use. |
|
||||
| <div className="anchor-with-padding" id="wixconfig.fragmentpaths">`fragmentPaths`<a class="hash-link" href="#wixconfig.fragmentpaths"></a></div> | string[] | [] | A list of paths to .wxs files with WiX fragments to use. |
|
||||
| <div className="anchor-with-padding" id="wixconfig.componentgrouprefs">`componentGroupRefs`<a class="hash-link" href="#wixconfig.componentgrouprefs"></a></div> | string[] | [] | The ComponentGroup element ids you want to reference from the fragments. |
|
||||
| <div className="anchor-with-padding" id="wixconfig.componentrefs">`componentRefs`<a class="hash-link" href="#wixconfig.componentrefs"></a></div> | string[] | [] | The Component element ids you want to reference from the fragments. |
|
||||
| <div className="anchor-with-padding" id="wixconfig.featuregrouprefs">`featureGroupRefs`<a class="hash-link" href="#wixconfig.featuregrouprefs"></a></div> | string[] | [] | The FeatureGroup element ids you want to reference from the fragments. |
|
||||
| <div className="anchor-with-padding" id="wixconfig.featurerefs">`featureRefs`<a class="hash-link" href="#wixconfig.featurerefs"></a></div> | string[] | [] | The Feature element ids you want to reference from the fragments. |
|
||||
| <div className="anchor-with-padding" id="wixconfig.mergerefs">`mergeRefs`<a class="hash-link" href="#wixconfig.mergerefs"></a></div> | string[] | [] | The Merge element ids you want to reference from the fragments. |
|
||||
| <div className="anchor-with-padding" id="wixconfig.skipwebviewinstall">`skipWebviewInstall`<a class="hash-link" href="#wixconfig.skipwebviewinstall"></a></div> | boolean | `false` | Disables the Webview2 runtime installation after app install.<br /><br />Will be removed in v2, prefer the [`WindowsConfig::webview_install_mode`] option. |
|
||||
| <div className="anchor-with-padding" id="wixconfig.license">`license`<a class="hash-link" href="#wixconfig.license"></a></div> | string? | _null_ | The path to the license file to render on the installer.<br /><br />Must be an RTF file, so if a different extension is provided, we convert it to the RTF format. |
|
||||
| <div className="anchor-with-padding" id="wixconfig.enableelevatedupdatetask">`enableElevatedUpdateTask`<a class="hash-link" href="#wixconfig.enableelevatedupdatetask"></a></div> | boolean | `false` | Create an elevated update task within Windows Task Scheduler. |
|
||||
| <div className="anchor-with-padding" id="wixconfig.bannerpath">`bannerPath`<a class="hash-link" href="#wixconfig.bannerpath"></a></div> | string? | _null_ | Path to a bitmap file to use as the installation user interface banner. This bitmap will appear at the top of all but the first page of the installer.<br /><br />The required dimensions are 493px × 58px. |
|
||||
| <div className="anchor-with-padding" id="wixconfig.dialogimagepath">`dialogImagePath`<a class="hash-link" href="#wixconfig.dialogimagepath"></a></div> | string? | _null_ | Path to a bitmap file to use on the installation user interface dialogs. It is used on the welcome and completion dialogs. The required dimensions are 493px × 312px. |
|
||||
|
||||
###### WixLanguage
|
||||
|
||||
The languages to build using WiX.
|
||||
|
||||
Can be any of the following types:
|
||||
|
||||
- `string`: A single language to build, without configuration.
|
||||
- `string[]`: A list of languages to build, without configuration.
|
||||
- [`WixLanguageConfig`](#wixlanguageconfig): A map of languages and its configuration.
|
||||
|
||||
###### WixLanguageConfig
|
||||
|
||||
Configuration for a target language for the WiX build.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="wixlanguageconfig.localepath">`localePath`<a class="hash-link" href="#wixlanguageconfig.localepath"></a></div> | string? | _null_ | The path to a locale (`.wxl`) file. See <https://wixtoolset.org/documentation/manual/v3/howtos/ui_and_localization/build_a_localized_version.html>. |
|
||||
|
||||
###### NsisConfig
|
||||
|
||||
Configuration for the Installer bundle using NSIS.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="nsisconfig.template">`template`<a class="hash-link" href="#nsisconfig.template"></a></div> | string? | _null_ | A custom .nsi template to use. |
|
||||
| <div className="anchor-with-padding" id="nsisconfig.license">`license`<a class="hash-link" href="#nsisconfig.license"></a></div> | string? | _null_ | The path to the license file to render on the installer. |
|
||||
| <div className="anchor-with-padding" id="nsisconfig.headerimage">`headerImage`<a class="hash-link" href="#nsisconfig.headerimage"></a></div> | string? | _null_ | The path to a bitmap file to display on the header of installers pages.<br /><br />The recommended dimensions are 150px x 57px. |
|
||||
| <div className="anchor-with-padding" id="nsisconfig.sidebarimage">`sidebarImage`<a class="hash-link" href="#nsisconfig.sidebarimage"></a></div> | string? | _null_ | The path to a bitmap file for the Welcome page and the Finish page.<br /><br />The recommended dimensions are 164px x 314px. |
|
||||
| <div className="anchor-with-padding" id="nsisconfig.installericon">`installerIcon`<a class="hash-link" href="#nsisconfig.installericon"></a></div> | string? | _null_ | The path to an icon file used as the installer icon. |
|
||||
| <div className="anchor-with-padding" id="nsisconfig.installmode">`installMode`<a class="hash-link" href="#nsisconfig.installmode"></a></div> | [`NSISInstallerMode`](#nsisinstallermode) | [view](#nsisinstallermode) | Whether the installation will be for all users or just the current user. |
|
||||
| <div className="anchor-with-padding" id="nsisconfig.languages">`languages`<a class="hash-link" href="#nsisconfig.languages"></a></div> | array? | _null_ | A list of installer languages. By default the OS language is used. If the OS language is not in the list of languages, the first language will be used. To allow the user to select the language, set `display_language_selector` to `true`.<br /><br />See <https://github.com/kichik/nsis/tree/9465c08046f00ccb6eda985abbdbf52c275c6c4d/Contrib/Language%20files> for the complete list of languages. |
|
||||
| <div className="anchor-with-padding" id="nsisconfig.customlanguagefiles">`customLanguageFiles`<a class="hash-link" href="#nsisconfig.customlanguagefiles"></a></div> | object? | _null_ | A key-value pair where the key is the language and the value is the path to a custom `.nsh` file that holds the translated text for tauri's custom messages.<br /><br />See <https://github.com/tauri-apps/tauri/blob/dev/tooling/bundler/src/bundle/windows/templates/nsis-languages/English.nsh> for an example `.nsh` file.<br /><br />**Note**: the key must be a valid NSIS language and it must be added to [`NsisConfig`] languages array, |
|
||||
| <div className="anchor-with-padding" id="nsisconfig.displaylanguageselector">`displayLanguageSelector`<a class="hash-link" href="#nsisconfig.displaylanguageselector"></a></div> | boolean | `false` | Whether to display a language selector dialog before the installer and uninstaller windows are rendered or not. By default the OS language is selected, with a fallback to the first language in the `languages` array. |
|
||||
|
||||
###### NSISInstallerMode
|
||||
|
||||
Install Modes for the NSIS installer.
|
||||
|
||||
Can be any **ONE** of the following types:
|
||||
|
||||
- "currentUser": Default mode for the installer.
|
||||
|
||||
Install the app by default in a directory that doesn't require Administrator access.
|
||||
|
||||
Installer metadata will be saved under the `HKCU` registry path.
|
||||
|
||||
- "perMachine": Install the app by default in the `Program Files` folder directory requires Administrator access for the installation.
|
||||
|
||||
Installer metadata will be saved under the `HKLM` registry path.
|
||||
|
||||
- "both": Combines both modes and allows the user to choose at install time whether to install for the current user or per machine. Note that this mode will require Administrator access even if the user wants to install it for the current user only.
|
||||
|
||||
Installer metadata will be saved under the `HKLM` or `HKCU` registry path based on the user's choice.
|
||||
|
||||
#### AllowlistConfig
|
||||
|
||||
Allowlist configuration. The allowlist is a translation of the [Cargo allowlist features](https://docs.rs/tauri/latest/tauri/#cargo-allowlist-features).
|
||||
|
||||
# Notes
|
||||
|
||||
- Endpoints that don't have their own allowlist option are enabled by default.
|
||||
- There is only "opt-in", no "opt-out". Setting an option to `false` has no effect.
|
||||
|
||||
# Examples
|
||||
|
||||
- - [`"app-all": true`](https://tauri.app/v1/api/config/#appallowlistconfig.all) will make the [hide](https://tauri.app/v1/api/js/app#hide) endpoint be available regardless of whether `hide` is set to `false` or `true` in the allowlist.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------- | ----------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="allowlistconfig.all">`all`<a class="hash-link" href="#allowlistconfig.all"></a></div> | boolean | `false` | Use this flag to enable all API features. |
|
||||
| <div className="anchor-with-padding" id="allowlistconfig.fs">`fs`<a class="hash-link" href="#allowlistconfig.fs"></a></div> | [`FsAllowlistConfig`](#fsallowlistconfig) | [view](#fsallowlistconfig) | File system API allowlist. |
|
||||
| <div className="anchor-with-padding" id="allowlistconfig.window">`window`<a class="hash-link" href="#allowlistconfig.window"></a></div> | [`WindowAllowlistConfig`](#windowallowlistconfig) | [view](#windowallowlistconfig) | Window API allowlist. |
|
||||
| <div className="anchor-with-padding" id="allowlistconfig.shell">`shell`<a class="hash-link" href="#allowlistconfig.shell"></a></div> | [`ShellAllowlistConfig`](#shellallowlistconfig) | [view](#shellallowlistconfig) | Shell API allowlist. |
|
||||
| <div className="anchor-with-padding" id="allowlistconfig.dialog">`dialog`<a class="hash-link" href="#allowlistconfig.dialog"></a></div> | [`DialogAllowlistConfig`](#dialogallowlistconfig) | [view](#dialogallowlistconfig) | Dialog API allowlist. |
|
||||
| <div className="anchor-with-padding" id="allowlistconfig.http">`http`<a class="hash-link" href="#allowlistconfig.http"></a></div> | [`HttpAllowlistConfig`](#httpallowlistconfig) | [view](#httpallowlistconfig) | HTTP API allowlist. |
|
||||
| <div className="anchor-with-padding" id="allowlistconfig.notification">`notification`<a class="hash-link" href="#allowlistconfig.notification"></a></div> | [`NotificationAllowlistConfig`](#notificationallowlistconfig) | [view](#notificationallowlistconfig) | Notification API allowlist. |
|
||||
| <div className="anchor-with-padding" id="allowlistconfig.globalshortcut">`globalShortcut`<a class="hash-link" href="#allowlistconfig.globalshortcut"></a></div> | [`GlobalShortcutAllowlistConfig`](#globalshortcutallowlistconfig) | [view](#globalshortcutallowlistconfig) | Global shortcut API allowlist. |
|
||||
| <div className="anchor-with-padding" id="allowlistconfig.os">`os`<a class="hash-link" href="#allowlistconfig.os"></a></div> | [`OsAllowlistConfig`](#osallowlistconfig) | [view](#osallowlistconfig) | OS allowlist. |
|
||||
| <div className="anchor-with-padding" id="allowlistconfig.path">`path`<a class="hash-link" href="#allowlistconfig.path"></a></div> | [`PathAllowlistConfig`](#pathallowlistconfig) | [view](#pathallowlistconfig) | Path API allowlist. |
|
||||
| <div className="anchor-with-padding" id="allowlistconfig.protocol">`protocol`<a class="hash-link" href="#allowlistconfig.protocol"></a></div> | [`ProtocolAllowlistConfig`](#protocolallowlistconfig) | [view](#protocolallowlistconfig) | Custom protocol allowlist. |
|
||||
| <div className="anchor-with-padding" id="allowlistconfig.process">`process`<a class="hash-link" href="#allowlistconfig.process"></a></div> | [`ProcessAllowlistConfig`](#processallowlistconfig) | [view](#processallowlistconfig) | Process API allowlist. |
|
||||
| <div className="anchor-with-padding" id="allowlistconfig.clipboard">`clipboard`<a class="hash-link" href="#allowlistconfig.clipboard"></a></div> | [`ClipboardAllowlistConfig`](#clipboardallowlistconfig) | [view](#clipboardallowlistconfig) | Clipboard APIs allowlist. |
|
||||
| <div className="anchor-with-padding" id="allowlistconfig.app">`app`<a class="hash-link" href="#allowlistconfig.app"></a></div> | [`AppAllowlistConfig`](#appallowlistconfig) | [view](#appallowlistconfig) | App APIs allowlist. |
|
||||
|
||||
##### FsAllowlistConfig
|
||||
|
||||
Allowlist for the file system APIs.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------- | ----------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="fsallowlistconfig.scope">`scope`<a class="hash-link" href="#fsallowlistconfig.scope"></a></div> | [`FsAllowlistScope`](#fsallowlistscope) | [] | The access scope for the filesystem APIs. |
|
||||
| <div className="anchor-with-padding" id="fsallowlistconfig.all">`all`<a class="hash-link" href="#fsallowlistconfig.all"></a></div> | boolean | `false` | Use this flag to enable all file system API features. |
|
||||
| <div className="anchor-with-padding" id="fsallowlistconfig.readfile">`readFile`<a class="hash-link" href="#fsallowlistconfig.readfile"></a></div> | boolean | `false` | Read file from local filesystem. |
|
||||
| <div className="anchor-with-padding" id="fsallowlistconfig.writefile">`writeFile`<a class="hash-link" href="#fsallowlistconfig.writefile"></a></div> | boolean | `false` | Write file to local filesystem. |
|
||||
| <div className="anchor-with-padding" id="fsallowlistconfig.readdir">`readDir`<a class="hash-link" href="#fsallowlistconfig.readdir"></a></div> | boolean | `false` | Read directory from local filesystem. |
|
||||
| <div className="anchor-with-padding" id="fsallowlistconfig.copyfile">`copyFile`<a class="hash-link" href="#fsallowlistconfig.copyfile"></a></div> | boolean | `false` | Copy file from local filesystem. |
|
||||
| <div className="anchor-with-padding" id="fsallowlistconfig.createdir">`createDir`<a class="hash-link" href="#fsallowlistconfig.createdir"></a></div> | boolean | `false` | Create directory from local filesystem. |
|
||||
| <div className="anchor-with-padding" id="fsallowlistconfig.removedir">`removeDir`<a class="hash-link" href="#fsallowlistconfig.removedir"></a></div> | boolean | `false` | Remove directory from local filesystem. |
|
||||
| <div className="anchor-with-padding" id="fsallowlistconfig.removefile">`removeFile`<a class="hash-link" href="#fsallowlistconfig.removefile"></a></div> | boolean | `false` | Remove file from local filesystem. |
|
||||
| <div className="anchor-with-padding" id="fsallowlistconfig.renamefile">`renameFile`<a class="hash-link" href="#fsallowlistconfig.renamefile"></a></div> | boolean | `false` | Rename file from local filesystem. |
|
||||
| <div className="anchor-with-padding" id="fsallowlistconfig.exists">`exists`<a class="hash-link" href="#fsallowlistconfig.exists"></a></div> | boolean | `false` | Check if path exists on the local filesystem. |
|
||||
|
||||
###### FsAllowlistScope
|
||||
|
||||
Filesystem scope definition. It is a list of glob patterns that restrict the API access from the webview.
|
||||
|
||||
Each pattern can start with a variable that resolves to a system base directory. The variables are: `$AUDIO`, `$CACHE`, `$CONFIG`, `$DATA`, `$LOCALDATA`, `$DESKTOP`, `$DOCUMENT`, `$DOWNLOAD`, `$EXE`, `$FONT`, `$HOME`, `$PICTURE`, `$PUBLIC`, `$RUNTIME`, `$TEMPLATE`, `$VIDEO`, `$RESOURCE`, `$APP`, `$LOG`, `$TEMP`, `$APPCONFIG`, `$APPDATA`, `$APPLOCALDATA`, `$APPCACHE`, `$APPLOG`.
|
||||
|
||||
Can be any of the following types:
|
||||
|
||||
- `string[]`: A list of paths that are allowed by this scope.
|
||||
- `{ "allow": string[], "deny": string[], "requireLiteralLeadingDot": boolean? }`: A complete scope configuration.
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="fsallowlistscope.allow">`allow`<a class="hash-link" href="#fsallowlistscope.allow"></a></div> | string[] | [] | A list of paths that are allowed by this scope. |
|
||||
| <div className="anchor-with-padding" id="fsallowlistscope.deny">`deny`<a class="hash-link" href="#fsallowlistscope.deny"></a></div> | string[] | [] | A list of paths that are not allowed by this scope. This gets precedence over the `Scope::allow` list. |
|
||||
| <div className="anchor-with-padding" id="fsallowlistscope.requireliteralleadingdot">`requireLiteralLeadingDot`<a class="hash-link" href="#fsallowlistscope.requireliteralleadingdot"></a></div> | boolean? | _null_ | Whether or not paths that contain components that start with a `.` will require that `.` appears literally in the pattern; `*`, `?`, `**`, or `[...]` will not match. This is useful because such files are conventionally considered hidden on Unix systems and it might be desirable to skip them when listing files.<br /><br />Defaults to `true` on Unix systems and `false` on Windows |
|
||||
|
||||
##### WindowAllowlistConfig
|
||||
|
||||
Allowlist for the window APIs.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ------- | ----------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.all">`all`<a class="hash-link" href="#windowallowlistconfig.all"></a></div> | boolean | `false` | Use this flag to enable all window API features. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.create">`create`<a class="hash-link" href="#windowallowlistconfig.create"></a></div> | boolean | `false` | Allows dynamic window creation. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.center">`center`<a class="hash-link" href="#windowallowlistconfig.center"></a></div> | boolean | `false` | Allows centering the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.requestuserattention">`requestUserAttention`<a class="hash-link" href="#windowallowlistconfig.requestuserattention"></a></div> | boolean | `false` | Allows requesting user attention on the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setresizable">`setResizable`<a class="hash-link" href="#windowallowlistconfig.setresizable"></a></div> | boolean | `false` | Allows setting the resizable flag of the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setmaximizable">`setMaximizable`<a class="hash-link" href="#windowallowlistconfig.setmaximizable"></a></div> | boolean | `false` | Allows setting whether the window's native maximize button is enabled or not. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setminimizable">`setMinimizable`<a class="hash-link" href="#windowallowlistconfig.setminimizable"></a></div> | boolean | `false` | Allows setting whether the window's native minimize button is enabled or not. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setclosable">`setClosable`<a class="hash-link" href="#windowallowlistconfig.setclosable"></a></div> | boolean | `false` | Allows setting whether the window's native close button is enabled or not. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.settitle">`setTitle`<a class="hash-link" href="#windowallowlistconfig.settitle"></a></div> | boolean | `false` | Allows changing the window title. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.maximize">`maximize`<a class="hash-link" href="#windowallowlistconfig.maximize"></a></div> | boolean | `false` | Allows maximizing the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.unmaximize">`unmaximize`<a class="hash-link" href="#windowallowlistconfig.unmaximize"></a></div> | boolean | `false` | Allows unmaximizing the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.minimize">`minimize`<a class="hash-link" href="#windowallowlistconfig.minimize"></a></div> | boolean | `false` | Allows minimizing the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.unminimize">`unminimize`<a class="hash-link" href="#windowallowlistconfig.unminimize"></a></div> | boolean | `false` | Allows unminimizing the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.show">`show`<a class="hash-link" href="#windowallowlistconfig.show"></a></div> | boolean | `false` | Allows showing the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.hide">`hide`<a class="hash-link" href="#windowallowlistconfig.hide"></a></div> | boolean | `false` | Allows hiding the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.close">`close`<a class="hash-link" href="#windowallowlistconfig.close"></a></div> | boolean | `false` | Allows closing the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setdecorations">`setDecorations`<a class="hash-link" href="#windowallowlistconfig.setdecorations"></a></div> | boolean | `false` | Allows setting the decorations flag of the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setalwaysontop">`setAlwaysOnTop`<a class="hash-link" href="#windowallowlistconfig.setalwaysontop"></a></div> | boolean | `false` | Allows setting the always_on_top flag of the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setcontentprotected">`setContentProtected`<a class="hash-link" href="#windowallowlistconfig.setcontentprotected"></a></div> | boolean | `false` | Allows preventing the window contents from being captured by other apps. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setsize">`setSize`<a class="hash-link" href="#windowallowlistconfig.setsize"></a></div> | boolean | `false` | Allows setting the window size. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setminsize">`setMinSize`<a class="hash-link" href="#windowallowlistconfig.setminsize"></a></div> | boolean | `false` | Allows setting the window minimum size. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setmaxsize">`setMaxSize`<a class="hash-link" href="#windowallowlistconfig.setmaxsize"></a></div> | boolean | `false` | Allows setting the window maximum size. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setposition">`setPosition`<a class="hash-link" href="#windowallowlistconfig.setposition"></a></div> | boolean | `false` | Allows changing the position of the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setfullscreen">`setFullscreen`<a class="hash-link" href="#windowallowlistconfig.setfullscreen"></a></div> | boolean | `false` | Allows setting the fullscreen flag of the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setfocus">`setFocus`<a class="hash-link" href="#windowallowlistconfig.setfocus"></a></div> | boolean | `false` | Allows focusing the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.seticon">`setIcon`<a class="hash-link" href="#windowallowlistconfig.seticon"></a></div> | boolean | `false` | Allows changing the window icon. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setskiptaskbar">`setSkipTaskbar`<a class="hash-link" href="#windowallowlistconfig.setskiptaskbar"></a></div> | boolean | `false` | Allows setting the skip_taskbar flag of the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setcursorgrab">`setCursorGrab`<a class="hash-link" href="#windowallowlistconfig.setcursorgrab"></a></div> | boolean | `false` | Allows grabbing the cursor. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setcursorvisible">`setCursorVisible`<a class="hash-link" href="#windowallowlistconfig.setcursorvisible"></a></div> | boolean | `false` | Allows setting the cursor visibility. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setcursoricon">`setCursorIcon`<a class="hash-link" href="#windowallowlistconfig.setcursoricon"></a></div> | boolean | `false` | Allows changing the cursor icon. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setcursorposition">`setCursorPosition`<a class="hash-link" href="#windowallowlistconfig.setcursorposition"></a></div> | boolean | `false` | Allows setting the cursor position. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.setignorecursorevents">`setIgnoreCursorEvents`<a class="hash-link" href="#windowallowlistconfig.setignorecursorevents"></a></div> | boolean | `false` | Allows ignoring cursor events. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.startdragging">`startDragging`<a class="hash-link" href="#windowallowlistconfig.startdragging"></a></div> | boolean | `false` | Allows start dragging on the window. |
|
||||
| <div className="anchor-with-padding" id="windowallowlistconfig.print">`print`<a class="hash-link" href="#windowallowlistconfig.print"></a></div> | boolean | `false` | Allows opening the system dialog to print the window content. |
|
||||
|
||||
##### ShellAllowlistConfig
|
||||
|
||||
Allowlist for the shell APIs.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="shellallowlistconfig.scope">`scope`<a class="hash-link" href="#shellallowlistconfig.scope"></a></div> | [`ShellAllowlistScope`](#shellallowlistscope) | [] | Access scope for the binary execution APIs. Sidecars are automatically enabled. |
|
||||
| <div className="anchor-with-padding" id="shellallowlistconfig.all">`all`<a class="hash-link" href="#shellallowlistconfig.all"></a></div> | boolean | `false` | Use this flag to enable all shell API features. |
|
||||
| <div className="anchor-with-padding" id="shellallowlistconfig.execute">`execute`<a class="hash-link" href="#shellallowlistconfig.execute"></a></div> | boolean | `false` | Enable binary execution. |
|
||||
| <div className="anchor-with-padding" id="shellallowlistconfig.sidecar">`sidecar`<a class="hash-link" href="#shellallowlistconfig.sidecar"></a></div> | boolean | `false` | Enable sidecar execution, allowing the JavaScript layer to spawn a sidecar command, an executable that is shipped with the application. For more information see <https://tauri.app/v1/guides/building/sidecar>. |
|
||||
| <div className="anchor-with-padding" id="shellallowlistconfig.open">`open`<a class="hash-link" href="#shellallowlistconfig.open"></a></div> | [`ShellAllowlistOpen`](#shellallowlistopen) | `false` | Open URL with the user's default application. |
|
||||
|
||||
###### ShellAllowlistScope
|
||||
|
||||
Shell scope definition. It is a list of command names and associated CLI arguments that restrict the API access from the webview.
|
||||
|
||||
Type: [`ShellAllowedCommand`](#shellallowedcommand)
|
||||
|
||||
###### ShellAllowedCommand
|
||||
|
||||
A command allowed to be executed by the webview API.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="shellallowedcommand.name">`name`<a class="hash-link" href="#shellallowedcommand.name"></a></div> | string (required) | | The name for this allowed shell command configuration.<br /><br />This name will be used inside of the webview API to call this command along with any specified arguments. |
|
||||
| <div className="anchor-with-padding" id="shellallowedcommand.cmd">`cmd`<a class="hash-link" href="#shellallowedcommand.cmd"></a></div> | string | _null_ | The command name. It can start with a variable that resolves to a system base directory. The variables are: `$AUDIO`, `$CACHE`, `$CONFIG`, `$DATA`, `$LOCALDATA`, `$DESKTOP`, `$DOCUMENT`, `$DOWNLOAD`, `$EXE`, `$FONT`, `$HOME`, `$PICTURE`, `$PUBLIC`, `$RUNTIME`, `$TEMPLATE`, `$VIDEO`, `$RESOURCE`, `$APP`, `$LOG`, `$TEMP`, `$APPCONFIG`, `$APPDATA`, `$APPLOCALDATA`, `$APPCACHE`, `$APPLOG`. |
|
||||
| <div className="anchor-with-padding" id="shellallowedcommand.args">`args`<a class="hash-link" href="#shellallowedcommand.args"></a></div> | [`ShellAllowedArgs`](#shellallowedargs) | `false` | The allowed arguments for the command execution. |
|
||||
| <div className="anchor-with-padding" id="shellallowedcommand.sidecar">`sidecar`<a class="hash-link" href="#shellallowedcommand.sidecar"></a></div> | boolean | `false` | If this command is a sidecar command. |
|
||||
|
||||
###### ShellAllowedArgs
|
||||
|
||||
A set of command arguments allowed to be executed by the webview API.
|
||||
|
||||
A value of `true` will allow any arguments to be passed to the command. `false` will disable all arguments. A list of [`ShellAllowedArg`] will set those arguments as the only valid arguments to be passed to the attached command configuration.
|
||||
|
||||
Can be any of the following types:
|
||||
|
||||
- `boolean`: Use a simple boolean to allow all or disable all arguments to this command configuration.
|
||||
- [`ShellAllowedArg`](#shellallowedarg): A specific set of [`ShellAllowedArg`] that are valid to call for the command configuration.
|
||||
|
||||
###### ShellAllowedArg
|
||||
|
||||
A command argument allowed to be executed by the webview API.
|
||||
|
||||
Can be any of the following types:
|
||||
|
||||
- `string`: A non-configurable argument that is passed to the command in the order it was specified.
|
||||
- `{ "validator": string }`: A variable that is set while calling the command from the webview API.
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="shellallowedarg.validator">`validator`<a class="hash-link" href="#shellallowedarg.validator"></a></div> | string (required) | | [regex](https://docs.rs/regex/latest/regex/#syntax) validator to require passed values to conform to an expected input.<br /><br />This will require the argument value passed to this variable to match the `validator` regex before it will be executed. |
|
||||
|
||||
###### ShellAllowlistOpen
|
||||
|
||||
Defines the `shell > open` api scope.
|
||||
|
||||
Can be any of the following types:
|
||||
|
||||
- `boolean`: If the shell open API should be enabled.
|
||||
|
||||
If enabled, the default validation regex (`^((mailto:\w+)|(tel:\w+)|(https?://\w+)).+`) is used.
|
||||
|
||||
- `string`: Enable the shell open API, with a custom regex that the opened path must match against.
|
||||
|
||||
If using a custom regex to support a non-http(s) schema, care should be used to prevent values that allow flag-like strings to pass validation. e.g. `--enable-debugging`, `-i`, `/R`.
|
||||
|
||||
##### DialogAllowlistConfig
|
||||
|
||||
Allowlist for the dialog APIs.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ------- | ------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="dialogallowlistconfig.all">`all`<a class="hash-link" href="#dialogallowlistconfig.all"></a></div> | boolean | `false` | Use this flag to enable all dialog API features. |
|
||||
| <div className="anchor-with-padding" id="dialogallowlistconfig.open">`open`<a class="hash-link" href="#dialogallowlistconfig.open"></a></div> | boolean | `false` | Allows the API to open a dialog window to pick files. |
|
||||
| <div className="anchor-with-padding" id="dialogallowlistconfig.save">`save`<a class="hash-link" href="#dialogallowlistconfig.save"></a></div> | boolean | `false` | Allows the API to open a dialog window to pick where to save files. |
|
||||
| <div className="anchor-with-padding" id="dialogallowlistconfig.message">`message`<a class="hash-link" href="#dialogallowlistconfig.message"></a></div> | boolean | `false` | Allows the API to show a message dialog window. |
|
||||
| <div className="anchor-with-padding" id="dialogallowlistconfig.ask">`ask`<a class="hash-link" href="#dialogallowlistconfig.ask"></a></div> | boolean | `false` | Allows the API to show a dialog window with Yes/No buttons. |
|
||||
| <div className="anchor-with-padding" id="dialogallowlistconfig.confirm">`confirm`<a class="hash-link" href="#dialogallowlistconfig.confirm"></a></div> | boolean | `false` | Allows the API to show a dialog window with Ok/Cancel buttons. |
|
||||
|
||||
##### HttpAllowlistConfig
|
||||
|
||||
Allowlist for the HTTP APIs.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------- | ---------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="httpallowlistconfig.scope">`scope`<a class="hash-link" href="#httpallowlistconfig.scope"></a></div> | [`HttpAllowlistScope`](#httpallowlistscope) | [] | The access scope for the HTTP APIs. |
|
||||
| <div className="anchor-with-padding" id="httpallowlistconfig.all">`all`<a class="hash-link" href="#httpallowlistconfig.all"></a></div> | boolean | `false` | Use this flag to enable all HTTP API features. |
|
||||
| <div className="anchor-with-padding" id="httpallowlistconfig.request">`request`<a class="hash-link" href="#httpallowlistconfig.request"></a></div> | boolean | `false` | Allows making HTTP requests. |
|
||||
|
||||
###### HttpAllowlistScope
|
||||
|
||||
HTTP API scope definition. It is a list of URLs that can be accessed by the webview when using the HTTP APIs. The scoped URL is matched against the request URL using a glob pattern.
|
||||
|
||||
Examples:
|
||||
|
||||
- "https://\*": allows all HTTPS urls
|
||||
- "https://\*.github.com/tauri-apps/tauri": allows any subdomain of "github.com" with the "tauri-apps/api" path
|
||||
- "https://myapi.service.com/users/*": allows access to any URLs that begins with "https://myapi.service.com/users/"
|
||||
|
||||
Type: `string _(format: `uri`)_[]`
|
||||
|
||||
##### NotificationAllowlistConfig
|
||||
|
||||
Allowlist for the notification APIs.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ------- | ------------------------------------------------------ |
|
||||
| <div className="anchor-with-padding" id="notificationallowlistconfig.all">`all`<a class="hash-link" href="#notificationallowlistconfig.all"></a></div> | boolean | `false` | Use this flag to enable all notification API features. |
|
||||
|
||||
##### GlobalShortcutAllowlistConfig
|
||||
|
||||
Allowlist for the global shortcut APIs.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | --------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="globalshortcutallowlistconfig.all">`all`<a class="hash-link" href="#globalshortcutallowlistconfig.all"></a></div> | boolean | `false` | Use this flag to enable all global shortcut API features. |
|
||||
|
||||
##### OsAllowlistConfig
|
||||
|
||||
Allowlist for the OS APIs.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ---------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | -------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="osallowlistconfig.all">`all`<a class="hash-link" href="#osallowlistconfig.all"></a></div> | boolean | `false` | Use this flag to enable all OS API features. |
|
||||
|
||||
##### PathAllowlistConfig
|
||||
|
||||
Allowlist for the path APIs.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| -------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | ---------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="pathallowlistconfig.all">`all`<a class="hash-link" href="#pathallowlistconfig.all"></a></div> | boolean | `false` | Use this flag to enable all path API features. |
|
||||
|
||||
##### ProtocolAllowlistConfig
|
||||
|
||||
Allowlist for the custom protocols.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------- | --------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="protocolallowlistconfig.assetscope">`assetScope`<a class="hash-link" href="#protocolallowlistconfig.assetscope"></a></div> | [`FsAllowlistScope`](#fsallowlistscope) | [] | The access scope for the asset protocol. |
|
||||
| <div className="anchor-with-padding" id="protocolallowlistconfig.all">`all`<a class="hash-link" href="#protocolallowlistconfig.all"></a></div> | boolean | `false` | Use this flag to enable all custom protocols. |
|
||||
| <div className="anchor-with-padding" id="protocolallowlistconfig.asset">`asset`<a class="hash-link" href="#protocolallowlistconfig.asset"></a></div> | boolean | `false` | Enables the asset protocol. |
|
||||
|
||||
##### ProcessAllowlistConfig
|
||||
|
||||
Allowlist for the process APIs.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="processallowlistconfig.all">`all`<a class="hash-link" href="#processallowlistconfig.all"></a></div> | boolean | `false` | Use this flag to enable all process APIs. |
|
||||
| <div className="anchor-with-padding" id="processallowlistconfig.relaunch">`relaunch`<a class="hash-link" href="#processallowlistconfig.relaunch"></a></div> | boolean | `false` | Enables the relaunch API. |
|
||||
| <div className="anchor-with-padding" id="processallowlistconfig.relaunchdangerousallowsymlinkmacos">`relaunchDangerousAllowSymlinkMacos`<a class="hash-link" href="#processallowlistconfig.relaunchdangerousallowsymlinkmacos"></a></div> | boolean | `false` | Dangerous option that allows macOS to relaunch even if the binary contains a symlink.<br /><br />This is due to macOS having less symlink protection. Highly recommended to not set this flag unless you have a very specific reason too, and understand the implications of it. |
|
||||
| <div className="anchor-with-padding" id="processallowlistconfig.exit">`exit`<a class="hash-link" href="#processallowlistconfig.exit"></a></div> | boolean | `false` | Enables the exit API. |
|
||||
|
||||
##### ClipboardAllowlistConfig
|
||||
|
||||
Allowlist for the clipboard APIs.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ------- | ------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="clipboardallowlistconfig.all">`all`<a class="hash-link" href="#clipboardallowlistconfig.all"></a></div> | boolean | `false` | Use this flag to enable all clipboard APIs. |
|
||||
| <div className="anchor-with-padding" id="clipboardallowlistconfig.writetext">`writeText`<a class="hash-link" href="#clipboardallowlistconfig.writetext"></a></div> | boolean | `false` | Enables the clipboard's `writeText` API. |
|
||||
| <div className="anchor-with-padding" id="clipboardallowlistconfig.readtext">`readText`<a class="hash-link" href="#clipboardallowlistconfig.readtext"></a></div> | boolean | `false` | Enables the clipboard's `readText` API. |
|
||||
|
||||
##### AppAllowlistConfig
|
||||
|
||||
Allowlist for the app APIs.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| --------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | ------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="appallowlistconfig.all">`all`<a class="hash-link" href="#appallowlistconfig.all"></a></div> | boolean | `false` | Use this flag to enable all app APIs. |
|
||||
| <div className="anchor-with-padding" id="appallowlistconfig.show">`show`<a class="hash-link" href="#appallowlistconfig.show"></a></div> | boolean | `false` | Enables the app's `show` API. |
|
||||
| <div className="anchor-with-padding" id="appallowlistconfig.hide">`hide`<a class="hash-link" href="#appallowlistconfig.hide"></a></div> | boolean | `false` | Enables the app's `hide` API. |
|
||||
|
||||
#### SecurityConfig
|
||||
|
||||
Security configuration.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| <div className="anchor-with-padding" id="securityconfig.csp">`csp`<a class="hash-link" href="#securityconfig.csp"></a></div> | [`Csp`](#csp)? | [view](#csp) | The Content Security Policy that will be injected on all HTML files on the built application. If [`dev_csp`](##securityconfig.devcsp) is not specified, this value is also injected on dev.<br /><br />This is a really important part of the configuration since it helps you ensure your WebView is secured. See <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>. |
|
||||
| <div className="anchor-with-padding" id="securityconfig.devcsp">`devCsp`<a class="hash-link" href="#securityconfig.devcsp"></a></div> | [`Csp`](#csp)? | [view](#csp) | The Content Security Policy that will be injected on all HTML files on development.<br /><br />This is a really important part of the configuration since it helps you ensure your WebView is secured. See <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>. |
|
||||
| <div className="anchor-with-padding" id="securityconfig.freezeprototype">`freezePrototype`<a class="hash-link" href="#securityconfig.freezeprototype"></a></div> | boolean | `false` | Freeze the `Object.prototype` when using the custom protocol. |
|
||||
| <div className="anchor-with-padding" id="securityconfig.dangerousdisableassetcspmodification">`dangerousDisableAssetCspModification`<a class="hash-link" href="#securityconfig.dangerousdisableassetcspmodification"></a></div> | [`DisabledCspModificationKind`](#disabledcspmodificationkind) | `false` | Disables the Tauri-injected CSP sources.<br /><br />At compile time, Tauri parses all the frontend assets and changes the Content-Security-Policy to only allow loading of your own scripts and styles by injecting nonce and hash sources. This stricts your CSP, which may introduce issues when using along with other flexing sources.<br /><br />This configuration option allows both a boolean and a list of strings as value. A boolean instructs Tauri to disable the injection for all CSP injections, and a list of strings indicates the CSP directives that Tauri cannot inject.<br /><br />**WARNING:** Only disable this if you know what you are doing and have properly configured the CSP. Your application might be vulnerable to XSS attacks without this Tauri protection. |
|
||||
| <div className="anchor-with-padding" id="securityconfig.dangerousremotedomainipcaccess">`dangerousRemoteDomainIpcAccess`<a class="hash-link" href="#securityconfig.dangerousremotedomainipcaccess"></a></div> | [`RemoteDomainAccessScope`](#remotedomainaccessscope) | [] | Allow external domains to send command to Tauri.<br /><br />By default, external domains do not have access to `window.__TAURI__`, which means they cannot communicate with the commands defined in Rust. This prevents attacks where an externally loaded malicious or compromised sites could start executing commands on the user's device.<br /><br />This configuration allows a set of external domains to have access to the Tauri commands. When you configure a domain to be allowed to access the IPC, all subpaths are allowed. Subdomains are not allowed.<br /><br />**WARNING:** Only use this option if you either have internal checks against malicious external sites or you can trust the allowed external sites. You application might be vulnerable to dangerous Tauri command related attacks otherwise. |
|
||||
|
||||
##### Csp
|
||||
|
||||
A Content-Security-Policy definition. See <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>.
|
||||
|
||||
Can be any of the following types:
|
||||
|
||||
- `string`: The entire CSP policy in a single text string.
|
||||
- [`CspDirectiveSources`](#cspdirectivesources): An object mapping a directive with its sources values as a list of strings.
|
||||
|
||||
###### CspDirectiveSources
|
||||
|
||||
A Content-Security-Policy directive source list. See <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#sources>.
|
||||
|
||||
Can be any of the following types:
|
||||
|
||||
- `string`: An inline list of CSP sources. Same as `List`, but concatenated with a space separator.
|
||||
- `string[]`: A list of CSP sources. The collection will be concatenated with a space separator for the CSP string.
|
||||
|
||||
##### DisabledCspModificationKind
|
||||
|
||||
The possible values for the `dangerous_disable_asset_csp_modification` config option.
|
||||
|
||||
Can be any of the following types:
|
||||
|
||||
- `boolean`: If `true`, disables all CSP modification. `false` is the default value and it configures Tauri to control the CSP.
|
||||
- `string[]`: Disables the given list of CSP directives modifications.
|
||||
|
||||
##### RemoteDomainAccessScope
|
||||
|
||||
External command access definition.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ------- | ------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="remotedomainaccessscope.scheme">`scheme`<a class="hash-link" href="#remotedomainaccessscope.scheme"></a></div> | string? | _null_ | The URL scheme to allow. By default, all schemas are allowed. |
|
||||
| <div className="anchor-with-padding" id="remotedomainaccessscope.domain">`domain`<a class="hash-link" href="#remotedomainaccessscope.domain"></a></div> | string (required) | | The domain to allow. |
|
||||
| <div className="anchor-with-padding" id="remotedomainaccessscope.windows">`windows`<a class="hash-link" href="#remotedomainaccessscope.windows"></a></div> | string[] (required) | | The list of window labels this scope applies to. |
|
||||
| <div className="anchor-with-padding" id="remotedomainaccessscope.plugins">`plugins`<a class="hash-link" href="#remotedomainaccessscope.plugins"></a></div> | string[] | [] | The list of plugins that are allowed in this scope. |
|
||||
| <div className="anchor-with-padding" id="remotedomainaccessscope.enabletauriapi">`enableTauriAPI`<a class="hash-link" href="#remotedomainaccessscope.enabletauriapi"></a></div> | boolean | `false` | Enables access to the Tauri API. |
|
||||
|
||||
#### UpdaterConfig
|
||||
|
||||
The Updater configuration object.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="updaterconfig.active">`active`<a class="hash-link" href="#updaterconfig.active"></a></div> | boolean | `false` | Whether the updater is active or not. |
|
||||
| <div className="anchor-with-padding" id="updaterconfig.dialog">`dialog`<a class="hash-link" href="#updaterconfig.dialog"></a></div> | boolean | `true` | Display built-in dialog or use event system if disabled. |
|
||||
| <div className="anchor-with-padding" id="updaterconfig.endpoints">`endpoints`<a class="hash-link" href="#updaterconfig.endpoints"></a></div> | [`UpdaterEndpoint`](#updaterendpoint)? | _null_ | The updater endpoints. TLS is enforced on production.<br /><br />The updater URL can contain the following variables:<br />- {{current_version}}: The version of the app that is requesting the update<br />- {{target}}: The operating system name (one of `linux`, `windows` or `darwin`).<br />- {{arch}}: The architecture of the machine (one of `x86_64`, `i686`, `aarch64` or `armv7`).<br /><br /># Examples<br />- "https://my.cdn.com/latest.json": a raw JSON endpoint that returns the latest version and download links for each platform.<br />- "https://updates.app.dev/{{target}}?version={{current_version}}&arch={{arch}}": a dedicated API with positional and query string arguments. |
|
||||
| <div className="anchor-with-padding" id="updaterconfig.pubkey">`pubkey`<a class="hash-link" href="#updaterconfig.pubkey"></a></div> | string | _null_ | Signature public key. |
|
||||
| <div className="anchor-with-padding" id="updaterconfig.windows">`windows`<a class="hash-link" href="#updaterconfig.windows"></a></div> | [`UpdaterWindowsConfig`](#updaterwindowsconfig) | [view](#updaterwindowsconfig) | The Windows configuration for the updater. |
|
||||
|
||||
##### UpdaterEndpoint
|
||||
|
||||
A URL to an updater server.
|
||||
|
||||
The URL must use the `https` scheme on production.
|
||||
|
||||
Type: `string` _(format: `uri`)_
|
||||
|
||||
##### UpdaterWindowsConfig
|
||||
|
||||
The updater configuration for Windows.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="updaterwindowsconfig.installerargs">`installerArgs`<a class="hash-link" href="#updaterwindowsconfig.installerargs"></a></div> | string[] | [] | Additional arguments given to the NSIS or WiX installer. |
|
||||
| <div className="anchor-with-padding" id="updaterwindowsconfig.installmode">`installMode`<a class="hash-link" href="#updaterwindowsconfig.installmode"></a></div> | [`WindowsUpdateInstallMode`](#windowsupdateinstallmode) | [view](#windowsupdateinstallmode) | The installation mode for the update on Windows. Defaults to `passive`. |
|
||||
|
||||
###### WindowsUpdateInstallMode
|
||||
|
||||
Install modes for the Windows update.
|
||||
|
||||
Can be any **ONE** of the following types:
|
||||
|
||||
- "basicUi": Specifies there's a basic UI during the installation process, including a final dialog box at the end.
|
||||
- "quiet": The quiet mode means there's no user interaction required. Requires admin privileges if the installer does.
|
||||
- "passive": Specifies unattended mode, which means the installation only shows a progress bar.
|
||||
|
||||
#### SystemTrayConfig
|
||||
|
||||
Configuration for application system tray icon.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="systemtrayconfig.iconpath">`iconPath`<a class="hash-link" href="#systemtrayconfig.iconpath"></a></div> | string (required) | | Path to the default icon to use on the system tray. |
|
||||
| <div className="anchor-with-padding" id="systemtrayconfig.iconastemplate">`iconAsTemplate`<a class="hash-link" href="#systemtrayconfig.iconastemplate"></a></div> | boolean | `false` | A Boolean value that determines whether the image represents a [template](https://developer.apple.com/documentation/appkit/nsimage/1520017-template?language=objc) image on macOS. |
|
||||
| <div className="anchor-with-padding" id="systemtrayconfig.menuonleftclick">`menuOnLeftClick`<a class="hash-link" href="#systemtrayconfig.menuonleftclick"></a></div> | boolean | `true` | A Boolean value that determines whether the menu should appear when the tray icon receives a left click on macOS. |
|
||||
| <div className="anchor-with-padding" id="systemtrayconfig.title">`title`<a class="hash-link" href="#systemtrayconfig.title"></a></div> | string? | _null_ | Title for MacOS tray |
|
||||
|
||||
### BuildConfig
|
||||
|
||||
The Build configuration object.
|
||||
|
||||
Type: `object`
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="buildconfig.runner">`runner`<a class="hash-link" href="#buildconfig.runner"></a></div> | string? | _null_ | The binary used to build and run the application. |
|
||||
| <div className="anchor-with-padding" id="buildconfig.devpath">`devPath`<a class="hash-link" href="#buildconfig.devpath"></a></div> | [`AppUrl`](#appurl) | [view](#appurl) | The path to the application assets or URL to load in development.<br /><br />This is usually an URL to a dev server, which serves your application assets with live reloading. Most modern JavaScript bundlers provides a way to start a dev server by default.<br /><br />See [vite](https://vitejs.dev/guide/), [Webpack DevServer](https://webpack.js.org/configuration/dev-server/) and [sirv](https://github.com/lukeed/sirv) for examples on how to set up a dev server. |
|
||||
| <div className="anchor-with-padding" id="buildconfig.distdir">`distDir`<a class="hash-link" href="#buildconfig.distdir"></a></div> | [`AppUrl`](#appurl) | [view](#appurl) | The path to the application assets or URL to load in production.<br /><br />When a path relative to the configuration file is provided, it is read recursively and all files are embedded in the application binary. Tauri then looks for an `index.html` file unless you provide a custom window URL.<br /><br />You can also provide a list of paths to be embedded, which allows granular control over what files are added to the binary. In this case, all files are added to the root and you must reference it that way in your HTML files.<br /><br />When an URL is provided, the application won't have bundled assets and the application will load that URL by default. |
|
||||
| <div className="anchor-with-padding" id="buildconfig.beforedevcommand">`beforeDevCommand`<a class="hash-link" href="#buildconfig.beforedevcommand"></a></div> | [`BeforeDevCommand`](#beforedevcommand)? | [view](#beforedevcommand) | A shell command to run before `tauri dev` kicks in.<br /><br />The TAURI_PLATFORM, TAURI_ARCH, TAURI_FAMILY, TAURI_PLATFORM_VERSION, TAURI_PLATFORM_TYPE and TAURI_DEBUG environment variables are set if you perform conditional compilation. |
|
||||
| <div className="anchor-with-padding" id="buildconfig.beforebuildcommand">`beforeBuildCommand`<a class="hash-link" href="#buildconfig.beforebuildcommand"></a></div> | [`HookCommand`](#hookcommand)? | [view](#hookcommand) | A shell command to run before `tauri build` kicks in.<br /><br />The TAURI_PLATFORM, TAURI_ARCH, TAURI_FAMILY, TAURI_PLATFORM_VERSION, TAURI_PLATFORM_TYPE and TAURI_DEBUG environment variables are set if you perform conditional compilation. |
|
||||
| <div className="anchor-with-padding" id="buildconfig.beforebundlecommand">`beforeBundleCommand`<a class="hash-link" href="#buildconfig.beforebundlecommand"></a></div> | [`HookCommand`](#hookcommand)? | [view](#hookcommand) | A shell command to run before the bundling phase in `tauri build` kicks in.<br /><br />The TAURI_PLATFORM, TAURI_ARCH, TAURI_FAMILY, TAURI_PLATFORM_VERSION, TAURI_PLATFORM_TYPE and TAURI_DEBUG environment variables are set if you perform conditional compilation. |
|
||||
| <div className="anchor-with-padding" id="buildconfig.features">`features`<a class="hash-link" href="#buildconfig.features"></a></div> | array? | _null_ | Features passed to `cargo` commands. |
|
||||
| <div className="anchor-with-padding" id="buildconfig.withglobaltauri">`withGlobalTauri`<a class="hash-link" href="#buildconfig.withglobaltauri"></a></div> | boolean | `false` | Whether we should inject the Tauri API on `window.__TAURI__` or not. |
|
||||
|
||||
#### AppUrl
|
||||
|
||||
Defines the URL or assets to embed in the application.
|
||||
|
||||
Can be any of the following types:
|
||||
|
||||
- [`WindowUrl`](#windowurl): The app's external URL, or the path to the directory containing the app assets.
|
||||
- `string[]`: An array of files to embed on the app.
|
||||
|
||||
#### BeforeDevCommand
|
||||
|
||||
Describes the shell command to run before `tauri dev`.
|
||||
|
||||
Can be any of the following types:
|
||||
|
||||
- `string`: Run the given script with the default options.
|
||||
- `{ "script": string, "cwd": string?, "wait": boolean }`: Run the given script with custom options.
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------- | -------------------------------------------------------------------------------------- |
|
||||
| <div className="anchor-with-padding" id="beforedevcommand.script">`script`<a class="hash-link" href="#beforedevcommand.script"></a></div> | string (required) | | The script to execute. |
|
||||
| <div className="anchor-with-padding" id="beforedevcommand.cwd">`cwd`<a class="hash-link" href="#beforedevcommand.cwd"></a></div> | string? | _null_ | The current working directory. |
|
||||
| <div className="anchor-with-padding" id="beforedevcommand.wait">`wait`<a class="hash-link" href="#beforedevcommand.wait"></a></div> | boolean | `false` | Whether `tauri dev` should wait for the command to finish or not. Defaults to `false`. |
|
||||
|
||||
#### HookCommand
|
||||
|
||||
Describes a shell command to be executed when a CLI hook is triggered.
|
||||
|
||||
Can be any of the following types:
|
||||
|
||||
- `string`: Run the given script with the default options.
|
||||
- `{ "script": string, "cwd": string? }`: Run the given script with custom options.
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------- | ------------------------------ |
|
||||
| <div className="anchor-with-padding" id="hookcommand.script">`script`<a class="hash-link" href="#hookcommand.script"></a></div> | string (required) | | The script to execute. |
|
||||
| <div className="anchor-with-padding" id="hookcommand.cwd">`cwd`<a class="hash-link" href="#hookcommand.cwd"></a></div> | string? | _null_ | The current working directory. |
|
||||
|
||||
### PluginConfig
|
||||
|
||||
The plugin configs holds a HashMap mapping a plugin name to its configuration object.
|
||||
|
||||
Type: `object`
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
title: JS API
|
||||
---
|
||||
|
||||
# @tauri-apps/api
|
||||
|
||||
### Modules
|
||||
|
||||
- [app](app.md)
|
||||
- [cli](cli.md)
|
||||
- [clipboard](clipboard.md)
|
||||
- [dialog](dialog.md)
|
||||
- [event](event.md)
|
||||
- [fs](fs.md)
|
||||
- [globalShortcut](globalShortcut.md)
|
||||
- [http](http.md)
|
||||
- [mocks](mocks.md)
|
||||
- [notification](notification.md)
|
||||
- [os](os.md)
|
||||
- [path](path.md)
|
||||
- [process](process.md)
|
||||
- [shell](shell.md)
|
||||
- [tauri](tauri.md)
|
||||
- [updater](updater.md)
|
||||
- [window](window.md)
|
||||
@@ -1,114 +0,0 @@
|
||||
---
|
||||
title: app
|
||||
---
|
||||
|
||||
# app
|
||||
|
||||
Get application metadata.
|
||||
|
||||
This package is also accessible with `window.__TAURI__.app` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
|
||||
|
||||
The APIs must be added to [`tauri.allowlist.app`](https://tauri.app/v1/api/config/#allowlistconfig.app) in `tauri.conf.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"app": {
|
||||
"all": true, // enable all app APIs
|
||||
"show": true,
|
||||
"hide": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
It is recommended to allowlist only the APIs you use for optimal bundle size and security.
|
||||
|
||||
## Functions
|
||||
|
||||
### `getName`
|
||||
|
||||
> **getName**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Gets the application name.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { getName } from "@tauri-apps/api/app";
|
||||
const appName = await getName();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `getTauriVersion`
|
||||
|
||||
> **getTauriVersion**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Gets the Tauri version.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { getTauriVersion } from "@tauri-apps/api/app";
|
||||
const tauriVersion = await getTauriVersion();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `getVersion`
|
||||
|
||||
> **getVersion**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Gets the application version.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { getVersion } from "@tauri-apps/api/app";
|
||||
const appVersion = await getVersion();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `hide`
|
||||
|
||||
> **hide**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Hides the application on macOS.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { hide } from "@tauri-apps/api/app";
|
||||
await hide();
|
||||
```
|
||||
|
||||
**Since**: 1.2.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
### `show`
|
||||
|
||||
> **show**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Shows the application on macOS. This function does not automatically focus any specific app window.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { show } from "@tauri-apps/api/app";
|
||||
await show();
|
||||
```
|
||||
|
||||
**Since**: 1.2.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
@@ -1,100 +0,0 @@
|
||||
---
|
||||
title: cli
|
||||
---
|
||||
|
||||
# cli
|
||||
|
||||
Parse arguments from your Command Line Interface.
|
||||
|
||||
This package is also accessible with `window.__TAURI__.cli` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
|
||||
|
||||
## Interfaces
|
||||
|
||||
### `ArgMatch`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `occurrences`
|
||||
|
||||
> **occurrences**: `number`
|
||||
|
||||
Number of occurrences
|
||||
|
||||
**Defined in:** [cli.ts:27](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/cli.ts#L27)
|
||||
|
||||
##### `value`
|
||||
|
||||
> **value**: `null` \| `string` \| `boolean` \| `string`[]
|
||||
|
||||
string if takes value
|
||||
boolean if flag
|
||||
string[] or null if takes multiple values
|
||||
|
||||
**Defined in:** [cli.ts:23](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/cli.ts#L23)
|
||||
|
||||
### `CliMatches`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `args`
|
||||
|
||||
> **args**: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`ArgMatch`](cli.md#argmatch)\>
|
||||
|
||||
**Defined in:** [cli.ts:42](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/cli.ts#L42)
|
||||
|
||||
##### `subcommand`
|
||||
|
||||
> **subcommand**: `null` \| [`SubcommandMatch`](cli.md#subcommandmatch)
|
||||
|
||||
**Defined in:** [cli.ts:43](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/cli.ts#L43)
|
||||
|
||||
### `SubcommandMatch`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `matches`
|
||||
|
||||
> **matches**: [`CliMatches`](cli.md#climatches)
|
||||
|
||||
**Defined in:** [cli.ts:35](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/cli.ts#L35)
|
||||
|
||||
##### `name`
|
||||
|
||||
> **name**: `string`
|
||||
|
||||
**Defined in:** [cli.ts:34](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/cli.ts#L34)
|
||||
|
||||
## Functions
|
||||
|
||||
### `getMatches`
|
||||
|
||||
> **getMatches**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`CliMatches`](cli.md#climatches)\>
|
||||
|
||||
Parse the arguments provided to the current process and get the matches using the configuration defined [`tauri.cli`](https://tauri.app/v1/api/config/#tauriconfig.cli) in `tauri.conf.json`
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { getMatches } from "@tauri-apps/api/cli";
|
||||
const matches = await getMatches();
|
||||
if (matches.subcommand?.name === "run") {
|
||||
// `./your-app run $ARGS` was executed
|
||||
const args = matches.subcommand?.matches.args;
|
||||
if ("debug" in args) {
|
||||
// `./your-app run --debug` was executed
|
||||
}
|
||||
} else {
|
||||
const args = matches.args;
|
||||
// `./your-app $ARGS` was executed
|
||||
}
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`CliMatches`](cli.md#climatches)\>
|
||||
@@ -1,72 +0,0 @@
|
||||
---
|
||||
title: clipboard
|
||||
---
|
||||
|
||||
# clipboard
|
||||
|
||||
Read and write to the system clipboard.
|
||||
|
||||
This package is also accessible with `window.__TAURI__.clipboard` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
|
||||
|
||||
The APIs must be added to [`tauri.allowlist.clipboard`](https://tauri.app/v1/api/config/#allowlistconfig.clipboard) in `tauri.conf.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"clipboard": {
|
||||
"all": true, // enable all Clipboard APIs
|
||||
"writeText": true,
|
||||
"readText": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
It is recommended to allowlist only the APIs you use for optimal bundle size and security.
|
||||
|
||||
## Functions
|
||||
|
||||
### `readText`
|
||||
|
||||
> **readText**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string` \| `null`\>
|
||||
|
||||
Gets the clipboard content as plain text.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { readText } from "@tauri-apps/api/clipboard";
|
||||
const clipboardText = await readText();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0.
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string` \| `null`\>
|
||||
|
||||
### `writeText`
|
||||
|
||||
> **writeText**(`text`: `string`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Writes plain text to the clipboard.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { writeText, readText } from "@tauri-apps/api/clipboard";
|
||||
await writeText("Tauri is awesome!");
|
||||
assert(await readText(), "Tauri is awesome!");
|
||||
```
|
||||
|
||||
**Since**: 1.0.0.
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :----- | :------- |
|
||||
| `text` | `string` |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
A promise indicating the success or failure of the operation.
|
||||
@@ -1,415 +0,0 @@
|
||||
---
|
||||
title: dialog
|
||||
---
|
||||
|
||||
# dialog
|
||||
|
||||
Native system dialogs for opening and saving files.
|
||||
|
||||
This package is also accessible with `window.__TAURI__.dialog` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
|
||||
|
||||
The APIs must be added to [`tauri.allowlist.dialog`](https://tauri.app/v1/api/config/#allowlistconfig.dialog) in `tauri.conf.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"dialog": {
|
||||
"all": true, // enable all dialog APIs
|
||||
"ask": true, // enable dialog ask API
|
||||
"confirm": true, // enable dialog confirm API
|
||||
"message": true, // enable dialog message API
|
||||
"open": true, // enable file open API
|
||||
"save": true // enable file save API
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
It is recommended to allowlist only the APIs you use for optimal bundle size and security.
|
||||
|
||||
## Interfaces
|
||||
|
||||
### `ConfirmDialogOptions`
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `cancelLabel`
|
||||
|
||||
> `Optional` **cancelLabel**: `string`
|
||||
|
||||
The label of the cancel button.
|
||||
|
||||
**Defined in:** [dialog.ts:112](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L112)
|
||||
|
||||
##### `okLabel`
|
||||
|
||||
> `Optional` **okLabel**: `string`
|
||||
|
||||
The label of the confirm button.
|
||||
|
||||
**Defined in:** [dialog.ts:110](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L110)
|
||||
|
||||
##### `title`
|
||||
|
||||
> `Optional` **title**: `string`
|
||||
|
||||
The title of the dialog. Defaults to the app name.
|
||||
|
||||
**Defined in:** [dialog.ts:106](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L106)
|
||||
|
||||
##### `type`
|
||||
|
||||
> `Optional` **type**: `"info"` \| `"warning"` \| `"error"`
|
||||
|
||||
The type of the dialog. Defaults to `info`.
|
||||
|
||||
**Defined in:** [dialog.ts:108](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L108)
|
||||
|
||||
### `DialogFilter`
|
||||
|
||||
Extension filters for the file dialog.
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `extensions`
|
||||
|
||||
> **extensions**: `string`[]
|
||||
|
||||
Extensions to filter, without a `.` prefix.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
extensions: ["svg", "png"];
|
||||
```
|
||||
|
||||
**Defined in:** [dialog.ts:48](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L48)
|
||||
|
||||
##### `name`
|
||||
|
||||
> **name**: `string`
|
||||
|
||||
Filter name.
|
||||
|
||||
**Defined in:** [dialog.ts:40](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L40)
|
||||
|
||||
### `MessageDialogOptions`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `okLabel`
|
||||
|
||||
> `Optional` **okLabel**: `string`
|
||||
|
||||
The label of the confirm button.
|
||||
|
||||
**Defined in:** [dialog.ts:101](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L101)
|
||||
|
||||
##### `title`
|
||||
|
||||
> `Optional` **title**: `string`
|
||||
|
||||
The title of the dialog. Defaults to the app name.
|
||||
|
||||
**Defined in:** [dialog.ts:97](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L97)
|
||||
|
||||
##### `type`
|
||||
|
||||
> `Optional` **type**: `"info"` \| `"warning"` \| `"error"`
|
||||
|
||||
The type of the dialog. Defaults to `info`.
|
||||
|
||||
**Defined in:** [dialog.ts:99](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L99)
|
||||
|
||||
### `OpenDialogOptions`
|
||||
|
||||
Options for the open dialog.
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `defaultPath`
|
||||
|
||||
> `Optional` **defaultPath**: `string`
|
||||
|
||||
Initial directory or file path.
|
||||
|
||||
**Defined in:** [dialog.ts:62](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L62)
|
||||
|
||||
##### `directory`
|
||||
|
||||
> `Optional` **directory**: `boolean`
|
||||
|
||||
Whether the dialog is a directory selection or not.
|
||||
|
||||
**Defined in:** [dialog.ts:66](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L66)
|
||||
|
||||
##### `filters`
|
||||
|
||||
> `Optional` **filters**: [`DialogFilter`](dialog.md#dialogfilter)[]
|
||||
|
||||
The filters of the dialog.
|
||||
|
||||
**Defined in:** [dialog.ts:60](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L60)
|
||||
|
||||
##### `multiple`
|
||||
|
||||
> `Optional` **multiple**: `boolean`
|
||||
|
||||
Whether the dialog allows multiple selection or not.
|
||||
|
||||
**Defined in:** [dialog.ts:64](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L64)
|
||||
|
||||
##### `recursive`
|
||||
|
||||
> `Optional` **recursive**: `boolean`
|
||||
|
||||
If `directory` is true, indicates that it will be read recursively later.
|
||||
Defines whether subdirectories will be allowed on the scope or not.
|
||||
|
||||
**Defined in:** [dialog.ts:71](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L71)
|
||||
|
||||
##### `title`
|
||||
|
||||
> `Optional` **title**: `string`
|
||||
|
||||
The title of the dialog window.
|
||||
|
||||
**Defined in:** [dialog.ts:58](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L58)
|
||||
|
||||
### `SaveDialogOptions`
|
||||
|
||||
Options for the save dialog.
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `defaultPath`
|
||||
|
||||
> `Optional` **defaultPath**: `string`
|
||||
|
||||
Initial directory or file path.
|
||||
If it's a directory path, the dialog interface will change to that folder.
|
||||
If it's not an existing directory, the file name will be set to the dialog's file name input and the dialog will be set to the parent folder.
|
||||
|
||||
**Defined in:** [dialog.ts:89](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L89)
|
||||
|
||||
##### `filters`
|
||||
|
||||
> `Optional` **filters**: [`DialogFilter`](dialog.md#dialogfilter)[]
|
||||
|
||||
The filters of the dialog.
|
||||
|
||||
**Defined in:** [dialog.ts:83](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L83)
|
||||
|
||||
##### `title`
|
||||
|
||||
> `Optional` **title**: `string`
|
||||
|
||||
The title of the dialog window.
|
||||
|
||||
**Defined in:** [dialog.ts:81](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/dialog.ts#L81)
|
||||
|
||||
## Functions
|
||||
|
||||
### `ask`
|
||||
|
||||
> **ask**(`message`: `string`, `options?`: `string` \| [`ConfirmDialogOptions`](dialog.md#confirmdialogoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`boolean`\>
|
||||
|
||||
Shows a question dialog with `Yes` and `No` buttons.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { ask } from "@tauri-apps/api/dialog";
|
||||
const yes = await ask("Are you sure?", "Tauri");
|
||||
const yes2 = await ask("This action cannot be reverted. Are you sure?", {
|
||||
title: "Tauri",
|
||||
type: "warning",
|
||||
});
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--------- | :------------------------------------------------------------------- | :----------------------------------------------------------------- |
|
||||
| `message` | `string` | The message to show. |
|
||||
| `options?` | `string` \| [`ConfirmDialogOptions`](dialog.md#confirmdialogoptions) | The dialog's options. If a string, it represents the dialog title. |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`boolean`\>
|
||||
|
||||
A promise resolving to a boolean indicating whether `Yes` was clicked or not.
|
||||
|
||||
### `confirm`
|
||||
|
||||
> **confirm**(`message`: `string`, `options?`: `string` \| [`ConfirmDialogOptions`](dialog.md#confirmdialogoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`boolean`\>
|
||||
|
||||
Shows a question dialog with `Ok` and `Cancel` buttons.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { confirm } from "@tauri-apps/api/dialog";
|
||||
const confirmed = await confirm("Are you sure?", "Tauri");
|
||||
const confirmed2 = await confirm(
|
||||
"This action cannot be reverted. Are you sure?",
|
||||
{ title: "Tauri", type: "warning" }
|
||||
);
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--------- | :------------------------------------------------------------------- | :----------------------------------------------------------------- |
|
||||
| `message` | `string` | The message to show. |
|
||||
| `options?` | `string` \| [`ConfirmDialogOptions`](dialog.md#confirmdialogoptions) | The dialog's options. If a string, it represents the dialog title. |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`boolean`\>
|
||||
|
||||
A promise resolving to a boolean indicating whether `Ok` was clicked or not.
|
||||
|
||||
### `message`
|
||||
|
||||
> **message**(`message`: `string`, `options?`: `string` \| [`MessageDialogOptions`](dialog.md#messagedialogoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Shows a message dialog with an `Ok` button.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { message } from "@tauri-apps/api/dialog";
|
||||
await message("Tauri is awesome", "Tauri");
|
||||
await message("File not found", { title: "Tauri", type: "error" });
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--------- | :------------------------------------------------------------------- | :----------------------------------------------------------------- |
|
||||
| `message` | `string` | The message to show. |
|
||||
| `options?` | `string` \| [`MessageDialogOptions`](dialog.md#messagedialogoptions) | The dialog's options. If a string, it represents the dialog title. |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
A promise indicating the success or failure of the operation.
|
||||
|
||||
### `open`
|
||||
|
||||
> **open**(`options?`: [`OpenDialogOptions`](dialog.md#opendialogoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`null` \| `string` \| `string`[]\>
|
||||
|
||||
Open a file/directory selection dialog.
|
||||
|
||||
The selected paths are added to the filesystem and asset protocol allowlist scopes.
|
||||
When security is more important than the easy of use of this API,
|
||||
prefer writing a dedicated command instead.
|
||||
|
||||
Note that the allowlist scope change is not persisted, so the values are cleared when the application is restarted.
|
||||
You can save it to the filesystem using [tauri-plugin-persisted-scope](https://github.com/tauri-apps/tauri-plugin-persisted-scope).
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { open } from "@tauri-apps/api/dialog";
|
||||
// Open a selection dialog for image files
|
||||
const selected = await open({
|
||||
multiple: true,
|
||||
filters: [
|
||||
{
|
||||
name: "Image",
|
||||
extensions: ["png", "jpeg"],
|
||||
},
|
||||
],
|
||||
});
|
||||
if (Array.isArray(selected)) {
|
||||
// user selected multiple files
|
||||
} else if (selected === null) {
|
||||
// user cancelled the selection
|
||||
} else {
|
||||
// user selected a single file
|
||||
}
|
||||
```
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { open } from "@tauri-apps/api/dialog";
|
||||
import { appDir } from "@tauri-apps/api/path";
|
||||
// Open a selection dialog for directories
|
||||
const selected = await open({
|
||||
directory: true,
|
||||
multiple: true,
|
||||
defaultPath: await appDir(),
|
||||
});
|
||||
if (Array.isArray(selected)) {
|
||||
// user selected multiple directories
|
||||
} else if (selected === null) {
|
||||
// user cancelled the selection
|
||||
} else {
|
||||
// user selected a single directory
|
||||
}
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :-------- | :------------------------------------------------- |
|
||||
| `options` | [`OpenDialogOptions`](dialog.md#opendialogoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`null` \| `string` \| `string`[]\>
|
||||
|
||||
A promise resolving to the selected path(s)
|
||||
|
||||
### `save`
|
||||
|
||||
> **save**(`options?`: [`SaveDialogOptions`](dialog.md#savedialogoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string` \| `null`\>
|
||||
|
||||
Open a file/directory save dialog.
|
||||
|
||||
The selected path is added to the filesystem and asset protocol allowlist scopes.
|
||||
When security is more important than the easy of use of this API,
|
||||
prefer writing a dedicated command instead.
|
||||
|
||||
Note that the allowlist scope change is not persisted, so the values are cleared when the application is restarted.
|
||||
You can save it to the filesystem using [tauri-plugin-persisted-scope](https://github.com/tauri-apps/tauri-plugin-persisted-scope).
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { save } from "@tauri-apps/api/dialog";
|
||||
const filePath = await save({
|
||||
filters: [
|
||||
{
|
||||
name: "Image",
|
||||
extensions: ["png", "jpeg"],
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :-------- | :------------------------------------------------- |
|
||||
| `options` | [`SaveDialogOptions`](dialog.md#savedialogoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string` \| `null`\>
|
||||
|
||||
A promise resolving to the selected path.
|
||||
@@ -1,229 +0,0 @@
|
||||
---
|
||||
title: event
|
||||
---
|
||||
|
||||
# event
|
||||
|
||||
The event system allows you to emit events to the backend and listen to events from it.
|
||||
|
||||
This package is also accessible with `window.__TAURI__.event` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
|
||||
|
||||
## Enumerations
|
||||
|
||||
### `TauriEvent`
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
#### Enumeration Members
|
||||
|
||||
| Name | Type | Defined in |
|
||||
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------- | :------------------------------------------------------------------------------------------- |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.CHECK_UPDATE"><a href="#event.TauriEvent.CHECK_UPDATE">`CHECK_UPDATE`</a></div> | `"tauri://update"` | [event.ts:34](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L34) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.DOWNLOAD_PROGRESS"><a href="#event.TauriEvent.DOWNLOAD_PROGRESS">`DOWNLOAD_PROGRESS`</a></div> | `"tauri://update-download-progress"` | [event.ts:38](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L38) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.INSTALL_UPDATE"><a href="#event.TauriEvent.INSTALL_UPDATE">`INSTALL_UPDATE`</a></div> | `"tauri://update-install"` | [event.ts:36](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L36) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.MENU"><a href="#event.TauriEvent.MENU">`MENU`</a></div> | `"tauri://menu"` | [event.ts:33](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L33) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.STATUS_UPDATE"><a href="#event.TauriEvent.STATUS_UPDATE">`STATUS_UPDATE`</a></div> | `"tauri://update-status"` | [event.ts:37](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L37) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.UPDATE_AVAILABLE"><a href="#event.TauriEvent.UPDATE_AVAILABLE">`UPDATE_AVAILABLE`</a></div> | `"tauri://update-available"` | [event.ts:35](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L35) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.WINDOW_BLUR"><a href="#event.TauriEvent.WINDOW_BLUR">`WINDOW_BLUR`</a></div> | `"tauri://blur"` | [event.ts:27](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L27) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.WINDOW_CLOSE_REQUESTED"><a href="#event.TauriEvent.WINDOW_CLOSE_REQUESTED">`WINDOW_CLOSE_REQUESTED`</a></div> | `"tauri://close-requested"` | [event.ts:23](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L23) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.WINDOW_CREATED"><a href="#event.TauriEvent.WINDOW_CREATED">`WINDOW_CREATED`</a></div> | `"tauri://window-created"` | [event.ts:24](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L24) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.WINDOW_DESTROYED"><a href="#event.TauriEvent.WINDOW_DESTROYED">`WINDOW_DESTROYED`</a></div> | `"tauri://destroyed"` | [event.ts:25](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L25) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.WINDOW_FILE_DROP"><a href="#event.TauriEvent.WINDOW_FILE_DROP">`WINDOW_FILE_DROP`</a></div> | `"tauri://file-drop"` | [event.ts:30](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L30) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.WINDOW_FILE_DROP_CANCELLED"><a href="#event.TauriEvent.WINDOW_FILE_DROP_CANCELLED">`WINDOW_FILE_DROP_CANCELLED`</a></div> | `"tauri://file-drop-cancelled"` | [event.ts:32](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L32) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.WINDOW_FILE_DROP_HOVER"><a href="#event.TauriEvent.WINDOW_FILE_DROP_HOVER">`WINDOW_FILE_DROP_HOVER`</a></div> | `"tauri://file-drop-hover"` | [event.ts:31](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L31) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.WINDOW_FOCUS"><a href="#event.TauriEvent.WINDOW_FOCUS">`WINDOW_FOCUS`</a></div> | `"tauri://focus"` | [event.ts:26](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L26) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.WINDOW_MOVED"><a href="#event.TauriEvent.WINDOW_MOVED">`WINDOW_MOVED`</a></div> | `"tauri://move"` | [event.ts:22](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L22) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.WINDOW_RESIZED"><a href="#event.TauriEvent.WINDOW_RESIZED">`WINDOW_RESIZED`</a></div> | `"tauri://resize"` | [event.ts:21](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L21) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.WINDOW_SCALE_FACTOR_CHANGED"><a href="#event.TauriEvent.WINDOW_SCALE_FACTOR_CHANGED">`WINDOW_SCALE_FACTOR_CHANGED`</a></div> | `"tauri://scale-change"` | [event.ts:28](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L28) |
|
||||
| <div class="anchor-with-padding" id="event.TauriEvent.WINDOW_THEME_CHANGED"><a href="#event.TauriEvent.WINDOW_THEME_CHANGED">`WINDOW_THEME_CHANGED`</a></div> | `"tauri://theme-changed"` | [event.ts:29](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L29) |
|
||||
|
||||
## Interfaces
|
||||
|
||||
### `Event<T>`
|
||||
|
||||
**Type parameters**
|
||||
|
||||
- `T`
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `event`
|
||||
|
||||
> **event**: [`EventName`](event.md#eventname)
|
||||
|
||||
Event name
|
||||
|
||||
**Defined in:** [helpers/event.ts:12](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/helpers/event.ts#L12)
|
||||
|
||||
##### `id`
|
||||
|
||||
> **id**: `number`
|
||||
|
||||
Event identifier used to unlisten
|
||||
|
||||
**Defined in:** [helpers/event.ts:16](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/helpers/event.ts#L16)
|
||||
|
||||
##### `payload`
|
||||
|
||||
> **payload**: `T`
|
||||
|
||||
Event payload
|
||||
|
||||
**Defined in:** [helpers/event.ts:18](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/helpers/event.ts#L18)
|
||||
|
||||
##### `windowLabel`
|
||||
|
||||
> **windowLabel**: `string`
|
||||
|
||||
The label of the window that emitted this event.
|
||||
|
||||
**Defined in:** [helpers/event.ts:14](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/helpers/event.ts#L14)
|
||||
|
||||
## Type Aliases
|
||||
|
||||
### `EventCallback<T>`
|
||||
|
||||
> **EventCallback**<`T`\>: (`event`: [`Event`](event.md#event)<`T`\>) => `void`
|
||||
|
||||
**Type parameters**
|
||||
|
||||
- `T`
|
||||
|
||||
**Type declaration**
|
||||
|
||||
> (`event`: [`Event`](event.md#event)<`T`\>): `void`
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :------ | :------------------------------ |
|
||||
| `event` | [`Event`](event.md#event)<`T`\> |
|
||||
|
||||
**Returns: **`void`
|
||||
|
||||
**Defined in:** [helpers/event.ts:21](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/helpers/event.ts#L21)
|
||||
|
||||
### `EventName`
|
||||
|
||||
> **EventName**: `${TauriEvent}` \| `string` & [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`never`, `never`\>
|
||||
|
||||
**Defined in:** [event.ts:15](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/event.ts#L15)
|
||||
|
||||
### `UnlistenFn`
|
||||
|
||||
> **UnlistenFn**: () => `void`
|
||||
|
||||
**Type declaration**
|
||||
|
||||
> (): `void`
|
||||
|
||||
**Returns: **`void`
|
||||
|
||||
**Defined in:** [helpers/event.ts:23](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/helpers/event.ts#L23)
|
||||
|
||||
## Functions
|
||||
|
||||
### `emit`
|
||||
|
||||
> **emit**(`event`: `string`, `payload?`: `unknown`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Emits an event to the backend and all Tauri windows.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { emit } from "@tauri-apps/api/event";
|
||||
await emit("frontend-loaded", { loggedIn: true, token: "authToken" });
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--------- | :-------- | :---------------------------------------------------------------------------- |
|
||||
| `event` | `string` | Event name. Must include only alphanumeric characters, `-`, `/`, `:` and `_`. |
|
||||
| `payload?` | `unknown` | - |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
### `listen`
|
||||
|
||||
> **listen**<`T`\>(`event`: [`EventName`](event.md#eventname), `handler`: [`EventCallback`](event.md#eventcallback)<`T`\>): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`UnlistenFn`](event.md#unlistenfn)\>
|
||||
|
||||
Listen to an event. The event can be either global or window-specific.
|
||||
See [windowLabel](event.md#windowlabel) to check the event source.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { listen } from "@tauri-apps/api/event";
|
||||
const unlisten = await listen<string>("error", (event) => {
|
||||
console.log(
|
||||
`Got error in window ${event.windowLabel}, payload: ${event.payload}`
|
||||
);
|
||||
});
|
||||
|
||||
// you need to call unlisten if your handler goes out of scope e.g. the component is unmounted
|
||||
unlisten();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Type parameters**
|
||||
|
||||
- `T`
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :-------- | :---------------------------------------------- | :---------------------------------------------------------------------------- |
|
||||
| `event` | [`EventName`](event.md#eventname) | Event name. Must include only alphanumeric characters, `-`, `/`, `:` and `_`. |
|
||||
| `handler` | [`EventCallback`](event.md#eventcallback)<`T`\> | Event handler callback. |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`UnlistenFn`](event.md#unlistenfn)\>
|
||||
|
||||
A promise resolving to a function to unlisten to the event.
|
||||
Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.
|
||||
|
||||
### `once`
|
||||
|
||||
> **once**<`T`\>(`event`: [`EventName`](event.md#eventname), `handler`: [`EventCallback`](event.md#eventcallback)<`T`\>): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`UnlistenFn`](event.md#unlistenfn)\>
|
||||
|
||||
Listen to an one-off event. See [listen](event.md#listen) for more information.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { once } from "@tauri-apps/api/event";
|
||||
interface LoadedPayload {
|
||||
loggedIn: boolean;
|
||||
token: string;
|
||||
}
|
||||
const unlisten = await once<LoadedPayload>("loaded", (event) => {
|
||||
console.log(
|
||||
`App is loaded, loggedIn: ${event.payload.loggedIn}, token: ${event.payload.token}`
|
||||
);
|
||||
});
|
||||
|
||||
// you need to call unlisten if your handler goes out of scope e.g. the component is unmounted
|
||||
unlisten();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Type parameters**
|
||||
|
||||
- `T`
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :-------- | :---------------------------------------------- | :---------------------------------------------------------------------------- |
|
||||
| `event` | [`EventName`](event.md#eventname) | Event name. Must include only alphanumeric characters, `-`, `/`, `:` and `_`. |
|
||||
| `handler` | [`EventCallback`](event.md#eventcallback)<`T`\> | - |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`UnlistenFn`](event.md#unlistenfn)\>
|
||||
|
||||
A promise resolving to a function to unlisten to the event.
|
||||
Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.
|
||||
@@ -1,609 +0,0 @@
|
||||
---
|
||||
title: fs
|
||||
---
|
||||
|
||||
# fs
|
||||
|
||||
Access the file system.
|
||||
|
||||
This package is also accessible with `window.__TAURI__.fs` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
|
||||
|
||||
The APIs must be added to [`tauri.allowlist.fs`](https://tauri.app/v1/api/config/#allowlistconfig.fs) in `tauri.conf.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"fs": {
|
||||
"all": true, // enable all FS APIs
|
||||
"readFile": true,
|
||||
"writeFile": true,
|
||||
"readDir": true,
|
||||
"copyFile": true,
|
||||
"createDir": true,
|
||||
"removeDir": true,
|
||||
"removeFile": true,
|
||||
"renameFile": true,
|
||||
"exists": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
It is recommended to allowlist only the APIs you use for optimal bundle size and security.
|
||||
|
||||
## Security
|
||||
|
||||
This module prevents path traversal, not allowing absolute paths or parent dir components
|
||||
(i.e. "/usr/path/to/file" or "../path/to/file" paths are not allowed).
|
||||
Paths accessed with this API must be relative to one of the [base directories](fs.md#basedirectory)
|
||||
so if you need access to arbitrary filesystem paths, you must write such logic on the core layer instead.
|
||||
|
||||
The API has a scope configuration that forces you to restrict the paths that can be accessed using glob patterns.
|
||||
|
||||
The scope configuration is an array of glob patterns describing folder paths that are allowed.
|
||||
For instance, this scope configuration only allows accessing files on the
|
||||
_databases_ folder of the [$APPDATA directory](path.md#appdatadir):
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"fs": {
|
||||
"scope": ["$APPDATA/databases/*"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notice the use of the `$APPDATA` variable. The value is injected at runtime, resolving to the [app data directory](path.md#appdatadir).
|
||||
The available variables are:
|
||||
[`$APPCONFIG`](path.md#appconfigdir), [`$APPDATA`](path.md#appdatadir), [`$APPLOCALDATA`](path.md#applocaldatadir),
|
||||
[`$APPCACHE`](path.md#appcachedir), [`$APPLOG`](path.md#applogdir),
|
||||
[`$AUDIO`](path.md#audiodir), [`$CACHE`](path.md#cachedir), [`$CONFIG`](path.md#configdir), [`$DATA`](path.md#datadir),
|
||||
[`$LOCALDATA`](path.md#localdatadir), [`$DESKTOP`](path.md#desktopdir), [`$DOCUMENT`](path.md#documentdir),
|
||||
[`$DOWNLOAD`](path.md#downloaddir), [`$EXE`](path.md#executabledir), [`$FONT`](path.md#fontdir), [`$HOME`](path.md#homedir),
|
||||
[`$PICTURE`](path.md#picturedir), [`$PUBLIC`](path.md#publicdir), [`$RUNTIME`](path.md#runtimedir),
|
||||
[`$TEMPLATE`](path.md#templatedir), [`$VIDEO`](path.md#videodir), [`$RESOURCE`](path.md#resourcedir), [`$APP`](path.md#appdir),
|
||||
[`$LOG`](path.md#logdir), [`$TEMP`](os.md#tempdir).
|
||||
|
||||
Trying to execute any API with a URL not configured on the scope results in a promise rejection due to denied access.
|
||||
|
||||
Note that this scope applies to **all** APIs on this module.
|
||||
|
||||
## References
|
||||
|
||||
### `Dir`
|
||||
|
||||
Renames and re-exports [BaseDirectory](fs.md#basedirectory)
|
||||
|
||||
### `writeFile`
|
||||
|
||||
Renames and re-exports [writeTextFile](fs.md#writetextfile)
|
||||
|
||||
## Enumerations
|
||||
|
||||
### `BaseDirectory`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Enumeration Members
|
||||
|
||||
| Name | Type | Defined in |
|
||||
| :------------------------------------------------------------------------------------------------------------------------------------ | :--- | :--------------------------------------------------------------------------------------- |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.App"><a href="#fs.BaseDirectory.App">`App`</a></div> | `18` | [fs.ts:98](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L98) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.AppCache"><a href="#fs.BaseDirectory.AppCache">`AppCache`</a></div> | `24` | [fs.ts:104](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L104) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.AppConfig"><a href="#fs.BaseDirectory.AppConfig">`AppConfig`</a></div> | `21` | [fs.ts:101](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L101) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.AppData"><a href="#fs.BaseDirectory.AppData">`AppData`</a></div> | `22` | [fs.ts:102](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L102) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.AppLocalData"><a href="#fs.BaseDirectory.AppLocalData">`AppLocalData`</a></div> | `23` | [fs.ts:103](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L103) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.AppLog"><a href="#fs.BaseDirectory.AppLog">`AppLog`</a></div> | `25` | [fs.ts:105](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L105) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Audio"><a href="#fs.BaseDirectory.Audio">`Audio`</a></div> | `1` | [fs.ts:81](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L81) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Cache"><a href="#fs.BaseDirectory.Cache">`Cache`</a></div> | `2` | [fs.ts:82](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L82) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Config"><a href="#fs.BaseDirectory.Config">`Config`</a></div> | `3` | [fs.ts:83](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L83) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Data"><a href="#fs.BaseDirectory.Data">`Data`</a></div> | `4` | [fs.ts:84](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L84) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Desktop"><a href="#fs.BaseDirectory.Desktop">`Desktop`</a></div> | `6` | [fs.ts:86](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L86) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Document"><a href="#fs.BaseDirectory.Document">`Document`</a></div> | `7` | [fs.ts:87](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L87) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Download"><a href="#fs.BaseDirectory.Download">`Download`</a></div> | `8` | [fs.ts:88](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L88) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Executable"><a href="#fs.BaseDirectory.Executable">`Executable`</a></div> | `9` | [fs.ts:89](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L89) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Font"><a href="#fs.BaseDirectory.Font">`Font`</a></div> | `10` | [fs.ts:90](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L90) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Home"><a href="#fs.BaseDirectory.Home">`Home`</a></div> | `11` | [fs.ts:91](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L91) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.LocalData"><a href="#fs.BaseDirectory.LocalData">`LocalData`</a></div> | `5` | [fs.ts:85](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L85) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Log"><a href="#fs.BaseDirectory.Log">`Log`</a></div> | `19` | [fs.ts:99](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L99) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Picture"><a href="#fs.BaseDirectory.Picture">`Picture`</a></div> | `12` | [fs.ts:92](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L92) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Public"><a href="#fs.BaseDirectory.Public">`Public`</a></div> | `13` | [fs.ts:93](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L93) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Resource"><a href="#fs.BaseDirectory.Resource">`Resource`</a></div> | `17` | [fs.ts:97](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L97) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Runtime"><a href="#fs.BaseDirectory.Runtime">`Runtime`</a></div> | `14` | [fs.ts:94](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L94) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Temp"><a href="#fs.BaseDirectory.Temp">`Temp`</a></div> | `20` | [fs.ts:100](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L100) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Template"><a href="#fs.BaseDirectory.Template">`Template`</a></div> | `15` | [fs.ts:95](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L95) |
|
||||
| <div class="anchor-with-padding" id="fs.BaseDirectory.Video"><a href="#fs.BaseDirectory.Video">`Video`</a></div> | `16` | [fs.ts:96](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L96) |
|
||||
|
||||
## Interfaces
|
||||
|
||||
### `FileEntry`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `children`
|
||||
|
||||
> `Optional` **children**: [`FileEntry`](fs.md#fileentry)[]
|
||||
|
||||
Children of this entry if it's a directory; null otherwise
|
||||
|
||||
**Defined in:** [fs.ts:161](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L161)
|
||||
|
||||
##### `name`
|
||||
|
||||
> `Optional` **name**: `string`
|
||||
|
||||
Name of the directory/file
|
||||
can be null if the path terminates with `..`
|
||||
|
||||
**Defined in:** [fs.ts:159](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L159)
|
||||
|
||||
##### `path`
|
||||
|
||||
> **path**: `string`
|
||||
|
||||
**Defined in:** [fs.ts:154](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L154)
|
||||
|
||||
### `FsBinaryFileOption`
|
||||
|
||||
Options object used to write a binary data to a file.
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `contents`
|
||||
|
||||
> **contents**: [`BinaryFileContents`](fs.md#binaryfilecontents)
|
||||
|
||||
The byte array contents.
|
||||
|
||||
**Defined in:** [fs.ts:147](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L147)
|
||||
|
||||
##### `path`
|
||||
|
||||
> **path**: `string`
|
||||
|
||||
Path to the file to write.
|
||||
|
||||
**Defined in:** [fs.ts:145](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L145)
|
||||
|
||||
### `FsDirOptions`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `dir`
|
||||
|
||||
> `Optional` **dir**: [`BaseDirectory`](fs.md#basedirectory)
|
||||
|
||||
**Defined in:** [fs.ts:120](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L120)
|
||||
|
||||
##### `recursive`
|
||||
|
||||
> `Optional` **recursive**: `boolean`
|
||||
|
||||
**Defined in:** [fs.ts:121](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L121)
|
||||
|
||||
### `FsOptions`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `dir`
|
||||
|
||||
> `Optional` **dir**: [`BaseDirectory`](fs.md#basedirectory)
|
||||
|
||||
**Defined in:** [fs.ts:112](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L112)
|
||||
|
||||
### `FsTextFileOption`
|
||||
|
||||
Options object used to write a UTF-8 string to a file.
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `contents`
|
||||
|
||||
> **contents**: `string`
|
||||
|
||||
The UTF-8 string to write to the file.
|
||||
|
||||
**Defined in:** [fs.ts:133](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L133)
|
||||
|
||||
##### `path`
|
||||
|
||||
> **path**: `string`
|
||||
|
||||
Path to the file to write.
|
||||
|
||||
**Defined in:** [fs.ts:131](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L131)
|
||||
|
||||
## Type Aliases
|
||||
|
||||
### `BinaryFileContents`
|
||||
|
||||
> **BinaryFileContents**: `Iterable`<`number`\> \| `ArrayLike`<`number`\> \| [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)
|
||||
|
||||
**Defined in:** [fs.ts:136](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/fs.ts#L136)
|
||||
|
||||
## Functions
|
||||
|
||||
### `copyFile`
|
||||
|
||||
> **copyFile**(`source`: `string`, `destination`: `string`, `options?`: [`FsOptions`](fs.md#fsoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Copies a file to a destination.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { copyFile, BaseDirectory } from "@tauri-apps/api/fs";
|
||||
// Copy the `$APPCONFIG/app.conf` file to `$APPCONFIG/app.conf.bk`
|
||||
await copyFile("app.conf", "app.conf.bk", { dir: BaseDirectory.AppConfig });
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :------------ | :----------------------------- |
|
||||
| `source` | `string` |
|
||||
| `destination` | `string` |
|
||||
| `options` | [`FsOptions`](fs.md#fsoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
A promise indicating the success or failure of the operation.
|
||||
|
||||
### `createDir`
|
||||
|
||||
> **createDir**(`dir`: `string`, `options?`: [`FsDirOptions`](fs.md#fsdiroptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Creates a directory.
|
||||
If one of the path's parent components doesn't exist
|
||||
and the `recursive` option isn't set to true, the promise will be rejected.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { createDir, BaseDirectory } from "@tauri-apps/api/fs";
|
||||
// Create the `$APPDATA/users` directory
|
||||
await createDir("users", { dir: BaseDirectory.AppData, recursive: true });
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :-------- | :----------------------------------- |
|
||||
| `dir` | `string` |
|
||||
| `options` | [`FsDirOptions`](fs.md#fsdiroptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
A promise indicating the success or failure of the operation.
|
||||
|
||||
### `exists`
|
||||
|
||||
> **exists**(`path`: `string`, `options?`: [`FsOptions`](fs.md#fsoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`boolean`\>
|
||||
|
||||
Check if a path exists.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { exists, BaseDirectory } from "@tauri-apps/api/fs";
|
||||
// Check if the `$APPDATA/avatar.png` file exists
|
||||
await exists("avatar.png", { dir: BaseDirectory.AppData });
|
||||
```
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :-------- | :----------------------------- |
|
||||
| `path` | `string` |
|
||||
| `options` | [`FsOptions`](fs.md#fsoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`boolean`\>
|
||||
|
||||
### `readBinaryFile`
|
||||
|
||||
> **readBinaryFile**(`filePath`: `string`, `options?`: [`FsOptions`](fs.md#fsoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)\>
|
||||
|
||||
Reads a file as byte array.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { readBinaryFile, BaseDirectory } from "@tauri-apps/api/fs";
|
||||
// Read the image file in the `$RESOURCEDIR/avatar.png` path
|
||||
const contents = await readBinaryFile("avatar.png", {
|
||||
dir: BaseDirectory.Resource,
|
||||
});
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :--------- | :----------------------------- |
|
||||
| `filePath` | `string` |
|
||||
| `options` | [`FsOptions`](fs.md#fsoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)\>
|
||||
|
||||
### `readDir`
|
||||
|
||||
> **readDir**(`dir`: `string`, `options?`: [`FsDirOptions`](fs.md#fsdiroptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`FileEntry`](fs.md#fileentry)[]\>
|
||||
|
||||
List directory files.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { readDir, BaseDirectory } from "@tauri-apps/api/fs";
|
||||
// Reads the `$APPDATA/users` directory recursively
|
||||
const entries = await readDir("users", {
|
||||
dir: BaseDirectory.AppData,
|
||||
recursive: true,
|
||||
});
|
||||
|
||||
function processEntries(entries) {
|
||||
for (const entry of entries) {
|
||||
console.log(`Entry: ${entry.path}`);
|
||||
if (entry.children) {
|
||||
processEntries(entry.children);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :-------- | :----------------------------------- |
|
||||
| `dir` | `string` |
|
||||
| `options` | [`FsDirOptions`](fs.md#fsdiroptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`FileEntry`](fs.md#fileentry)[]\>
|
||||
|
||||
### `readTextFile`
|
||||
|
||||
> **readTextFile**(`filePath`: `string`, `options?`: [`FsOptions`](fs.md#fsoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Reads a file as an UTF-8 encoded string.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { readTextFile, BaseDirectory } from "@tauri-apps/api/fs";
|
||||
// Read the text file in the `$APPCONFIG/app.conf` path
|
||||
const contents = await readTextFile("app.conf", {
|
||||
dir: BaseDirectory.AppConfig,
|
||||
});
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :--------- | :----------------------------- |
|
||||
| `filePath` | `string` |
|
||||
| `options` | [`FsOptions`](fs.md#fsoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `removeDir`
|
||||
|
||||
> **removeDir**(`dir`: `string`, `options?`: [`FsDirOptions`](fs.md#fsdiroptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Removes a directory.
|
||||
If the directory is not empty and the `recursive` option isn't set to true, the promise will be rejected.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { removeDir, BaseDirectory } from "@tauri-apps/api/fs";
|
||||
// Remove the directory `$APPDATA/users`
|
||||
await removeDir("users", { dir: BaseDirectory.AppData });
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :-------- | :----------------------------------- |
|
||||
| `dir` | `string` |
|
||||
| `options` | [`FsDirOptions`](fs.md#fsdiroptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
A promise indicating the success or failure of the operation.
|
||||
|
||||
### `removeFile`
|
||||
|
||||
> **removeFile**(`file`: `string`, `options?`: [`FsOptions`](fs.md#fsoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Removes a file.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { removeFile, BaseDirectory } from "@tauri-apps/api/fs";
|
||||
// Remove the `$APPConfig/app.conf` file
|
||||
await removeFile("app.conf", { dir: BaseDirectory.AppConfig });
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :-------- | :----------------------------- |
|
||||
| `file` | `string` |
|
||||
| `options` | [`FsOptions`](fs.md#fsoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
A promise indicating the success or failure of the operation.
|
||||
|
||||
### `renameFile`
|
||||
|
||||
> **renameFile**(`oldPath`: `string`, `newPath`: `string`, `options?`: [`FsOptions`](fs.md#fsoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Renames a file.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { renameFile, BaseDirectory } from "@tauri-apps/api/fs";
|
||||
// Rename the `$APPDATA/avatar.png` file
|
||||
await renameFile("avatar.png", "deleted.png", { dir: BaseDirectory.AppData });
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :-------- | :----------------------------- |
|
||||
| `oldPath` | `string` |
|
||||
| `newPath` | `string` |
|
||||
| `options` | [`FsOptions`](fs.md#fsoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
A promise indicating the success or failure of the operation.
|
||||
|
||||
### `writeBinaryFile`
|
||||
|
||||
> **writeBinaryFile**(`path`: `string`, `contents`: [`BinaryFileContents`](fs.md#binaryfilecontents), `options?`: [`FsOptions`](fs.md#fsoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Writes a byte array content to a file.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { writeBinaryFile, BaseDirectory } from "@tauri-apps/api/fs";
|
||||
// Write a binary file to the `$APPDATA/avatar.png` path
|
||||
await writeBinaryFile("avatar.png", new Uint8Array([]), {
|
||||
dir: BaseDirectory.AppData,
|
||||
});
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--------- | :----------------------------------------------- | :-------------------- |
|
||||
| `path` | `string` | - |
|
||||
| `contents` | [`BinaryFileContents`](fs.md#binaryfilecontents) | - |
|
||||
| `options?` | [`FsOptions`](fs.md#fsoptions) | Configuration object. |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
A promise indicating the success or failure of the operation.
|
||||
|
||||
> **writeBinaryFile**(`file`: [`FsBinaryFileOption`](fs.md#fsbinaryfileoption), `options?`: [`FsOptions`](fs.md#fsoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Writes a byte array content to a file.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { writeBinaryFile, BaseDirectory } from "@tauri-apps/api/fs";
|
||||
// Write a binary file to the `$APPDATA/avatar.png` path
|
||||
await writeBinaryFile(
|
||||
{ path: "avatar.png", contents: new Uint8Array([]) },
|
||||
{ dir: BaseDirectory.AppData }
|
||||
);
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--------- | :----------------------------------------------- | :------------------------------------------------ |
|
||||
| `file` | [`FsBinaryFileOption`](fs.md#fsbinaryfileoption) | The object containing the file path and contents. |
|
||||
| `options?` | [`FsOptions`](fs.md#fsoptions) | Configuration object. |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
A promise indicating the success or failure of the operation.
|
||||
|
||||
### `writeTextFile`
|
||||
|
||||
> **writeTextFile**(`path`: `string`, `contents`: `string`, `options?`: [`FsOptions`](fs.md#fsoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Writes a UTF-8 text file.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { writeTextFile, BaseDirectory } from "@tauri-apps/api/fs";
|
||||
// Write a text file to the `$APPCONFIG/app.conf` path
|
||||
await writeTextFile("app.conf", "file contents", {
|
||||
dir: BaseDirectory.AppConfig,
|
||||
});
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :--------- | :----------------------------- |
|
||||
| `path` | `string` |
|
||||
| `contents` | `string` |
|
||||
| `options?` | [`FsOptions`](fs.md#fsoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
> **writeTextFile**(`file`: [`FsTextFileOption`](fs.md#fstextfileoption), `options?`: [`FsOptions`](fs.md#fsoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Writes a UTF-8 text file.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { writeTextFile, BaseDirectory } from "@tauri-apps/api/fs";
|
||||
// Write a text file to the `$APPCONFIG/app.conf` path
|
||||
await writeTextFile(
|
||||
{ path: "app.conf", contents: "file contents" },
|
||||
{ dir: BaseDirectory.AppConfig }
|
||||
);
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :--------- | :------------------------------------------- |
|
||||
| `file` | [`FsTextFileOption`](fs.md#fstextfileoption) |
|
||||
| `options?` | [`FsOptions`](fs.md#fsoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
A promise indicating the success or failure of the operation.
|
||||
@@ -1,162 +0,0 @@
|
||||
---
|
||||
title: globalShortcut
|
||||
---
|
||||
|
||||
# globalShortcut
|
||||
|
||||
Register global shortcuts.
|
||||
|
||||
This package is also accessible with `window.__TAURI__.globalShortcut` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
|
||||
|
||||
The APIs must be added to [`tauri.allowlist.globalShortcut`](https://tauri.app/v1/api/config/#allowlistconfig.globalshortcut) in `tauri.conf.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"globalShortcut": {
|
||||
"all": true // enable all global shortcut APIs
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
It is recommended to allowlist only the APIs you use for optimal bundle size and security.
|
||||
|
||||
## Type Aliases
|
||||
|
||||
### `ShortcutHandler`
|
||||
|
||||
> **ShortcutHandler**: (`shortcut`: `string`) => `void`
|
||||
|
||||
**Type declaration**
|
||||
|
||||
> (`shortcut`: `string`): `void`
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :--------- | :------- |
|
||||
| `shortcut` | `string` |
|
||||
|
||||
**Returns: **`void`
|
||||
|
||||
**Defined in:** [globalShortcut.ts:29](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/globalShortcut.ts#L29)
|
||||
|
||||
## Functions
|
||||
|
||||
### `isRegistered`
|
||||
|
||||
> **isRegistered**(`shortcut`: `string`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`boolean`\>
|
||||
|
||||
Determines whether the given shortcut is registered by this application or not.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { isRegistered } from "@tauri-apps/api/globalShortcut";
|
||||
const isRegistered = await isRegistered("CommandOrControl+P");
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--------- | :------- | :------------------------------------------------------------------------------------ |
|
||||
| `shortcut` | `string` | Array of shortcut definitions, modifiers and key separated by "+" e.g. CmdOrControl+Q |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`boolean`\>
|
||||
|
||||
### `register`
|
||||
|
||||
> **register**(`shortcut`: `string`, `handler`: [`ShortcutHandler`](globalShortcut.md#shortcuthandler)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Register a global shortcut.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { register } from "@tauri-apps/api/globalShortcut";
|
||||
await register("CommandOrControl+Shift+C", () => {
|
||||
console.log("Shortcut triggered");
|
||||
});
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--------- | :----------------------------------------------------- | :-------------------------------------------------------------------------- |
|
||||
| `shortcut` | `string` | Shortcut definition, modifiers and key separated by "+" e.g. CmdOrControl+Q |
|
||||
| `handler` | [`ShortcutHandler`](globalShortcut.md#shortcuthandler) | Shortcut handler callback - takes the triggered shortcut as argument |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
### `registerAll`
|
||||
|
||||
> **registerAll**(`shortcuts`: `string`[], `handler`: [`ShortcutHandler`](globalShortcut.md#shortcuthandler)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Register a collection of global shortcuts.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { registerAll } from "@tauri-apps/api/globalShortcut";
|
||||
await registerAll(["CommandOrControl+Shift+C", "Ctrl+Alt+F12"], (shortcut) => {
|
||||
console.log(`Shortcut ${shortcut} triggered`);
|
||||
});
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :---------- | :----------------------------------------------------- | :------------------------------------------------------------------------------------ |
|
||||
| `shortcuts` | `string`[] | Array of shortcut definitions, modifiers and key separated by "+" e.g. CmdOrControl+Q |
|
||||
| `handler` | [`ShortcutHandler`](globalShortcut.md#shortcuthandler) | Shortcut handler callback - takes the triggered shortcut as argument |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
### `unregister`
|
||||
|
||||
> **unregister**(`shortcut`: `string`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Unregister a global shortcut.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { unregister } from "@tauri-apps/api/globalShortcut";
|
||||
await unregister("CmdOrControl+Space");
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--------- | :------- | :-------------------------------------------------------------------------- |
|
||||
| `shortcut` | `string` | shortcut definition, modifiers and key separated by "+" e.g. CmdOrControl+Q |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
### `unregisterAll`
|
||||
|
||||
> **unregisterAll**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Unregisters all shortcuts registered by the application.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { unregisterAll } from "@tauri-apps/api/globalShortcut";
|
||||
await unregisterAll();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
@@ -1,682 +0,0 @@
|
||||
---
|
||||
title: http
|
||||
---
|
||||
|
||||
# http
|
||||
|
||||
Access the HTTP client written in Rust.
|
||||
|
||||
This package is also accessible with `window.__TAURI__.http` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
|
||||
|
||||
The APIs must be allowlisted on `tauri.conf.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"http": {
|
||||
"all": true, // enable all http APIs
|
||||
"request": true // enable HTTP request API
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
It is recommended to allowlist only the APIs you use for optimal bundle size and security.
|
||||
|
||||
## Security
|
||||
|
||||
This API has a scope configuration that forces you to restrict the URLs and paths that can be accessed using glob patterns.
|
||||
|
||||
For instance, this scope configuration only allows making HTTP requests to the GitHub API for the `tauri-apps` organization:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"http": {
|
||||
"scope": ["https://api.github.com/repos/tauri-apps/*"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Trying to execute any API with a URL not configured on the scope results in a promise rejection due to denied access.
|
||||
|
||||
## Enumerations
|
||||
|
||||
### `ResponseType`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Enumeration Members
|
||||
|
||||
| Name | Type | Defined in |
|
||||
| :-------------------------------------------------------------------------------------------------------------------- | :--- | :----------------------------------------------------------------------------------------- |
|
||||
| <div class="anchor-with-padding" id="http.ResponseType.Binary"><a href="#http.ResponseType.Binary">`Binary`</a></div> | `3` | [http.ts:74](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L74) |
|
||||
| <div class="anchor-with-padding" id="http.ResponseType.JSON"><a href="#http.ResponseType.JSON">`JSON`</a></div> | `1` | [http.ts:72](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L72) |
|
||||
| <div class="anchor-with-padding" id="http.ResponseType.Text"><a href="#http.ResponseType.Text">`Text`</a></div> | `2` | [http.ts:73](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L73) |
|
||||
|
||||
## Classes
|
||||
|
||||
### `Body`
|
||||
|
||||
The body object to be used on POST and PUT requests.
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `payload`
|
||||
|
||||
> **payload**: `unknown`
|
||||
|
||||
**Defined in:** [http.ts:95](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L95)
|
||||
|
||||
##### `type`
|
||||
|
||||
> **type**: `string`
|
||||
|
||||
**Defined in:** [http.ts:94](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L94)
|
||||
|
||||
#### Methods
|
||||
|
||||
##### `bytes`
|
||||
|
||||
> `Static` **bytes**(`bytes`: `Iterable`<`number`\> \| [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) \| `ArrayLike`<`number`\>): [`Body`](http.md#body)
|
||||
|
||||
Creates a new byte array body.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { Body } from "@tauri-apps/api/http";
|
||||
Body.bytes(new Uint8Array([1, 2, 3]));
|
||||
```
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |
|
||||
| `bytes` | `Iterable`<`number`\> \| [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) \| `ArrayLike`<`number`\> | The body byte array. |
|
||||
|
||||
**Returns: **[`Body`](http.md#body)
|
||||
|
||||
The body object ready to be used on the POST and PUT requests.
|
||||
|
||||
##### `form`
|
||||
|
||||
> `Static` **form**(`data`: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`Part`](http.md#part)\> \| [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)): [`Body`](http.md#body)
|
||||
|
||||
Creates a new form data body. The form data is an object where each key is the entry name,
|
||||
and the value is either a string or a file object.
|
||||
|
||||
By default it sets the `application/x-www-form-urlencoded` Content-Type header,
|
||||
but you can set it to `multipart/form-data` if the Cargo feature `http-multipart` is enabled.
|
||||
|
||||
Note that a file path must be allowed in the `fs` allowlist scope.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { Body } from "@tauri-apps/api/http";
|
||||
const body = Body.form({
|
||||
key: "value",
|
||||
image: {
|
||||
file: "/path/to/file", // either a path or an array buffer of the file contents
|
||||
mime: "image/jpeg", // optional
|
||||
fileName: "image.jpg", // optional
|
||||
},
|
||||
});
|
||||
|
||||
// alternatively, use a FormData:
|
||||
const form = new FormData();
|
||||
form.append("key", "value");
|
||||
form.append("image", file, "image.png");
|
||||
const formBody = Body.form(form);
|
||||
```
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |
|
||||
| `data` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, [`Part`](http.md#part)\> \| [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) | The body data. |
|
||||
|
||||
**Returns: **[`Body`](http.md#body)
|
||||
|
||||
The body object ready to be used on the POST and PUT requests.
|
||||
|
||||
##### `json`
|
||||
|
||||
> `Static` **json**(`data`: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`any`, `any`\>): [`Body`](http.md#body)
|
||||
|
||||
Creates a new JSON body.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { Body } from "@tauri-apps/api/http";
|
||||
Body.json({
|
||||
registered: true,
|
||||
name: "tauri",
|
||||
});
|
||||
```
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :----- | :--------------------------------------------------------------------------------------------------------- | :-------------------- |
|
||||
| `data` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`any`, `any`\> | The body JSON object. |
|
||||
|
||||
**Returns: **[`Body`](http.md#body)
|
||||
|
||||
The body object ready to be used on the POST and PUT requests.
|
||||
|
||||
##### `text`
|
||||
|
||||
> `Static` **text**(`value`: `string`): [`Body`](http.md#body)
|
||||
|
||||
Creates a new UTF-8 string body.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { Body } from "@tauri-apps/api/http";
|
||||
Body.text("The body content as a string");
|
||||
```
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------ | :------- | :--------------- |
|
||||
| `value` | `string` | The body string. |
|
||||
|
||||
**Returns: **[`Body`](http.md#body)
|
||||
|
||||
The body object ready to be used on the POST and PUT requests.
|
||||
|
||||
### `Client`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `id`
|
||||
|
||||
> **id**: `number`
|
||||
|
||||
**Defined in:** [http.ts:303](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L303)
|
||||
|
||||
#### Methods
|
||||
|
||||
##### `delete`
|
||||
|
||||
> **delete**<`T`\>(`url`: `string`, `options?`: [`RequestOptions`](http.md#requestoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Response`](http.md#response)<`T`\>\>
|
||||
|
||||
Makes a DELETE request.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { getClient } from "@tauri-apps/api/http";
|
||||
const client = await getClient();
|
||||
const response = await client.delete("http://localhost:3003/users/1");
|
||||
```
|
||||
|
||||
**Type parameters**
|
||||
|
||||
- `T`
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :--------- | :----------------------------------------- |
|
||||
| `url` | `string` |
|
||||
| `options?` | [`RequestOptions`](http.md#requestoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Response`](http.md#response)<`T`\>\>
|
||||
|
||||
##### `drop`
|
||||
|
||||
> **drop**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Drops the client instance.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { getClient } from "@tauri-apps/api/http";
|
||||
const client = await getClient();
|
||||
await client.drop();
|
||||
```
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
##### `get`
|
||||
|
||||
> **get**<`T`\>(`url`: `string`, `options?`: [`RequestOptions`](http.md#requestoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Response`](http.md#response)<`T`\>\>
|
||||
|
||||
Makes a GET request.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { getClient, ResponseType } from "@tauri-apps/api/http";
|
||||
const client = await getClient();
|
||||
const response = await client.get("http://localhost:3003/users", {
|
||||
timeout: 30,
|
||||
// the expected response type
|
||||
responseType: ResponseType.JSON,
|
||||
});
|
||||
```
|
||||
|
||||
**Type parameters**
|
||||
|
||||
- `T`
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :--------- | :----------------------------------------- |
|
||||
| `url` | `string` |
|
||||
| `options?` | [`RequestOptions`](http.md#requestoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Response`](http.md#response)<`T`\>\>
|
||||
|
||||
##### `patch`
|
||||
|
||||
> **patch**<`T`\>(`url`: `string`, `options?`: [`RequestOptions`](http.md#requestoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Response`](http.md#response)<`T`\>\>
|
||||
|
||||
Makes a PATCH request.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { getClient, Body } from "@tauri-apps/api/http";
|
||||
const client = await getClient();
|
||||
const response = await client.patch("http://localhost:3003/users/1", {
|
||||
body: Body.json({ email: "contact@tauri.app" }),
|
||||
});
|
||||
```
|
||||
|
||||
**Type parameters**
|
||||
|
||||
- `T`
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :--------- | :----------------------------------------- |
|
||||
| `url` | `string` |
|
||||
| `options?` | [`RequestOptions`](http.md#requestoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Response`](http.md#response)<`T`\>\>
|
||||
|
||||
##### `post`
|
||||
|
||||
> **post**<`T`\>(`url`: `string`, `body?`: [`Body`](http.md#body), `options?`: [`RequestOptions`](http.md#requestoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Response`](http.md#response)<`T`\>\>
|
||||
|
||||
Makes a POST request.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { getClient, Body, ResponseType } from "@tauri-apps/api/http";
|
||||
const client = await getClient();
|
||||
const response = await client.post("http://localhost:3003/users", {
|
||||
body: Body.json({
|
||||
name: "tauri",
|
||||
password: "awesome",
|
||||
}),
|
||||
// in this case the server returns a simple string
|
||||
responseType: ResponseType.Text,
|
||||
});
|
||||
```
|
||||
|
||||
**Type parameters**
|
||||
|
||||
- `T`
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :--------- | :----------------------------------------- |
|
||||
| `url` | `string` |
|
||||
| `body?` | [`Body`](http.md#body) |
|
||||
| `options?` | [`RequestOptions`](http.md#requestoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Response`](http.md#response)<`T`\>\>
|
||||
|
||||
##### `put`
|
||||
|
||||
> **put**<`T`\>(`url`: `string`, `body?`: [`Body`](http.md#body), `options?`: [`RequestOptions`](http.md#requestoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Response`](http.md#response)<`T`\>\>
|
||||
|
||||
Makes a PUT request.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { getClient, Body } from "@tauri-apps/api/http";
|
||||
const client = await getClient();
|
||||
const response = await client.put("http://localhost:3003/users/1", {
|
||||
body: Body.form({
|
||||
file: {
|
||||
file: "/home/tauri/avatar.png",
|
||||
mime: "image/png",
|
||||
fileName: "avatar.png",
|
||||
},
|
||||
}),
|
||||
});
|
||||
```
|
||||
|
||||
**Type parameters**
|
||||
|
||||
- `T`
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :--------- | :----------------------------------------- |
|
||||
| `url` | `string` |
|
||||
| `body?` | [`Body`](http.md#body) |
|
||||
| `options?` | [`RequestOptions`](http.md#requestoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Response`](http.md#response)<`T`\>\>
|
||||
|
||||
##### `request`
|
||||
|
||||
> **request**<`T`\>(`options`: [`HttpOptions`](http.md#httpoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Response`](http.md#response)<`T`\>\>
|
||||
|
||||
Makes an HTTP request.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { getClient } from "@tauri-apps/api/http";
|
||||
const client = await getClient();
|
||||
const response = await client.request({
|
||||
method: "GET",
|
||||
url: "http://localhost:3003/users",
|
||||
});
|
||||
```
|
||||
|
||||
**Type parameters**
|
||||
|
||||
- `T`
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :-------- | :----------------------------------- |
|
||||
| `options` | [`HttpOptions`](http.md#httpoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Response`](http.md#response)<`T`\>\>
|
||||
|
||||
### `Response<T>`
|
||||
|
||||
Response object.
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Type parameters**
|
||||
|
||||
- `T`
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `data`
|
||||
|
||||
> **data**: `T`
|
||||
|
||||
The response data.
|
||||
|
||||
**Defined in:** [http.ts:286](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L286)
|
||||
|
||||
##### `headers`
|
||||
|
||||
> **headers**: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, `string`\>
|
||||
|
||||
The response headers.
|
||||
|
||||
**Defined in:** [http.ts:282](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L282)
|
||||
|
||||
##### `ok`
|
||||
|
||||
> **ok**: `boolean`
|
||||
|
||||
A boolean indicating whether the response was successful (status in the range 200–299) or not.
|
||||
|
||||
**Defined in:** [http.ts:280](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L280)
|
||||
|
||||
##### `rawHeaders`
|
||||
|
||||
> **rawHeaders**: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, `string`[]\>
|
||||
|
||||
The response raw headers.
|
||||
|
||||
**Defined in:** [http.ts:284](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L284)
|
||||
|
||||
##### `status`
|
||||
|
||||
> **status**: `number`
|
||||
|
||||
The response status code.
|
||||
|
||||
**Defined in:** [http.ts:278](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L278)
|
||||
|
||||
##### `url`
|
||||
|
||||
> **url**: `string`
|
||||
|
||||
The request URL.
|
||||
|
||||
**Defined in:** [http.ts:276](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L276)
|
||||
|
||||
## Interfaces
|
||||
|
||||
### `ClientOptions`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `connectTimeout`
|
||||
|
||||
> `Optional` **connectTimeout**: `number` \| [`Duration`](http.md#duration)
|
||||
|
||||
**Defined in:** [http.ts:65](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L65)
|
||||
|
||||
##### `maxRedirections`
|
||||
|
||||
> `Optional` **maxRedirections**: `number`
|
||||
|
||||
Defines the maximum number of redirects the client should follow.
|
||||
If set to 0, no redirects will be followed.
|
||||
|
||||
**Defined in:** [http.ts:64](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L64)
|
||||
|
||||
### `Duration`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `nanos`
|
||||
|
||||
> **nanos**: `number`
|
||||
|
||||
**Defined in:** [http.ts:53](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L53)
|
||||
|
||||
##### `secs`
|
||||
|
||||
> **secs**: `number`
|
||||
|
||||
**Defined in:** [http.ts:52](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L52)
|
||||
|
||||
### `FilePart<T>`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Type parameters**
|
||||
|
||||
- `T`
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `file`
|
||||
|
||||
> **file**: `string` \| `T`
|
||||
|
||||
**Defined in:** [http.ts:81](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L81)
|
||||
|
||||
##### `fileName`
|
||||
|
||||
> `Optional` **fileName**: `string`
|
||||
|
||||
**Defined in:** [http.ts:83](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L83)
|
||||
|
||||
##### `mime`
|
||||
|
||||
> `Optional` **mime**: `string`
|
||||
|
||||
**Defined in:** [http.ts:82](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L82)
|
||||
|
||||
### `HttpOptions`
|
||||
|
||||
Options object sent to the backend.
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `body`
|
||||
|
||||
> `Optional` **body**: [`Body`](http.md#body)
|
||||
|
||||
**Defined in:** [http.ts:250](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L250)
|
||||
|
||||
##### `headers`
|
||||
|
||||
> `Optional` **headers**: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, `any`\>
|
||||
|
||||
**Defined in:** [http.ts:248](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L248)
|
||||
|
||||
##### `method`
|
||||
|
||||
> **method**: [`HttpVerb`](http.md#httpverb)
|
||||
|
||||
**Defined in:** [http.ts:246](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L246)
|
||||
|
||||
##### `query`
|
||||
|
||||
> `Optional` **query**: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, `any`\>
|
||||
|
||||
**Defined in:** [http.ts:249](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L249)
|
||||
|
||||
##### `responseType`
|
||||
|
||||
> `Optional` **responseType**: [`ResponseType`](http.md#responsetype)
|
||||
|
||||
**Defined in:** [http.ts:252](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L252)
|
||||
|
||||
##### `timeout`
|
||||
|
||||
> `Optional` **timeout**: `number` \| [`Duration`](http.md#duration)
|
||||
|
||||
**Defined in:** [http.ts:251](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L251)
|
||||
|
||||
##### `url`
|
||||
|
||||
> **url**: `string`
|
||||
|
||||
**Defined in:** [http.ts:247](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L247)
|
||||
|
||||
## Type Aliases
|
||||
|
||||
### `FetchOptions`
|
||||
|
||||
> **FetchOptions**: [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)<[`HttpOptions`](http.md#httpoptions), `"url"`\>
|
||||
|
||||
Options for the `fetch` API.
|
||||
|
||||
**Defined in:** [http.ts:258](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L258)
|
||||
|
||||
### `HttpVerb`
|
||||
|
||||
> **HttpVerb**: `"GET"` \| `"POST"` \| `"PUT"` \| `"DELETE"` \| `"PATCH"` \| `"HEAD"` \| `"OPTIONS"` \| `"CONNECT"` \| `"TRACE"`
|
||||
|
||||
The request HTTP verb.
|
||||
|
||||
**Defined in:** [http.ts:229](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L229)
|
||||
|
||||
### `Part`
|
||||
|
||||
> **Part**: `string` \| [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) \| [`FilePart`](http.md#filepart)<[`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)\>
|
||||
|
||||
**Defined in:** [http.ts:86](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L86)
|
||||
|
||||
### `RequestOptions`
|
||||
|
||||
> **RequestOptions**: [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)<[`HttpOptions`](http.md#httpoptions), `"method"` \| `"url"`\>
|
||||
|
||||
Request options.
|
||||
|
||||
**Defined in:** [http.ts:256](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/http.ts#L256)
|
||||
|
||||
## Functions
|
||||
|
||||
### `fetch`
|
||||
|
||||
> **fetch**<`T`\>(`url`: `string`, `options?`: [`FetchOptions`](http.md#fetchoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Response`](http.md#response)<`T`\>\>
|
||||
|
||||
Perform an HTTP request using the default client.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { fetch } from "@tauri-apps/api/http";
|
||||
const response = await fetch("http://localhost:3003/users/2", {
|
||||
method: "GET",
|
||||
timeout: 30,
|
||||
});
|
||||
```
|
||||
|
||||
**Type parameters**
|
||||
|
||||
- `T`
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :--------- | :------------------------------------- |
|
||||
| `url` | `string` |
|
||||
| `options?` | [`FetchOptions`](http.md#fetchoptions) |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Response`](http.md#response)<`T`\>\>
|
||||
|
||||
### `getClient`
|
||||
|
||||
> **getClient**(`options?`: [`ClientOptions`](http.md#clientoptions)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Client`](http.md#client)\>
|
||||
|
||||
Creates a new client using the specified options.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { getClient } from "@tauri-apps/api/http";
|
||||
const client = await getClient();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--------- | :--------------------------------------- | :-------------------- |
|
||||
| `options?` | [`ClientOptions`](http.md#clientoptions) | Client configuration. |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Client`](http.md#client)\>
|
||||
|
||||
A promise resolving to the client instance.
|
||||
@@ -1,162 +0,0 @@
|
||||
---
|
||||
title: mocks
|
||||
---
|
||||
|
||||
# mocks
|
||||
|
||||
## Functions
|
||||
|
||||
### `clearMocks`
|
||||
|
||||
> **clearMocks**(): `void`
|
||||
|
||||
Clears mocked functions/data injected by the other functions in this module.
|
||||
When using a test runner that doesn't provide a fresh window object for each test, calling this function will reset tauri specific properties.
|
||||
|
||||
# Example
|
||||
|
||||
```js
|
||||
import { mockWindows, clearMocks } from "@tauri-apps/api/mocks";
|
||||
|
||||
afterEach(() => {
|
||||
clearMocks();
|
||||
});
|
||||
|
||||
test("mocked windows", () => {
|
||||
mockWindows("main", "second", "third");
|
||||
|
||||
expect(window).toHaveProperty("__TAURI_METADATA__");
|
||||
});
|
||||
|
||||
test("no mocked windows", () => {
|
||||
expect(window).not.toHaveProperty("__TAURI_METADATA__");
|
||||
});
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **`void`
|
||||
|
||||
### `mockIPC`
|
||||
|
||||
> **mockIPC**(`cb`: `fn`): `void`
|
||||
|
||||
Intercepts all IPC requests with the given mock handler.
|
||||
|
||||
This function can be used when testing tauri frontend applications or when running the frontend in a Node.js context during static site generation.
|
||||
|
||||
# Examples
|
||||
|
||||
Testing setup using vitest:
|
||||
|
||||
```js
|
||||
import { mockIPC, clearMocks } from "@tauri-apps/api/mocks"
|
||||
import { invoke } from "@tauri-apps/api/tauri"
|
||||
|
||||
afterEach(() => {
|
||||
clearMocks()
|
||||
})
|
||||
|
||||
test("mocked command", () => {
|
||||
mockIPC((cmd, args) => {
|
||||
switch (cmd) {
|
||||
case "add":
|
||||
return (args.a as number) + (args.b as number);
|
||||
default:
|
||||
break;
|
||||
}
|
||||
});
|
||||
|
||||
expect(invoke('add', { a: 12, b: 15 })).resolves.toBe(27);
|
||||
})
|
||||
```
|
||||
|
||||
The callback function can also return a Promise:
|
||||
|
||||
```js
|
||||
import { mockIPC, clearMocks } from "@tauri-apps/api/mocks";
|
||||
import { invoke } from "@tauri-apps/api/tauri";
|
||||
|
||||
afterEach(() => {
|
||||
clearMocks();
|
||||
});
|
||||
|
||||
test("mocked command", () => {
|
||||
mockIPC((cmd, args) => {
|
||||
if (cmd === "get_data") {
|
||||
return fetch("https://example.com/data.json").then((response) =>
|
||||
response.json()
|
||||
);
|
||||
}
|
||||
});
|
||||
|
||||
expect(invoke("get_data")).resolves.toBe({ foo: "bar" });
|
||||
});
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :--- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `cb` | (`cmd`: `string`, `args`: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, `unknown`\>) => `any` |
|
||||
|
||||
**Returns: **`void`
|
||||
|
||||
### `mockWindows`
|
||||
|
||||
> **mockWindows**(`current`: `string`, ...`additionalWindows`: `string`[]): `void`
|
||||
|
||||
Mocks one or many window labels.
|
||||
In non-tauri context it is required to call this function _before_ using the `@tauri-apps/api/window` module.
|
||||
|
||||
This function only mocks the _presence_ of windows,
|
||||
window properties (e.g. width and height) can be mocked like regular IPC calls using the `mockIPC` function.
|
||||
|
||||
# Examples
|
||||
|
||||
```js
|
||||
import { mockWindows } from "@tauri-apps/api/mocks";
|
||||
import { getCurrent } from "@tauri-apps/api/window";
|
||||
|
||||
mockWindows("main", "second", "third");
|
||||
|
||||
const win = getCurrent();
|
||||
|
||||
win.label; // "main"
|
||||
```
|
||||
|
||||
```js
|
||||
import { mockWindows } from "@tauri-apps/api/mocks";
|
||||
|
||||
mockWindows("main", "second", "third");
|
||||
|
||||
mockIPC((cmd, args) => {
|
||||
if (cmd === "tauri") {
|
||||
if (
|
||||
args?.__tauriModule === "Window" &&
|
||||
args?.message?.cmd === "manage" &&
|
||||
args?.message?.data?.cmd?.type === "close"
|
||||
) {
|
||||
console.log("closing window!");
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
const { getCurrent } = await import("@tauri-apps/api/window");
|
||||
|
||||
const win = getCurrent();
|
||||
await win.close(); // this will cause the mocked IPC handler to log to the console.
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--------------------- | :--------- | :----------------------------------------------------- |
|
||||
| `current` | `string` | Label of window this JavaScript context is running in. |
|
||||
| `...additionalWindows` | `string`[] | Label of additional windows the app has. |
|
||||
|
||||
**Returns: **`void`
|
||||
@@ -1,150 +0,0 @@
|
||||
---
|
||||
title: notification
|
||||
---
|
||||
|
||||
# notification
|
||||
|
||||
Send toast notifications (brief auto-expiring OS window element) to your user.
|
||||
Can also be used with the Notification Web API.
|
||||
|
||||
This package is also accessible with `window.__TAURI__.notification` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
|
||||
|
||||
The APIs must be added to [`tauri.allowlist.notification`](https://tauri.app/v1/api/config/#allowlistconfig.notification) in `tauri.conf.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"notification": {
|
||||
"all": true // enable all notification APIs
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
It is recommended to allowlist only the APIs you use for optimal bundle size and security.
|
||||
|
||||
## Interfaces
|
||||
|
||||
### `Options`
|
||||
|
||||
Options to send a notification.
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `body`
|
||||
|
||||
> `Optional` **body**: `string`
|
||||
|
||||
Optional notification body.
|
||||
|
||||
**Defined in:** [notification.ts:38](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/notification.ts#L38)
|
||||
|
||||
##### `icon`
|
||||
|
||||
> `Optional` **icon**: `string`
|
||||
|
||||
Optional notification icon.
|
||||
|
||||
**Defined in:** [notification.ts:40](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/notification.ts#L40)
|
||||
|
||||
##### `title`
|
||||
|
||||
> **title**: `string`
|
||||
|
||||
Notification title.
|
||||
|
||||
**Defined in:** [notification.ts:36](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/notification.ts#L36)
|
||||
|
||||
## Type Aliases
|
||||
|
||||
### `Permission`
|
||||
|
||||
> **Permission**: `"granted"` \| `"denied"` \| `"default"`
|
||||
|
||||
Possible permission values.
|
||||
|
||||
**Defined in:** [notification.ts:44](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/notification.ts#L44)
|
||||
|
||||
## Functions
|
||||
|
||||
### `isPermissionGranted`
|
||||
|
||||
> **isPermissionGranted**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`boolean`\>
|
||||
|
||||
Checks if the permission to send notifications is granted.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { isPermissionGranted } from "@tauri-apps/api/notification";
|
||||
const permissionGranted = await isPermissionGranted();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`boolean`\>
|
||||
|
||||
### `requestPermission`
|
||||
|
||||
> **requestPermission**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Permission`](notification.md#permission)\>
|
||||
|
||||
Requests the permission to send notifications.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import {
|
||||
isPermissionGranted,
|
||||
requestPermission,
|
||||
} from "@tauri-apps/api/notification";
|
||||
let permissionGranted = await isPermissionGranted();
|
||||
if (!permissionGranted) {
|
||||
const permission = await requestPermission();
|
||||
permissionGranted = permission === "granted";
|
||||
}
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Permission`](notification.md#permission)\>
|
||||
|
||||
A promise resolving to whether the user granted the permission or not.
|
||||
|
||||
### `sendNotification`
|
||||
|
||||
> **sendNotification**(`options`: `string` \| [`Options`](notification.md#options)): `void`
|
||||
|
||||
Sends a notification to the user.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import {
|
||||
isPermissionGranted,
|
||||
requestPermission,
|
||||
sendNotification,
|
||||
} from "@tauri-apps/api/notification";
|
||||
let permissionGranted = await isPermissionGranted();
|
||||
if (!permissionGranted) {
|
||||
const permission = await requestPermission();
|
||||
permissionGranted = permission === "granted";
|
||||
}
|
||||
if (permissionGranted) {
|
||||
sendNotification("Tauri is awesome!");
|
||||
sendNotification({ title: "TAURI", body: "Tauri is awesome!" });
|
||||
}
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :-------- | :----------------------------------------------- |
|
||||
| `options` | `string` \| [`Options`](notification.md#options) |
|
||||
|
||||
**Returns: **`void`
|
||||
@@ -1,169 +0,0 @@
|
||||
---
|
||||
title: os
|
||||
---
|
||||
|
||||
# os
|
||||
|
||||
Provides operating system-related utility methods and properties.
|
||||
|
||||
This package is also accessible with `window.__TAURI__.os` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
|
||||
|
||||
The APIs must be added to [`tauri.allowlist.os`](https://tauri.app/v1/api/config/#allowlistconfig.os) in `tauri.conf.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"os": {
|
||||
"all": true // enable all Os APIs
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
It is recommended to allowlist only the APIs you use for optimal bundle size and security.
|
||||
|
||||
## Type Aliases
|
||||
|
||||
### `Arch`
|
||||
|
||||
> **Arch**: `"x86"` \| `"x86_64"` \| `"arm"` \| `"aarch64"` \| `"mips"` \| `"mips64"` \| `"powerpc"` \| `"powerpc64"` \| `"riscv64"` \| `"s390x"` \| `"sparc64"`
|
||||
|
||||
**Defined in:** [os.ts:43](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/os.ts#L43)
|
||||
|
||||
### `OsType`
|
||||
|
||||
> **OsType**: `"Linux"` \| `"Darwin"` \| `"Windows_NT"`
|
||||
|
||||
**Defined in:** [os.ts:41](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/os.ts#L41)
|
||||
|
||||
### `Platform`
|
||||
|
||||
> **Platform**: `"linux"` \| `"darwin"` \| `"ios"` \| `"freebsd"` \| `"dragonfly"` \| `"netbsd"` \| `"openbsd"` \| `"solaris"` \| `"android"` \| `"win32"`
|
||||
|
||||
**Defined in:** [os.ts:29](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/os.ts#L29)
|
||||
|
||||
## Variables
|
||||
|
||||
### `EOL`
|
||||
|
||||
> `Const` **EOL**: `"\n"` \| `"\r\n"`
|
||||
|
||||
The operating system-specific end-of-line marker.
|
||||
|
||||
- `\n` on POSIX
|
||||
- `\r\n` on Windows
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Defined in:** [os.ts:63](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/os.ts#L63)
|
||||
|
||||
## Functions
|
||||
|
||||
### `arch`
|
||||
|
||||
> **arch**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Arch`](os.md#arch)\>
|
||||
|
||||
Returns the operating system CPU architecture for which the tauri app was compiled.
|
||||
Possible values are `'x86'`, `'x86_64'`, `'arm'`, `'aarch64'`, `'mips'`, `'mips64'`, `'powerpc'`, `'powerpc64'`, `'riscv64'`, `'s390x'`, `'sparc64'`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { arch } from "@tauri-apps/api/os";
|
||||
const archName = await arch();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Arch`](os.md#arch)\>
|
||||
|
||||
### `locale`
|
||||
|
||||
> **locale**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string` \| `null`\>
|
||||
|
||||
Returns a String with a `BCP-47` language tag inside. If the locale couldn’t be obtained, `null` is returned instead.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { locale } from "@tauri-apps/api/os";
|
||||
const locale = await locale();
|
||||
if (locale) {
|
||||
// use the locale string here
|
||||
}
|
||||
```
|
||||
|
||||
**Since**: 1.4.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string` \| `null`\>
|
||||
|
||||
### `platform`
|
||||
|
||||
> **platform**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Platform`](os.md#platform)\>
|
||||
|
||||
Returns a string identifying the operating system platform.
|
||||
The value is set at compile time. Possible values are `'linux'`, `'darwin'`, `'ios'`, `'freebsd'`, `'dragonfly'`, `'netbsd'`, `'openbsd'`, `'solaris'`, `'android'`, `'win32'`
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { platform } from "@tauri-apps/api/os";
|
||||
const platformName = await platform();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Platform`](os.md#platform)\>
|
||||
|
||||
### `tempdir`
|
||||
|
||||
> **tempdir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the operating system's default directory for temporary files as a string.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { tempdir } from "@tauri-apps/api/os";
|
||||
const tempdirPath = await tempdir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `type`
|
||||
|
||||
> **type**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`OsType`](os.md#ostype)\>
|
||||
|
||||
Returns `'Linux'` on Linux, `'Darwin'` on macOS, and `'Windows_NT'` on Windows.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { type } from "@tauri-apps/api/os";
|
||||
const osType = await type();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`OsType`](os.md#ostype)\>
|
||||
|
||||
### `version`
|
||||
|
||||
> **version**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns a string identifying the kernel version.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { version } from "@tauri-apps/api/os";
|
||||
const osVersion = await version();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
@@ -1,777 +0,0 @@
|
||||
---
|
||||
title: path
|
||||
---
|
||||
|
||||
# path
|
||||
|
||||
The path module provides utilities for working with file and directory paths.
|
||||
|
||||
This package is also accessible with `window.__TAURI__.path` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
|
||||
|
||||
The APIs must be added to [`tauri.allowlist.path`](https://tauri.app/v1/api/config/#allowlistconfig.path) in `tauri.conf.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"path": {
|
||||
"all": true // enable all Path APIs
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
It is recommended to allowlist only the APIs you use for optimal bundle size and security.
|
||||
|
||||
## References
|
||||
|
||||
### `BaseDirectory`
|
||||
|
||||
Re-exports [BaseDirectory](fs.md#basedirectory)
|
||||
|
||||
## Variables
|
||||
|
||||
### `delimiter`
|
||||
|
||||
> `Const` **delimiter**: `";"` \| `":"`
|
||||
|
||||
Provides the platform-specific path segment delimiter:
|
||||
|
||||
- `;` on Windows
|
||||
- `:` on POSIX
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Defined in:** [path.ts:660](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/path.ts#L660)
|
||||
|
||||
### `sep`
|
||||
|
||||
> `Const` **sep**: `"\\"` \| `"/"`
|
||||
|
||||
Provides the platform-specific path segment separator:
|
||||
|
||||
- `\` on Windows
|
||||
- `/` on POSIX
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Defined in:** [path.ts:651](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/path.ts#L651)
|
||||
|
||||
## Functions
|
||||
|
||||
### `appCacheDir`
|
||||
|
||||
> **appCacheDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the suggested directory for your app's cache files.
|
||||
Resolves to `${cacheDir}/${bundleIdentifier}`, where `bundleIdentifier` is the value [`tauri.bundle.identifier`](https://tauri.app/v1/api/config/#bundleconfig.identifier) is configured in `tauri.conf.json`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { appCacheDir } from "@tauri-apps/api/path";
|
||||
const appCacheDirPath = await appCacheDir();
|
||||
```
|
||||
|
||||
**Since**: 1.2.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `appConfigDir`
|
||||
|
||||
> **appConfigDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the suggested directory for your app's config files.
|
||||
Resolves to `${configDir}/${bundleIdentifier}`, where `bundleIdentifier` is the value [`tauri.bundle.identifier`](https://tauri.app/v1/api/config/#bundleconfig.identifier) is configured in `tauri.conf.json`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { appConfigDir } from "@tauri-apps/api/path";
|
||||
const appConfigDirPath = await appConfigDir();
|
||||
```
|
||||
|
||||
**Since**: 1.2.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `appDataDir`
|
||||
|
||||
> **appDataDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the suggested directory for your app's data files.
|
||||
Resolves to `${dataDir}/${bundleIdentifier}`, where `bundleIdentifier` is the value [`tauri.bundle.identifier`](https://tauri.app/v1/api/config/#bundleconfig.identifier) is configured in `tauri.conf.json`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { appDataDir } from "@tauri-apps/api/path";
|
||||
const appDataDirPath = await appDataDir();
|
||||
```
|
||||
|
||||
**Since**: 1.2.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `appDir`
|
||||
|
||||
> **appDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the suggested directory for your app config files.
|
||||
|
||||
**Deprecated**
|
||||
|
||||
since 1.2.0: Will be removed in 2.0.0. Use [appConfigDir](path.md#appconfigdir) or [appDataDir](path.md#appdatadir) instead.
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `appLocalDataDir`
|
||||
|
||||
> **appLocalDataDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the suggested directory for your app's local data files.
|
||||
Resolves to `${localDataDir}/${bundleIdentifier}`, where `bundleIdentifier` is the value [`tauri.bundle.identifier`](https://tauri.app/v1/api/config/#bundleconfig.identifier) is configured in `tauri.conf.json`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { appLocalDataDir } from "@tauri-apps/api/path";
|
||||
const appLocalDataDirPath = await appLocalDataDir();
|
||||
```
|
||||
|
||||
**Since**: 1.2.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `appLogDir`
|
||||
|
||||
> **appLogDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the suggested directory for your app's log files.
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux:** Resolves to `${configDir}/${bundleIdentifier}/logs`.
|
||||
- **macOS:** Resolves to `${homeDir}/Library/Logs/{bundleIdentifier}`
|
||||
- **Windows:** Resolves to `${configDir}/${bundleIdentifier}/logs`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { appLogDir } from "@tauri-apps/api/path";
|
||||
const appLogDirPath = await appLogDir();
|
||||
```
|
||||
|
||||
**Since**: 1.2.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `audioDir`
|
||||
|
||||
> **audioDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the user's audio directory.
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux:** Resolves to [`xdg-user-dirs`](https://www.freedesktop.org/wiki/Software/xdg-user-dirs/)' `XDG_MUSIC_DIR`.
|
||||
- **macOS:** Resolves to `$HOME/Music`.
|
||||
- **Windows:** Resolves to `{FOLDERID_Music}`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { audioDir } from "@tauri-apps/api/path";
|
||||
const audioDirPath = await audioDir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `basename`
|
||||
|
||||
> **basename**(`path`: `string`, `ext?`: `string`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the last portion of a `path`. Trailing directory separators are ignored.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { basename, resolveResource } from "@tauri-apps/api/path";
|
||||
const resourcePath = await resolveResource("app.conf");
|
||||
const base = await basename(resourcePath);
|
||||
assert(base === "app.conf");
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :----- | :------- | :--------------------------------------------------------------- |
|
||||
| `path` | `string` | - |
|
||||
| `ext?` | `string` | An optional file extension to be removed from the returned path. |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `cacheDir`
|
||||
|
||||
> **cacheDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the user's cache directory.
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux:** Resolves to `$XDG_CACHE_HOME` or `$HOME/.cache`.
|
||||
- **macOS:** Resolves to `$HOME/Library/Caches`.
|
||||
- **Windows:** Resolves to `{FOLDERID_LocalAppData}`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { cacheDir } from "@tauri-apps/api/path";
|
||||
const cacheDirPath = await cacheDir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `configDir`
|
||||
|
||||
> **configDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the user's config directory.
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux:** Resolves to `$XDG_CONFIG_HOME` or `$HOME/.config`.
|
||||
- **macOS:** Resolves to `$HOME/Library/Application Support`.
|
||||
- **Windows:** Resolves to `{FOLDERID_RoamingAppData}`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { configDir } from "@tauri-apps/api/path";
|
||||
const configDirPath = await configDir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `dataDir`
|
||||
|
||||
> **dataDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the user's data directory.
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux:** Resolves to `$XDG_DATA_HOME` or `$HOME/.local/share`.
|
||||
- **macOS:** Resolves to `$HOME/Library/Application Support`.
|
||||
- **Windows:** Resolves to `{FOLDERID_RoamingAppData}`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { dataDir } from "@tauri-apps/api/path";
|
||||
const dataDirPath = await dataDir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `desktopDir`
|
||||
|
||||
> **desktopDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the user's desktop directory.
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux:** Resolves to [`xdg-user-dirs`](https://www.freedesktop.org/wiki/Software/xdg-user-dirs/)' `XDG_DESKTOP_DIR`.
|
||||
- **macOS:** Resolves to `$HOME/Desktop`.
|
||||
- **Windows:** Resolves to `{FOLDERID_Desktop}`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { desktopDir } from "@tauri-apps/api/path";
|
||||
const desktopPath = await desktopDir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `dirname`
|
||||
|
||||
> **dirname**(`path`: `string`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the directory name of a `path`. Trailing directory separators are ignored.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { dirname, appDataDir } from "@tauri-apps/api/path";
|
||||
const appDataDirPath = await appDataDir();
|
||||
const dir = await dirname(appDataDirPath);
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :----- | :------- |
|
||||
| `path` | `string` |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `documentDir`
|
||||
|
||||
> **documentDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the user's document directory.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { documentDir } from "@tauri-apps/api/path";
|
||||
const documentDirPath = await documentDir();
|
||||
```
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux:** Resolves to [`xdg-user-dirs`](https://www.freedesktop.org/wiki/Software/xdg-user-dirs/)' `XDG_DOCUMENTS_DIR`.
|
||||
- **macOS:** Resolves to `$HOME/Documents`.
|
||||
- **Windows:** Resolves to `{FOLDERID_Documents}`.
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `downloadDir`
|
||||
|
||||
> **downloadDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the user's download directory.
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux**: Resolves to [`xdg-user-dirs`](https://www.freedesktop.org/wiki/Software/xdg-user-dirs/)' `XDG_DOWNLOAD_DIR`.
|
||||
- **macOS**: Resolves to `$HOME/Downloads`.
|
||||
- **Windows**: Resolves to `{FOLDERID_Downloads}`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { downloadDir } from "@tauri-apps/api/path";
|
||||
const downloadDirPath = await downloadDir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `executableDir`
|
||||
|
||||
> **executableDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the user's executable directory.
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux:** Resolves to `$XDG_BIN_HOME/../bin` or `$XDG_DATA_HOME/../bin` or `$HOME/.local/bin`.
|
||||
- **macOS:** Not supported.
|
||||
- **Windows:** Not supported.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { executableDir } from "@tauri-apps/api/path";
|
||||
const executableDirPath = await executableDir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `extname`
|
||||
|
||||
> **extname**(`path`: `string`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the extension of the `path`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { extname, resolveResource } from "@tauri-apps/api/path";
|
||||
const resourcePath = await resolveResource("app.conf");
|
||||
const ext = await extname(resourcePath);
|
||||
assert(ext === "conf");
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :----- | :------- |
|
||||
| `path` | `string` |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `fontDir`
|
||||
|
||||
> **fontDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the user's font directory.
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux:** Resolves to `$XDG_DATA_HOME/fonts` or `$HOME/.local/share/fonts`.
|
||||
- **macOS:** Resolves to `$HOME/Library/Fonts`.
|
||||
- **Windows:** Not supported.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { fontDir } from "@tauri-apps/api/path";
|
||||
const fontDirPath = await fontDir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `homeDir`
|
||||
|
||||
> **homeDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the user's home directory.
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux:** Resolves to `$HOME`.
|
||||
- **macOS:** Resolves to `$HOME`.
|
||||
- **Windows:** Resolves to `{FOLDERID_Profile}`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { homeDir } from "@tauri-apps/api/path";
|
||||
const homeDirPath = await homeDir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `isAbsolute`
|
||||
|
||||
> **isAbsolute**(`path`: `string`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`boolean`\>
|
||||
|
||||
Returns whether the path is absolute or not.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { isAbsolute } from "@tauri-apps/api/path";
|
||||
assert(await isAbsolute("/home/tauri"));
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :----- | :------- |
|
||||
| `path` | `string` |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`boolean`\>
|
||||
|
||||
### `join`
|
||||
|
||||
> **join**(...`paths`: `string`[]): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Joins all given `path` segments together using the platform-specific separator as a delimiter, then normalizes the resulting path.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { join, appDataDir } from "@tauri-apps/api/path";
|
||||
const appDataDirPath = await appDataDir();
|
||||
const path = await join(appDataDirPath, "users", "tauri", "avatar.png");
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :--------- | :--------- |
|
||||
| `...paths` | `string`[] |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `localDataDir`
|
||||
|
||||
> **localDataDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the user's local data directory.
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux:** Resolves to `$XDG_DATA_HOME` or `$HOME/.local/share`.
|
||||
- **macOS:** Resolves to `$HOME/Library/Application Support`.
|
||||
- **Windows:** Resolves to `{FOLDERID_LocalAppData}`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { localDataDir } from "@tauri-apps/api/path";
|
||||
const localDataDirPath = await localDataDir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `logDir`
|
||||
|
||||
> **logDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the suggested log directory.
|
||||
|
||||
**Deprecated**
|
||||
|
||||
since 1.2.0: Will be removed in 2.0.0. Use [appLogDir](path.md#applogdir) instead.
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `normalize`
|
||||
|
||||
> **normalize**(`path`: `string`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Normalizes the given `path`, resolving `'..'` and `'.'` segments and resolve symbolic links.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { normalize, appDataDir } from "@tauri-apps/api/path";
|
||||
const appDataDirPath = await appDataDir();
|
||||
const path = await normalize(
|
||||
appDataDirPath,
|
||||
"..",
|
||||
"users",
|
||||
"tauri",
|
||||
"avatar.png"
|
||||
);
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :----- | :------- |
|
||||
| `path` | `string` |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `pictureDir`
|
||||
|
||||
> **pictureDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the user's picture directory.
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux:** Resolves to [`xdg-user-dirs`](https://www.freedesktop.org/wiki/Software/xdg-user-dirs/)' `XDG_PICTURES_DIR`.
|
||||
- **macOS:** Resolves to `$HOME/Pictures`.
|
||||
- **Windows:** Resolves to `{FOLDERID_Pictures}`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { pictureDir } from "@tauri-apps/api/path";
|
||||
const pictureDirPath = await pictureDir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `publicDir`
|
||||
|
||||
> **publicDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the user's public directory.
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux:** Resolves to [`xdg-user-dirs`](https://www.freedesktop.org/wiki/Software/xdg-user-dirs/)' `XDG_PUBLICSHARE_DIR`.
|
||||
- **macOS:** Resolves to `$HOME/Public`.
|
||||
- **Windows:** Resolves to `{FOLDERID_Public}`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { publicDir } from "@tauri-apps/api/path";
|
||||
const publicDirPath = await publicDir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `resolve`
|
||||
|
||||
> **resolve**(...`paths`: `string`[]): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Resolves a sequence of `paths` or `path` segments into an absolute path.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { resolve, appDataDir } from "@tauri-apps/api/path";
|
||||
const appDataDirPath = await appDataDir();
|
||||
const path = await resolve(
|
||||
appDataDirPath,
|
||||
"..",
|
||||
"users",
|
||||
"tauri",
|
||||
"avatar.png"
|
||||
);
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :--------- | :--------- |
|
||||
| `...paths` | `string`[] |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `resolveResource`
|
||||
|
||||
> **resolveResource**(`resourcePath`: `string`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Resolve the path to a resource file.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { resolveResource } from "@tauri-apps/api/path";
|
||||
const resourcePath = await resolveResource("script.sh");
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `resourcePath` | `string` | The path to the resource.<br/>Must follow the same syntax as defined in `tauri.conf.json > tauri > bundle > resources`, i.e. keeping subfolders and parent dir components (`../`). |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
The full path to the resource.
|
||||
|
||||
### `resourceDir`
|
||||
|
||||
> **resourceDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the application's resource directory.
|
||||
To resolve a resource path, see the [[resolveResource | `resolveResource API`]].
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { resourceDir } from "@tauri-apps/api/path";
|
||||
const resourceDirPath = await resourceDir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `runtimeDir`
|
||||
|
||||
> **runtimeDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the user's runtime directory.
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux:** Resolves to `$XDG_RUNTIME_DIR`.
|
||||
- **macOS:** Not supported.
|
||||
- **Windows:** Not supported.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { runtimeDir } from "@tauri-apps/api/path";
|
||||
const runtimeDirPath = await runtimeDir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `templateDir`
|
||||
|
||||
> **templateDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the user's template directory.
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux:** Resolves to [`xdg-user-dirs`](https://www.freedesktop.org/wiki/Software/xdg-user-dirs/)' `XDG_TEMPLATES_DIR`.
|
||||
- **macOS:** Not supported.
|
||||
- **Windows:** Resolves to `{FOLDERID_Templates}`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { templateDir } from "@tauri-apps/api/path";
|
||||
const templateDirPath = await templateDir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
### `videoDir`
|
||||
|
||||
> **videoDir**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
|
||||
Returns the path to the user's video directory.
|
||||
|
||||
#### Platform-specific
|
||||
|
||||
- **Linux:** Resolves to [`xdg-user-dirs`](https://www.freedesktop.org/wiki/Software/xdg-user-dirs/)' `XDG_VIDEOS_DIR`.
|
||||
- **macOS:** Resolves to `$HOME/Movies`.
|
||||
- **Windows:** Resolves to `{FOLDERID_Videos}`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { videoDir } from "@tauri-apps/api/path";
|
||||
const videoDirPath = await videoDir();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`string`\>
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
title: process
|
||||
---
|
||||
|
||||
# process
|
||||
|
||||
Perform operations on the current process.
|
||||
|
||||
This package is also accessible with `window.__TAURI__.process` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
|
||||
|
||||
## Functions
|
||||
|
||||
### `exit`
|
||||
|
||||
> **exit**(`exitCode?`: `number`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Exits immediately with the given `exitCode`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { exit } from "@tauri-apps/api/process";
|
||||
await exit(1);
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
| :--------- | :------- | :------------ | :-------------------- |
|
||||
| `exitCode` | `number` | `0` | The exit code to use. |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
A promise indicating the success or failure of the operation.
|
||||
|
||||
### `relaunch`
|
||||
|
||||
> **relaunch**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Exits the current instance of the app then relaunches it.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { relaunch } from "@tauri-apps/api/process";
|
||||
await relaunch();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
A promise indicating the success or failure of the operation.
|
||||
@@ -1,746 +0,0 @@
|
||||
---
|
||||
title: shell
|
||||
---
|
||||
|
||||
# shell
|
||||
|
||||
Access the system shell.
|
||||
Allows you to spawn child processes and manage files and URLs using their default application.
|
||||
|
||||
This package is also accessible with `window.__TAURI__.shell` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
|
||||
|
||||
The APIs must be added to [`tauri.allowlist.shell`](https://tauri.app/v1/api/config/#allowlistconfig.shell) in `tauri.conf.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"shell": {
|
||||
"all": true, // enable all shell APIs
|
||||
"execute": true, // enable process spawn APIs
|
||||
"sidecar": true, // enable spawning sidecars
|
||||
"open": true // enable opening files/URLs using the default program
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
It is recommended to allowlist only the APIs you use for optimal bundle size and security.
|
||||
|
||||
## Security
|
||||
|
||||
This API has a scope configuration that forces you to restrict the programs and arguments that can be used.
|
||||
|
||||
### Restricting access to the [`open`](shell.md#open) API
|
||||
|
||||
On the allowlist, `open: true` means that the [open](shell.md#open) API can be used with any URL,
|
||||
as the argument is validated with the `^((mailto:\w+)|(tel:\w+)|(https?://\w+)).+` regex.
|
||||
You can change that regex by changing the boolean value to a string, e.g. `open: ^https://github.com/`.
|
||||
|
||||
### Restricting access to the [`Command`](shell.md#command) APIs
|
||||
|
||||
The `shell` allowlist object has a `scope` field that defines an array of CLIs that can be used.
|
||||
Each CLI is a configuration object `{ name: string, cmd: string, sidecar?: bool, args?: boolean | Arg[] }`.
|
||||
|
||||
- `name`: the unique identifier of the command, passed to the [Command constructor](shell.md#constructor).
|
||||
If it's a sidecar, this must be the value defined on `tauri.conf.json > tauri > bundle > externalBin`.
|
||||
- `cmd`: the program that is executed on this configuration. If it's a sidecar, this value is ignored.
|
||||
- `sidecar`: whether the object configures a sidecar or a system program.
|
||||
- `args`: the arguments that can be passed to the program. By default no arguments are allowed.
|
||||
- `true` means that any argument list is allowed.
|
||||
- `false` means that no arguments are allowed.
|
||||
- otherwise an array can be configured. Each item is either a string representing the fixed argument value
|
||||
or a `{ validator: string }` that defines a regex validating the argument value.
|
||||
|
||||
#### Example scope configuration
|
||||
|
||||
CLI: `git commit -m "the commit message"`
|
||||
|
||||
Configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"scope": [
|
||||
{
|
||||
"name": "run-git-commit",
|
||||
"cmd": "git",
|
||||
"args": ["commit", "-m", { "validator": "\\S+" }]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Usage:
|
||||
|
||||
```typescript
|
||||
import { Command } from "@tauri-apps/api/shell";
|
||||
new Command("run-git-commit", ["commit", "-m", "the commit message"]);
|
||||
```
|
||||
|
||||
Trying to execute any API with a program not configured on the scope results in a promise rejection due to denied access.
|
||||
|
||||
## Classes
|
||||
|
||||
### `Child`
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
#### Constructors
|
||||
|
||||
##### `constructor`
|
||||
|
||||
> **new Child**(`pid`: `number`): [`Child`](shell.md#child)
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---- | :------- |
|
||||
| `pid` | `number` |
|
||||
|
||||
**Defined in:** [shell.ts:325](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/shell.ts#L325)
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `pid`
|
||||
|
||||
> **pid**: `number`
|
||||
|
||||
The child process `pid`.
|
||||
|
||||
**Defined in:** [shell.ts:323](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/shell.ts#L323)
|
||||
|
||||
#### Methods
|
||||
|
||||
##### `kill`
|
||||
|
||||
> **kill**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Kills the child process.
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
A promise indicating the success or failure of the operation.
|
||||
|
||||
##### `write`
|
||||
|
||||
> **write**(`data`: `string` \| [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Writes `data` to the `stdin`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { Command } from "@tauri-apps/api/shell";
|
||||
const command = new Command("node");
|
||||
const child = await command.spawn();
|
||||
await child.write("message");
|
||||
await child.write([0, 1, 2, 3, 4, 5]);
|
||||
```
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :----- | :---------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------- |
|
||||
| `data` | `string` \| [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) | The message to write, either a string or a byte array. |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
A promise indicating the success or failure of the operation.
|
||||
|
||||
### `Command`
|
||||
|
||||
The entry point for spawning child processes.
|
||||
It emits the `close` and `error` events.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { Command } from "@tauri-apps/api/shell";
|
||||
const command = new Command("node");
|
||||
command.on("close", (data) => {
|
||||
console.log(
|
||||
`command finished with code ${data.code} and signal ${data.signal}`
|
||||
);
|
||||
});
|
||||
command.on("error", (error) => console.error(`command error: "${error}"`));
|
||||
command.stdout.on("data", (line) => console.log(`command stdout: "${line}"`));
|
||||
command.stderr.on("data", (line) => console.log(`command stderr: "${line}"`));
|
||||
|
||||
const child = await command.spawn();
|
||||
console.log("pid:", child.pid);
|
||||
```
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Hierarchy**
|
||||
|
||||
- [`EventEmitter`](shell.md#eventemitter)<`"close"` \| `"error"`\>
|
||||
- **Command**
|
||||
|
||||
#### Constructors
|
||||
|
||||
##### `constructor`
|
||||
|
||||
> **new Command**(`program`: `string`, `args?`: `string` \| `string`[], `options?`: [`SpawnOptions`](shell.md#spawnoptions)): [`Command`](shell.md#command)
|
||||
|
||||
Creates a new `Command` instance.
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
| :--------- | :-------------------------------------- | :------------ | :--------------------------------------------------------------------------------------------------------------- |
|
||||
| `program` | `string` | `undefined` | The program name to execute.<br/>It must be configured on `tauri.conf.json > tauri > allowlist > shell > scope`. |
|
||||
| `args` | `string` \| `string`[] | `[]` | Program arguments. |
|
||||
| `options?` | [`SpawnOptions`](shell.md#spawnoptions) | `undefined` | Spawn options. |
|
||||
|
||||
**Overrides:** [EventEmitter](shell.md#eventemitter).[constructor](shell.md#constructor)
|
||||
|
||||
**Defined in:** [shell.ts:413](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/shell.ts#L413)
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `stderr`
|
||||
|
||||
> `Readonly` **stderr**: [`EventEmitter`](shell.md#eventemitter)<`"data"`\>
|
||||
|
||||
Event emitter for the `stderr`. Emits the `data` event.
|
||||
|
||||
**Defined in:** [shell.ts:403](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/shell.ts#L403)
|
||||
|
||||
##### `stdout`
|
||||
|
||||
> `Readonly` **stdout**: [`EventEmitter`](shell.md#eventemitter)<`"data"`\>
|
||||
|
||||
Event emitter for the `stdout`. Emits the `data` event.
|
||||
|
||||
**Defined in:** [shell.ts:401](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/shell.ts#L401)
|
||||
|
||||
#### Methods
|
||||
|
||||
##### `addListener`
|
||||
|
||||
> **addListener**(`eventName`: `"error"` \| `"close"`, `listener`: `fn`): [`Command`](shell.md#command)
|
||||
|
||||
Alias for `emitter.on(eventName, listener)`.
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---------- | :----------------------------- |
|
||||
| `eventName` | `"error"` \| `"close"` |
|
||||
| `listener` | (...`args`: `any`[]) => `void` |
|
||||
|
||||
**Returns: **[`Command`](shell.md#command)
|
||||
|
||||
##### `execute`
|
||||
|
||||
> **execute**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`ChildProcess`](shell.md#childprocess)\>
|
||||
|
||||
Executes the command as a child process, waiting for it to finish and collecting all of its output.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { Command } from "@tauri-apps/api/shell";
|
||||
const output = await new Command("echo", "message").execute();
|
||||
assert(output.code === 0);
|
||||
assert(output.signal === null);
|
||||
assert(output.stdout === "message");
|
||||
assert(output.stderr === "");
|
||||
```
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`ChildProcess`](shell.md#childprocess)\>
|
||||
|
||||
A promise resolving to the child process output.
|
||||
|
||||
##### `listenerCount`
|
||||
|
||||
> **listenerCount**(`eventName`: `"error"` \| `"close"`): `number`
|
||||
|
||||
Returns the number of listeners listening to the event named `eventName`.
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---------- | :--------------------- |
|
||||
| `eventName` | `"error"` \| `"close"` |
|
||||
|
||||
**Returns: **`number`
|
||||
|
||||
##### `off`
|
||||
|
||||
> **off**(`eventName`: `"error"` \| `"close"`, `listener`: `fn`): [`Command`](shell.md#command)
|
||||
|
||||
Removes the all specified listener from the listener array for the event eventName
|
||||
Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---------- | :----------------------------- |
|
||||
| `eventName` | `"error"` \| `"close"` |
|
||||
| `listener` | (...`args`: `any`[]) => `void` |
|
||||
|
||||
**Returns: **[`Command`](shell.md#command)
|
||||
|
||||
##### `on`
|
||||
|
||||
> **on**(`eventName`: `"error"` \| `"close"`, `listener`: `fn`): [`Command`](shell.md#command)
|
||||
|
||||
Adds the `listener` function to the end of the listeners array for the
|
||||
event named `eventName`. No checks are made to see if the `listener` has
|
||||
already been added. Multiple calls passing the same combination of `eventName`and `listener` will result in the `listener` being added, and called, multiple
|
||||
times.
|
||||
|
||||
Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---------- | :----------------------------- |
|
||||
| `eventName` | `"error"` \| `"close"` |
|
||||
| `listener` | (...`args`: `any`[]) => `void` |
|
||||
|
||||
**Returns: **[`Command`](shell.md#command)
|
||||
|
||||
##### `once`
|
||||
|
||||
> **once**(`eventName`: `"error"` \| `"close"`, `listener`: `fn`): [`Command`](shell.md#command)
|
||||
|
||||
Adds a **one-time**`listener` function for the event named `eventName`. The
|
||||
next time `eventName` is triggered, this listener is removed and then invoked.
|
||||
|
||||
Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---------- | :----------------------------- |
|
||||
| `eventName` | `"error"` \| `"close"` |
|
||||
| `listener` | (...`args`: `any`[]) => `void` |
|
||||
|
||||
**Returns: **[`Command`](shell.md#command)
|
||||
|
||||
##### `prependListener`
|
||||
|
||||
> **prependListener**(`eventName`: `"error"` \| `"close"`, `listener`: `fn`): [`Command`](shell.md#command)
|
||||
|
||||
Adds the `listener` function to the _beginning_ of the listeners array for the
|
||||
event named `eventName`. No checks are made to see if the `listener` has
|
||||
already been added. Multiple calls passing the same combination of `eventName`and `listener` will result in the `listener` being added, and called, multiple
|
||||
times.
|
||||
|
||||
Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---------- | :----------------------------- |
|
||||
| `eventName` | `"error"` \| `"close"` |
|
||||
| `listener` | (...`args`: `any`[]) => `void` |
|
||||
|
||||
**Returns: **[`Command`](shell.md#command)
|
||||
|
||||
##### `prependOnceListener`
|
||||
|
||||
> **prependOnceListener**(`eventName`: `"error"` \| `"close"`, `listener`: `fn`): [`Command`](shell.md#command)
|
||||
|
||||
Adds a **one-time**`listener` function for the event named `eventName` to the*beginning* of the listeners array. The next time `eventName` is triggered, this
|
||||
listener is removed, and then invoked.
|
||||
|
||||
Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---------- | :----------------------------- |
|
||||
| `eventName` | `"error"` \| `"close"` |
|
||||
| `listener` | (...`args`: `any`[]) => `void` |
|
||||
|
||||
**Returns: **[`Command`](shell.md#command)
|
||||
|
||||
##### `removeAllListeners`
|
||||
|
||||
> **removeAllListeners**(`event?`: `"error"` \| `"close"`): [`Command`](shell.md#command)
|
||||
|
||||
Removes all listeners, or those of the specified eventName.
|
||||
|
||||
Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :------- | :--------------------- |
|
||||
| `event?` | `"error"` \| `"close"` |
|
||||
|
||||
**Returns: **[`Command`](shell.md#command)
|
||||
|
||||
##### `removeListener`
|
||||
|
||||
> **removeListener**(`eventName`: `"error"` \| `"close"`, `listener`: `fn`): [`Command`](shell.md#command)
|
||||
|
||||
Alias for `emitter.off(eventName, listener)`.
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---------- | :----------------------------- |
|
||||
| `eventName` | `"error"` \| `"close"` |
|
||||
| `listener` | (...`args`: `any`[]) => `void` |
|
||||
|
||||
**Returns: **[`Command`](shell.md#command)
|
||||
|
||||
##### `spawn`
|
||||
|
||||
> **spawn**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Child`](shell.md#child)\>
|
||||
|
||||
Executes the command as a child process, returning a handle to it.
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`Child`](shell.md#child)\>
|
||||
|
||||
A promise resolving to the child process handle.
|
||||
|
||||
##### `sidecar`
|
||||
|
||||
> `Static` **sidecar**(`program`: `string`, `args?`: `string` \| `string`[], `options?`: [`SpawnOptions`](shell.md#spawnoptions)): [`Command`](shell.md#command)
|
||||
|
||||
Creates a command to execute the given sidecar program.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { Command } from "@tauri-apps/api/shell";
|
||||
const command = Command.sidecar("my-sidecar");
|
||||
const output = await command.execute();
|
||||
```
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
| :--------- | :-------------------------------------- | :------------ | :---------------------------------------------------------------------------------------------------------- |
|
||||
| `program` | `string` | `undefined` | The program to execute.<br/>It must be configured on `tauri.conf.json > tauri > allowlist > shell > scope`. |
|
||||
| `args` | `string` \| `string`[] | `[]` | - |
|
||||
| `options?` | [`SpawnOptions`](shell.md#spawnoptions) | `undefined` | - |
|
||||
|
||||
**Returns: **[`Command`](shell.md#command)
|
||||
|
||||
### `EventEmitter<E>`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Type parameters**
|
||||
|
||||
- `E` _extends_ `string`
|
||||
|
||||
**Hierarchy**
|
||||
|
||||
- **EventEmitter**
|
||||
- [`Command`](shell.md#command)
|
||||
|
||||
#### Constructors
|
||||
|
||||
##### `constructor`
|
||||
|
||||
> **new EventEmitter**<`E`\>(): [`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
**Type parameters**
|
||||
|
||||
- `E` _extends_ `string`
|
||||
|
||||
#### Methods
|
||||
|
||||
##### `addListener`
|
||||
|
||||
> **addListener**(`eventName`: `E`, `listener`: `fn`): [`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
Alias for `emitter.on(eventName, listener)`.
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---------- | :----------------------------- |
|
||||
| `eventName` | `E` |
|
||||
| `listener` | (...`args`: `any`[]) => `void` |
|
||||
|
||||
**Returns: **[`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
##### `listenerCount`
|
||||
|
||||
> **listenerCount**(`eventName`: `E`): `number`
|
||||
|
||||
Returns the number of listeners listening to the event named `eventName`.
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---------- | :--- |
|
||||
| `eventName` | `E` |
|
||||
|
||||
**Returns: **`number`
|
||||
|
||||
##### `off`
|
||||
|
||||
> **off**(`eventName`: `E`, `listener`: `fn`): [`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
Removes the all specified listener from the listener array for the event eventName
|
||||
Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---------- | :----------------------------- |
|
||||
| `eventName` | `E` |
|
||||
| `listener` | (...`args`: `any`[]) => `void` |
|
||||
|
||||
**Returns: **[`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
##### `on`
|
||||
|
||||
> **on**(`eventName`: `E`, `listener`: `fn`): [`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
Adds the `listener` function to the end of the listeners array for the
|
||||
event named `eventName`. No checks are made to see if the `listener` has
|
||||
already been added. Multiple calls passing the same combination of `eventName`and `listener` will result in the `listener` being added, and called, multiple
|
||||
times.
|
||||
|
||||
Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---------- | :----------------------------- |
|
||||
| `eventName` | `E` |
|
||||
| `listener` | (...`args`: `any`[]) => `void` |
|
||||
|
||||
**Returns: **[`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
##### `once`
|
||||
|
||||
> **once**(`eventName`: `E`, `listener`: `fn`): [`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
Adds a **one-time**`listener` function for the event named `eventName`. The
|
||||
next time `eventName` is triggered, this listener is removed and then invoked.
|
||||
|
||||
Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---------- | :----------------------------- |
|
||||
| `eventName` | `E` |
|
||||
| `listener` | (...`args`: `any`[]) => `void` |
|
||||
|
||||
**Returns: **[`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
##### `prependListener`
|
||||
|
||||
> **prependListener**(`eventName`: `E`, `listener`: `fn`): [`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
Adds the `listener` function to the _beginning_ of the listeners array for the
|
||||
event named `eventName`. No checks are made to see if the `listener` has
|
||||
already been added. Multiple calls passing the same combination of `eventName`and `listener` will result in the `listener` being added, and called, multiple
|
||||
times.
|
||||
|
||||
Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---------- | :----------------------------- |
|
||||
| `eventName` | `E` |
|
||||
| `listener` | (...`args`: `any`[]) => `void` |
|
||||
|
||||
**Returns: **[`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
##### `prependOnceListener`
|
||||
|
||||
> **prependOnceListener**(`eventName`: `E`, `listener`: `fn`): [`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
Adds a **one-time**`listener` function for the event named `eventName` to the*beginning* of the listeners array. The next time `eventName` is triggered, this
|
||||
listener is removed, and then invoked.
|
||||
|
||||
Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---------- | :----------------------------- |
|
||||
| `eventName` | `E` |
|
||||
| `listener` | (...`args`: `any`[]) => `void` |
|
||||
|
||||
**Returns: **[`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
##### `removeAllListeners`
|
||||
|
||||
> **removeAllListeners**(`event?`: `E`): [`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
Removes all listeners, or those of the specified eventName.
|
||||
|
||||
Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :------- | :--- |
|
||||
| `event?` | `E` |
|
||||
|
||||
**Returns: **[`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
##### `removeListener`
|
||||
|
||||
> **removeListener**(`eventName`: `E`, `listener`: `fn`): [`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
Alias for `emitter.off(eventName, listener)`.
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :---------- | :----------------------------- |
|
||||
| `eventName` | `E` |
|
||||
| `listener` | (...`args`: `any`[]) => `void` |
|
||||
|
||||
**Returns: **[`EventEmitter`](shell.md#eventemitter)<`E`\>
|
||||
|
||||
## Interfaces
|
||||
|
||||
### `ChildProcess`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `code`
|
||||
|
||||
> **code**: `null` \| `number`
|
||||
|
||||
Exit code of the process. `null` if the process was terminated by a signal on Unix.
|
||||
|
||||
**Defined in:** [shell.ts:109](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/shell.ts#L109)
|
||||
|
||||
##### `signal`
|
||||
|
||||
> **signal**: `null` \| `number`
|
||||
|
||||
If the process was terminated by a signal, represents that signal.
|
||||
|
||||
**Defined in:** [shell.ts:111](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/shell.ts#L111)
|
||||
|
||||
##### `stderr`
|
||||
|
||||
> **stderr**: `string`
|
||||
|
||||
The data that the process wrote to `stderr`.
|
||||
|
||||
**Defined in:** [shell.ts:115](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/shell.ts#L115)
|
||||
|
||||
##### `stdout`
|
||||
|
||||
> **stdout**: `string`
|
||||
|
||||
The data that the process wrote to `stdout`.
|
||||
|
||||
**Defined in:** [shell.ts:113](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/shell.ts#L113)
|
||||
|
||||
### `SpawnOptions`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `cwd`
|
||||
|
||||
> `Optional` **cwd**: `string`
|
||||
|
||||
Current working directory.
|
||||
|
||||
**Defined in:** [shell.ts:88](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/shell.ts#L88)
|
||||
|
||||
##### `encoding`
|
||||
|
||||
> `Optional` **encoding**: `string`
|
||||
|
||||
Character encoding for stdout/stderr
|
||||
|
||||
**Since**: 1.1.0
|
||||
|
||||
**Defined in:** [shell.ts:96](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/shell.ts#L96)
|
||||
|
||||
##### `env`
|
||||
|
||||
> `Optional` **env**: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, `string`\>
|
||||
|
||||
Environment variables. set to `null` to clear the process env.
|
||||
|
||||
**Defined in:** [shell.ts:90](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/shell.ts#L90)
|
||||
|
||||
## Functions
|
||||
|
||||
### `open`
|
||||
|
||||
> **open**(`path`: `string`, `openWith?`: `string`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Opens a path or URL with the system's default app,
|
||||
or the one specified with `openWith`.
|
||||
|
||||
The `openWith` value must be one of `firefox`, `google chrome`, `chromium` `safari`,
|
||||
`open`, `start`, `xdg-open`, `gio`, `gnome-open`, `kde-open` or `wslview`.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { open } from "@tauri-apps/api/shell";
|
||||
// opens the given URL on the default browser:
|
||||
await open("https://github.com/tauri-apps/tauri");
|
||||
// opens the given URL using `firefox`:
|
||||
await open("https://github.com/tauri-apps/tauri", "firefox");
|
||||
// opens a file using the default program:
|
||||
await open("/path/to/file");
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :---------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `path` | `string` | The path or URL to open.<br/>This value is matched against the string regex defined on `tauri.conf.json > tauri > allowlist > shell > open`,<br/>which defaults to `^((mailto:\w+)\|(tel:\w+)\|(https?://\w+)).+`. |
|
||||
| `openWith?` | `string` | The app to open the file or URL with.<br/>Defaults to the system default application for the specified path type. |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
@@ -1,114 +0,0 @@
|
||||
---
|
||||
title: tauri
|
||||
---
|
||||
|
||||
# tauri
|
||||
|
||||
Invoke your custom commands.
|
||||
|
||||
This package is also accessible with `window.__TAURI__.tauri` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
|
||||
|
||||
## Type Aliases
|
||||
|
||||
### `InvokeArgs`
|
||||
|
||||
> **InvokeArgs**: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)<`string`, `unknown`\>
|
||||
|
||||
Command arguments.
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Defined in:** [tauri.ts:63](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/tauri.ts#L63)
|
||||
|
||||
## Functions
|
||||
|
||||
### `convertFileSrc`
|
||||
|
||||
> **convertFileSrc**(`filePath`: `string`, `protocol?`: `string`): `string`
|
||||
|
||||
Convert a device file path to an URL that can be loaded by the webview.
|
||||
Note that `asset:` and `https://asset.localhost` must be added to [`tauri.security.csp`](https://tauri.app/v1/api/config/#securityconfig.csp) in `tauri.conf.json`.
|
||||
Example CSP value: `"csp": "default-src 'self'; img-src 'self' asset: https://asset.localhost"` to use the asset protocol on image sources.
|
||||
|
||||
Additionally, `asset` must be added to [`tauri.allowlist.protocol`](https://tauri.app/v1/api/config/#allowlistconfig.protocol)
|
||||
in `tauri.conf.json` and its access scope must be defined on the `assetScope` array on the same `protocol` object.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { appDataDir, join } from "@tauri-apps/api/path";
|
||||
import { convertFileSrc } from "@tauri-apps/api/tauri";
|
||||
const appDataDirPath = await appDataDir();
|
||||
const filePath = await join(appDataDirPath, "assets/video.mp4");
|
||||
const assetUrl = convertFileSrc(filePath);
|
||||
|
||||
const video = document.getElementById("my-video");
|
||||
const source = document.createElement("source");
|
||||
source.type = "video/mp4";
|
||||
source.src = assetUrl;
|
||||
video.appendChild(source);
|
||||
video.load();
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
| :--------- | :------- | :------------ | :------------------------------------------------------------------------------------------------ |
|
||||
| `filePath` | `string` | `undefined` | The file path. |
|
||||
| `protocol` | `string` | `'asset'` | The protocol to use. Defaults to `asset`. You only need to set this when using a custom protocol. |
|
||||
|
||||
**Returns: **`string`
|
||||
|
||||
the URL that can be used as source on the webview.
|
||||
|
||||
### `invoke`
|
||||
|
||||
> **invoke**<`T`\>(`cmd`: `string`, `args?`: [`InvokeArgs`](tauri.md#invokeargs)): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`T`\>
|
||||
|
||||
Sends a message to the backend.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { invoke } from "@tauri-apps/api/tauri";
|
||||
await invoke("login", { user: "tauri", password: "poiwe3h4r5ip3yrhtew9ty" });
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Type parameters**
|
||||
|
||||
- `T`
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Description |
|
||||
| :----- | :---------------------------------- | :--------------------------------------------- |
|
||||
| `cmd` | `string` | The command name. |
|
||||
| `args` | [`InvokeArgs`](tauri.md#invokeargs) | The optional arguments to pass to the command. |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`T`\>
|
||||
|
||||
A promise resolving or rejecting to the backend response.
|
||||
|
||||
### `transformCallback`
|
||||
|
||||
> **transformCallback**(`callback?`: `fn`, `once?`: `boolean`): `number`
|
||||
|
||||
Transforms a callback function to a string identifier that can be passed to the backend.
|
||||
The backend uses the identifier to `eval()` the callback.
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type | Default value |
|
||||
| :---------- | :---------------------------- | :------------ |
|
||||
| `callback?` | (`response`: `any`) => `void` | `undefined` |
|
||||
| `once` | `boolean` | `false` |
|
||||
|
||||
**Returns: **`number`
|
||||
|
||||
A unique identifier associated with the callback function.
|
||||
@@ -1,159 +0,0 @@
|
||||
---
|
||||
title: update
|
||||
---
|
||||
|
||||
# updater
|
||||
|
||||
Customize the auto updater flow.
|
||||
|
||||
This package is also accessible with `window.__TAURI__.updater` when [`build.withGlobalTauri`](https://tauri.app/v1/api/config/#buildconfig.withglobaltauri) in `tauri.conf.json` is set to `true`.
|
||||
|
||||
## Interfaces
|
||||
|
||||
### `UpdateManifest`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `body`
|
||||
|
||||
> **body**: `string`
|
||||
|
||||
**Defined in:** [updater.ts:34](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/updater.ts#L34)
|
||||
|
||||
##### `date`
|
||||
|
||||
> **date**: `string`
|
||||
|
||||
**Defined in:** [updater.ts:33](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/updater.ts#L33)
|
||||
|
||||
##### `version`
|
||||
|
||||
> **version**: `string`
|
||||
|
||||
**Defined in:** [updater.ts:32](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/updater.ts#L32)
|
||||
|
||||
### `UpdateResult`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `manifest`
|
||||
|
||||
> `Optional` **manifest**: [`UpdateManifest`](updater.md#updatemanifest)
|
||||
|
||||
**Defined in:** [updater.ts:41](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/updater.ts#L41)
|
||||
|
||||
##### `shouldUpdate`
|
||||
|
||||
> **shouldUpdate**: `boolean`
|
||||
|
||||
**Defined in:** [updater.ts:42](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/updater.ts#L42)
|
||||
|
||||
### `UpdateStatusResult`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
#### Properties
|
||||
|
||||
##### `error`
|
||||
|
||||
> `Optional` **error**: `string`
|
||||
|
||||
**Defined in:** [updater.ts:24](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/updater.ts#L24)
|
||||
|
||||
##### `status`
|
||||
|
||||
> **status**: [`UpdateStatus`](updater.md#updatestatus)
|
||||
|
||||
**Defined in:** [updater.ts:25](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/updater.ts#L25)
|
||||
|
||||
## Type Aliases
|
||||
|
||||
### `UpdateStatus`
|
||||
|
||||
> **UpdateStatus**: `"PENDING"` \| `"ERROR"` \| `"DONE"` \| `"UPTODATE"`
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Defined in:** [updater.ts:18](https://github.com/tauri-apps/tauri/blob/b7ae725/tooling/api/src/updater.ts#L18)
|
||||
|
||||
## Functions
|
||||
|
||||
### `checkUpdate`
|
||||
|
||||
> **checkUpdate**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`UpdateResult`](updater.md#updateresult)\>
|
||||
|
||||
Checks if an update is available.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { checkUpdate } from "@tauri-apps/api/updater";
|
||||
const update = await checkUpdate();
|
||||
// now run installUpdate() if needed
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`UpdateResult`](updater.md#updateresult)\>
|
||||
|
||||
Promise resolving to the update status.
|
||||
|
||||
### `installUpdate`
|
||||
|
||||
> **installUpdate**(): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
Install the update if there's one available.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { checkUpdate, installUpdate } from "@tauri-apps/api/updater";
|
||||
const update = await checkUpdate();
|
||||
if (update.shouldUpdate) {
|
||||
console.log(
|
||||
`Installing update ${update.manifest?.version}, ${update.manifest?.date}, ${update.manifest.body}`
|
||||
);
|
||||
await installUpdate();
|
||||
}
|
||||
```
|
||||
|
||||
**Since**: 1.0.0
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
|
||||
|
||||
A promise indicating the success or failure of the operation.
|
||||
|
||||
### `onUpdaterEvent`
|
||||
|
||||
> **onUpdaterEvent**(`handler`: `fn`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`UnlistenFn`](event.md#unlistenfn)\>
|
||||
|
||||
Listen to an updater event.
|
||||
|
||||
**Example**
|
||||
|
||||
```typescript
|
||||
import { onUpdaterEvent } from "@tauri-apps/api/updater";
|
||||
const unlisten = await onUpdaterEvent(({ error, status }) => {
|
||||
console.log("Updater event", error, status);
|
||||
});
|
||||
|
||||
// you need to call unlisten if your handler goes out of scope e.g. the component is unmounted
|
||||
unlisten();
|
||||
```
|
||||
|
||||
**Since**: 1.0.2
|
||||
|
||||
**Parameters**
|
||||
|
||||
| Name | Type |
|
||||
| :-------- | :-------------------------------------------------------------------------- |
|
||||
| `handler` | (`status`: [`UpdateStatusResult`](updater.md#updatestatusresult)) => `void` |
|
||||
|
||||
**Returns: **[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[`UnlistenFn`](event.md#unlistenfn)\>
|
||||
|
||||
A promise resolving to a function to unlisten to the event.
|
||||
Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,13 +0,0 @@
|
||||
---
|
||||
title: introduction
|
||||
---
|
||||
|
||||
# Introduction
|
||||
|
||||
The Tauri Bundler is a Rust harness to compile your binary, package assets, and prepare a final bundle.
|
||||
|
||||
It will detect your operating system and build a bundle accordingly. It currently supports:
|
||||
|
||||
- [Windows](./windows.md): `-setup.exe`, `.msi`
|
||||
- [macOS](./macos.md): `.app`, `.dmg`
|
||||
- [Linux](./linux.md): `.deb`, `.appimage`
|
||||
@@ -1,13 +0,0 @@
|
||||
---
|
||||
title: _tauri-build
|
||||
---
|
||||
|
||||
import Command from '@theme/Command'
|
||||
|
||||
To build and bundle your Tauri application into a single executable simply run the following command:
|
||||
|
||||
<Command name="build" />
|
||||
|
||||
It will build your frontend (if configured, see [`beforeBuildCommand`][beforebuildcommand]), compile the Rust binary, collect all external binaries and resources and finally produce neat platform-specific bundles and installers.
|
||||
|
||||
[beforebuildcommand]: ../../api/config.md#buildconfig.beforebuildcommand
|
||||
@@ -1,317 +0,0 @@
|
||||
---
|
||||
title: reducing app size
|
||||
---
|
||||
|
||||
# Reducing App Size
|
||||
|
||||
With Tauri, we are working to reduce the environmental footprint of applications by using fewer system resources where available, providing compiled systems that don't need runtime evaluation, and offering guides so that engineers can go even smaller without sacrificing performance or security. By saving resources we are doing our part to help you help us save the planet -- which is the only bottom line that companies in the 21st Century should care about.
|
||||
|
||||
So if you are interested in learning how to improve your app size and performance, read on!
|
||||
|
||||
### You can't improve what you can't measure
|
||||
|
||||
Before you can optimize your app, you need to figure out what takes up space in your app! Here are a couple of tools that can assist you with that:
|
||||
|
||||
- **[`cargo-bloat`]** - A Rust utility to determine what takes the most space in your app. It gives you an excellent, sorted overview of the most significant Rust functions.
|
||||
|
||||
- **[`cargo-expand`]** - [Macros] make your rust code more concise and easier to read, but they are also hidden size traps! Use `cargo-expand` to see what those macros generate under the hood.
|
||||
|
||||
- **[`rollup-plugin-visualizer`]** - A tool that generates beautiful (and insightful) graphs from your rollup bundle. Very convenient for figuring out what JavaScript dependencies contribute to your final bundle size the most.
|
||||
|
||||
- **[`rollup-plugin-graph`]** - You noticed a dependency included in your final frontend bundle, but you are unsure why? `rollup-plugin-graph` generates Graphviz-compatible visualizations of your entire dependency graph.
|
||||
|
||||
These are just a couple of tools that you might use. Make sure to check your frontend bundlers plugin list for more!
|
||||
|
||||
## Checklist
|
||||
|
||||
1. [Minify Javascript](#minify-javascript)
|
||||
2. [Optimize Dependencies](#optimize-dependencies)
|
||||
3. [Optimize Images](#optimize-images)
|
||||
4. [Remove Unnecessary Custom Fonts](#remove-unnecessary-custom-fonts)
|
||||
5. [Allowlist Config](#allowlist-config)
|
||||
6. [Rust Build-time Optimizations](#rust-build-time-optimizations)
|
||||
7. [Stripping](#stripping)
|
||||
8. [UPX](#upx)
|
||||
|
||||
### Minify JavaScript
|
||||
|
||||
JavaScript makes up a large portion of a typical Tauri app, so it's important to make the JavaScript as lightweight as possible.
|
||||
|
||||
You can choose from a plethora of JavaScript bundlers; popular choices are [Vite], [webpack], and [rollup]. All of them can produce minified JavaScript if configured correctly, so consult your bundler documentation for specific options. Generally speaking, you should make sure to:
|
||||
|
||||
#### Enable tree shaking
|
||||
|
||||
This option removes unused JavaScript from your bundle. All popular bundlers enable this by default.
|
||||
|
||||
#### Enable minification
|
||||
|
||||
Minification removes unnecessary whitespace, shortens variable names, and applies other optimizations. Most bundlers enable this by default; a notable exception is [rollup], where you need plugins like [rollup-plugin-terser] or [rollup-plugin-uglify].
|
||||
|
||||
Note: You can use minifiers like [terser] and [esbuild] as standalone tools.
|
||||
|
||||
#### Disable source maps
|
||||
|
||||
Source maps provide a pleasant developer experience when working with languages that compile to JavaScript, such as [TypeScript]. As source maps tend to be quite large, you must disable them when building for production. They have no benefit to your end-user, so it's effectively dead weight.
|
||||
|
||||
### Optimize Dependencies
|
||||
|
||||
Many popular libraries have smaller and faster alternatives that you can choose from instead.
|
||||
|
||||
Most libraries you use depend on many libraries themselves, so a library that looks inconspicuous at first glance might add **several megabytes** worth of code to your app.
|
||||
|
||||
You can use [Bundlephobia] to find the cost of JavaScript dependencies. Inspecting the cost of Rust dependencies is generally harder since the compiler does many optimizations.
|
||||
|
||||
If you find a library that seems excessively large, Google around, chances are someone else already had the same thought and created an alternative. A good example is [Moment.js] and its [many alternatives][you-dont-need-momentjs].
|
||||
|
||||
But keep in mind: **The best dependency is no dependency**, meaning that you should always prefer language builtins over 3rd party packages.
|
||||
|
||||
### Optimize Images
|
||||
|
||||
According to the [Http Archive], images are the [biggest contributor to website weight][http archive report, image bytes]. So if your app includes images or icons, make sure to optimize them!
|
||||
|
||||
You can choose between a variety of manual options ([GIMP], [Photoshop], [Squoosh]) or plugins for your favorite frontend build tools ([vite-imagetools], [vite-plugin-imagemin], [image-minimizer-webpack-plugin]).
|
||||
|
||||
Do note that the `imagemin` library most of the plugins use is [officially unmaintained][imagemin is unmaintained].
|
||||
|
||||
#### Use Modern Image Formats
|
||||
|
||||
Formats such as `webp` or `avif` offer size reductions of **up to
|
||||
95%** compared to jpeg while maintaining excellent visual accuracy.
|
||||
You can use tools such as [Squoosh] to try different formats on your
|
||||
images.
|
||||
|
||||
#### Size Images Accordingly
|
||||
|
||||
No one appreciates you shipping the 6K raw image with your app, so make sure to size your image accordingly. Images that appear large on-screen should be sized larger than images that take up less screen space.
|
||||
|
||||
#### Don't Use Responsive Images
|
||||
|
||||
In a Web Environment, you are supposed to use [Responsive Images] to load the correct image size for each user dynamically. Since you are not dynamically distributing images over the web, using Responsive Images only needlessly bloats your app with redundant copies.
|
||||
|
||||
#### Remove Metadata
|
||||
|
||||
Images that were taken straight from a camera or stock photo side often include metadata about the camera and lens model or photographer. Not only are those wasted bytes, but metadata
|
||||
properties can also hold potentially sensitive information such as the time, day, and location of the photo.
|
||||
|
||||
### Remove Unnecessary Custom Fonts
|
||||
|
||||
Consider not shipping custom fonts with your app and relying on system fonts instead. If you must ship custom fonts, make sure they are in modern, optimized formats such as `woff2`.
|
||||
|
||||
Fonts can be pretty big, so using the fonts already included in the Operating System reduces the footprint of your app. It also avoids FOUT (Flash of Unstyled Text) and makes your app feel more "native" since it uses the same font as all other apps.
|
||||
|
||||
If you must include custom fonts, make sure you include them in modern formats such as `woff2` as those tend to be much smaller than legacy formats.
|
||||
|
||||
Use so-called **"System Font Stacks"** in your CSS. There are a number
|
||||
of variations, but here are 3 basic ones to get you started:
|
||||
|
||||
**Sans-Serif**
|
||||
|
||||
```css
|
||||
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial,
|
||||
sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
|
||||
```
|
||||
|
||||
**Serif**
|
||||
|
||||
```css
|
||||
font-family: Iowan Old Style, Apple Garamond, Baskerville, Times New Roman, Droid
|
||||
Serif, Times, Source Serif Pro, serif, Apple Color Emoji, Segoe UI Emoji, Segoe
|
||||
UI Symbol;
|
||||
```
|
||||
|
||||
**Monospace**
|
||||
|
||||
```css
|
||||
font-family: ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, Liberation
|
||||
Mono, monospace;
|
||||
```
|
||||
|
||||
### Allowlist Config
|
||||
|
||||
You can reduce the size of your app by only enabling the Tauri API features you need in the `allowlist` config.
|
||||
|
||||
The `allowlist` config determines what API features to enable; disabled features will **not be compiled into your app**. This is an easy way of shedding some extra weight.
|
||||
|
||||
An example from a typical `tauri.conf.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"all": false,
|
||||
"fs": {
|
||||
"writeFile": true
|
||||
},
|
||||
"shell": {
|
||||
"execute": true
|
||||
},
|
||||
"dialog": {
|
||||
"save": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Rust Build-Time Optimizations
|
||||
|
||||
Configure your cargo project to take advantage of Rusts size optimization features. [Why is a rust executable large ?] provides an excellent explanation of why this matters and an in-depth walkthrough. At the same time, [Minimizing Rust Binary Size] is more up-to-date and has a couple of extra recommendations.
|
||||
|
||||
Rust is notorious for producing large binaries, but you can instruct the compiler to optimize the final executable's size.
|
||||
|
||||
Cargo exposes several options that determine how the compiler generates your binary. The "recommended" options for Tauri apps are these:
|
||||
|
||||
```toml
|
||||
[profile.release]
|
||||
panic = "abort" # Strip expensive panic clean-up logic
|
||||
codegen-units = 1 # Compile crates one after another so the compiler can optimize better
|
||||
lto = true # Enables link to optimizations
|
||||
opt-level = "s" # Optimize for binary size
|
||||
strip = true # Remove debug symbols
|
||||
```
|
||||
|
||||
:::note
|
||||
There is also `opt-level = "z"` available to reduce the resulting binary size. `"s"` and `"z"` can sometimes be smaller than the other, so test it with your application!
|
||||
|
||||
We've seen smaller binary sizes from `"s"` for Tauri example applications, but real-world applications can always differ.
|
||||
:::
|
||||
|
||||
For a detailed explanation of each option and a bunch more, refer to the [Cargo books Profiles section][cargo profiles].
|
||||
|
||||
#### Disable Tauri's Asset Compression
|
||||
|
||||
By default, Tauri uses Brotli to compress assets in the final binary. Brotli embeds a large (~170KiB) lookup table to achieve great results, but if the resources you embed are smaller than this or compress poorly, the resulting binary may be bigger than any savings.
|
||||
|
||||
Compression can be disabled by setting `default-features` to `false` and specifying everything except the `compression` feature:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
tauri = { version = "...", features = ["objc-exception", "wry"], default-features = false }
|
||||
```
|
||||
|
||||
#### Unstable Rust Compression Features
|
||||
|
||||
:::caution
|
||||
The following suggestions are all unstable features and require a nightly toolchain. See the [Unstable Features][cargo unstable features] documentation for more information on what this involves.
|
||||
:::
|
||||
|
||||
The following methods involve using unstable compiler features and require the rust nightly toolchain. If you don't have the nightly toolchain + `rust-src` nightly component added, try the following:
|
||||
|
||||
```shell
|
||||
rustup toolchain install nightly
|
||||
rustup component add rust-src --toolchain nightly
|
||||
```
|
||||
|
||||
To tell Cargo that the current project uses the nightly toolchain, we will create an [Override File] at the root of our project called `rust-toolchain.toml`. This file will contain the following:
|
||||
|
||||
```toml title=rust-toolchain.toml
|
||||
[toolchain]
|
||||
channel = "nightly-2023-01-03" # The nightly release to use, you can update this to the most recent one if you want
|
||||
profile = "minimal"
|
||||
```
|
||||
|
||||
The Rust Standard Library comes precompiled. This means Rust is faster to install, but also that the compiler can't optimize the Standard Library. You can apply the optimization options for the rest of your binary + dependencies to the std with an unstable flag. This flag requires specifying your target, so know the target triple you are targeting.
|
||||
|
||||
```shell
|
||||
cargo tauri build --target <Target triple to build for> -- -Z build-std
|
||||
```
|
||||
|
||||
If you are using `panic = "abort"` in your release profile optimizations, you need to make sure the `panic_abort` crate is compiled with std. Additionally, an extra std feature can further reduce the binary size. The following applies to both:
|
||||
|
||||
```shell
|
||||
cargo tauri build --target <Target triple to build for> -- -Z build-std=std,panic_abort -Z build-std-features=panic_immediate_abort
|
||||
```
|
||||
|
||||
See the unstable documentation for more details about [`-Z build-std`][cargo build-std] and [`-Z build-std-features`][cargo build-std-features].
|
||||
|
||||
### Stripping
|
||||
|
||||
Use strip utilities to remove debug symbols from your compiled app.
|
||||
|
||||
Your compiled app includes so-called "Debug Symbols" that include function and variable names. Your end-users will probably not care about Debug Symbols, so this is a pretty surefire way to save some bytes!
|
||||
|
||||
The easiest way is to use the famous `strip` utility to remove this debugging information.
|
||||
|
||||
```shell
|
||||
strip target/release/my_application
|
||||
```
|
||||
|
||||
See your local `strip` manpage for more information and flags that can be used to specify what information gets stripped out from the binary.
|
||||
|
||||
:::info
|
||||
|
||||
Rust 1.59 now has a builtin version of `strip`! It can be
|
||||
enabled by adding the following to your `Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[profile.release]
|
||||
strip = true # Automatically strip symbols from the binary.
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### UPX
|
||||
|
||||
UPX, **Ultimate Packer for eXecutables**, is a dinosaur amongst the binary packers. This 23-year-old, well-maintained piece of kit is GPL-v2 licensed with a pretty liberal usage declaration. Our understanding of the licensing is that you can use it for any purposes (commercial or otherwise) without needing to change your license unless you modify the source code of UPX.
|
||||
|
||||
Maybe your target audience has very slow internet, or your app needs to fit on a tiny USB stick, and all the above steps haven't resulted in the savings you need. Fear not, as we have one last trick up our sleeves:
|
||||
|
||||
[UPX] compresses your binary and creates a self-extracting executable that decompresses itself at runtime.
|
||||
|
||||
:::caution
|
||||
You should know that this technique might flag your binary as a virus on Windows and macOS - so use it at your own discretion, and as always, validate with [Frida] and do real distribution testing!
|
||||
:::
|
||||
|
||||
#### Usage on macOS
|
||||
|
||||
<!-- Add additional platforms -->
|
||||
|
||||
```
|
||||
brew install upx
|
||||
yarn tauri build
|
||||
upx --ultra-brute src-tauri/target/release/bundle/macos/app.app/Contents/macOS/app
|
||||
|
||||
Ultimate Packer for eXecutables
|
||||
Copyright (C) 1996 - 2018
|
||||
UPX 3.95 Markus Oberhumer, Laszlo Molnar & John Reiser Aug 26th 2018
|
||||
|
||||
File size Ratio Format Name
|
||||
-------------------- ------ ----------- -----------
|
||||
963140 -> 274448 28.50% macho/amd64 app
|
||||
```
|
||||
|
||||
[`cargo-bloat`]: https://github.com/RazrFalcon/cargo-bloat
|
||||
[macros]: https://doc.rust-lang.org/book/ch19-06-macros.html
|
||||
[`cargo-expand`]: https://github.com/dtolnay/cargo-expand
|
||||
[`rollup-plugin-visualizer`]: https://github.com/btd/rollup-plugin-visualizer
|
||||
[`rollup-plugin-graph`]: https://github.com/ondras/rollup-plugin-graph
|
||||
[vite]: https://vitejs.dev
|
||||
[webpack]: https://webpack.js.org
|
||||
[rollup]: https://rollupjs.org/guide/en/
|
||||
[rollup-plugin-terser]: https://github.com/TrySound/rollup-plugin-terser
|
||||
[rollup-plugin-uglify]: https://github.com/TrySound/rollup-plugin-uglify
|
||||
[terser]: https://terser.org
|
||||
[esbuild]: https://esbuild.github.io
|
||||
[typescript]: https://www.typescriptlang.org
|
||||
[moment.js]: https://momentjs.com
|
||||
[you-dont-need-momentjs]: https://github.com/you-dont-need/You-Dont-Need-Momentjs
|
||||
[http archive]: https://httparchive.org
|
||||
[http archive report, image bytes]: https://httparchive.org/reports/page-weight#bytesImg
|
||||
[imagemin is unmaintained]: https://github.com/imagemin/imagemin/issues/385
|
||||
[gimp]: https://www.gimp.org
|
||||
[photoshop]: https://www.adobe.com/de/products/photoshop.html
|
||||
[vite-imagetools]: https://github.com/JonasKruckenberg/imagetools
|
||||
[vite-plugin-imagemin]: https://github.com/vbenjs/vite-plugin-imagemin
|
||||
[image-minimizer-webpack-plugin]: https://github.com/webpack-contrib/image-minimizer-webpack-plugin
|
||||
[squoosh]: https://squoosh.app
|
||||
[responsive images]: https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images
|
||||
[why is a rust executable large ?]: https://lifthrasiir.github.io/rustlog/why-is-a-rust-executable-large.html
|
||||
[minimizing rust binary size]: https://github.com/johnthagen/min-sized-rust
|
||||
[cargo unstable features]: https://doc.rust-lang.org/cargo/reference/unstable.html#unstable-features
|
||||
[override file]: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file
|
||||
[cargo profiles]: https://doc.rust-lang.org/cargo/reference/profiles.html
|
||||
[cargo build-std]: https://doc.rust-lang.org/cargo/reference/unstable.html#build-std
|
||||
[cargo build-std-features]: https://doc.rust-lang.org/cargo/reference/unstable.html#build-std-features
|
||||
[bundlephobia]: https://bundlephobia.com
|
||||
[frida]: https://frida.re/docs/home/
|
||||
[upx]: https://github.com/upx/upx
|
||||
@@ -1,270 +0,0 @@
|
||||
---
|
||||
title: cross platform compilation
|
||||
---
|
||||
|
||||
import Command from '@theme/Command'
|
||||
|
||||
# Cross-Platform Compilation
|
||||
|
||||
Tauri relies heavily on native libraries and toolchains, so meaningful cross-compilation is **not possible** at the current moment. The next best option is to compile utilizing a CI/CD pipeline hosted on something like [GitHub Actions], Azure Pipelines, GitLab, or other options. The pipeline can run the compilation for each platform simultaneously making the compilation and release process much easier.
|
||||
|
||||
For an easy setup, we currently provide [Tauri Action], a GitHub Action that runs on all the supported platforms, compiles your software, generates the necessary artifacts, and uploads them to a new GitHub release.
|
||||
|
||||
## Tauri GitHub Action
|
||||
|
||||
Tauri Action leverages GitHub Actions to simultaneously build your application as a Tauri native binary for macOS, Linux, and Windows, and automates creating a GitHub release.
|
||||
|
||||
This GitHub Action may also be used as a testing pipeline for your Tauri app, guaranteeing compilation runs fine on all platforms for each pull request sent, even if you don't wish to create a new release.
|
||||
|
||||
:::info Code Signing
|
||||
|
||||
To setup code signing for both Windows and macOS on your workflow, follow the specific guide for each platform:
|
||||
|
||||
- [Windows Code Signing with GitHub Actions]
|
||||
- [macOS Code Signing with GitHub Actions]
|
||||
|
||||
:::
|
||||
|
||||
### Getting Started
|
||||
|
||||
To set up Tauri Action you must first set up a GitHub repository. You can use this action on a repo that doesn't have Tauri configured since it automatically initializes Tauri before building and configuring it to use your artifacts.
|
||||
|
||||
Go to the Actions tab on your GitHub project and choose "New workflow", then choose "Set up a workflow yourself". Replace the file with the [Tauri Action production build workflow example]. Alternatively, you may set up the workflow based on the [example at the bottom of this page](#example-workflow)
|
||||
|
||||
### Configuration
|
||||
|
||||
You can configure Tauri with the `configPath`, `distPath` and `iconPath` options. See the actions Readme for details.
|
||||
|
||||
<!-- FIXME: tauriScript is currently broken.
|
||||
Custom Tauri CLI scripts can be run with the `tauriScript` option. So instead of running `yarn tauri build` or `npx tauri build`, `${tauriScript}` will be executed. This can be useful when you need custom build functionality such as when creating Tauri apps e.g. a `desktop:build` script.
|
||||
-->
|
||||
|
||||
When your app isn't on the root of the repo, use the `projectPath` input.
|
||||
|
||||
You may modify the workflow name, change the triggers, and add more steps such as `npm run lint` or `npm run test`. The important part is that you keep the below line at the end of the workflow, since this runs the build script and releases the artifacts:
|
||||
|
||||
```yaml
|
||||
- uses: tauri-apps/tauri-action@v0
|
||||
```
|
||||
|
||||
### How to Trigger
|
||||
|
||||
The release workflow in the README examples linked above is triggered by pushes on the "release" branch. The action automatically creates a tag and title for the GitHub release using the application version specified in `tauri.config.json`.
|
||||
|
||||
You can also trigger the workflow on the push of a version tag such as "app-v0.7.0". For this you can change the start of the release workflow:
|
||||
|
||||
```yaml
|
||||
name: publish
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- "app-v*"
|
||||
workflow_dispatch:
|
||||
```
|
||||
|
||||
### Example Workflow
|
||||
|
||||
Below is an example workflow that has been setup to run every time a new version is created on git.
|
||||
|
||||
This workflow sets up the environment on Windows, Ubuntu, and macOS latest versions. Note under `jobs.release.strategy.matrix` the platform array which contains `macos-latest`, `ubuntu-20.04`, and `windows-latest`.
|
||||
|
||||
The steps this workflow takes are:
|
||||
|
||||
1. Checkout the repository using `actions/checkout@v3`
|
||||
2. Set up Node LTS and a cache for global npm/yarn/pnpm package data using `actions/setup-node@v3`.
|
||||
3. Set up Rust and a cache for the `target/` folder using `dtolnay/rust-toolchain@stable` and `swatinem/rust-cache@v2`.
|
||||
4. Installs all the dependencies and run the build script (for the web app).
|
||||
5. Finally, it uses `tauri-apps/tauri-action@v0` to run `tauri build`, generate the artifacts, and create the GitHub release.
|
||||
|
||||
```yaml
|
||||
name: Release
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- "v*"
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
release:
|
||||
permissions:
|
||||
contents: write
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
platform: [macos-latest, ubuntu-20.04, windows-latest]
|
||||
runs-on: ${{ matrix.platform }}
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v3
|
||||
|
||||
- name: Install dependencies (ubuntu only)
|
||||
if: matrix.platform == 'ubuntu-20.04'
|
||||
# You can remove libayatana-appindicator3-dev if you don't use the system tray feature.
|
||||
run: |
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev libayatana-appindicator3-dev librsvg2-dev
|
||||
|
||||
- name: Rust setup
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Rust cache
|
||||
uses: swatinem/rust-cache@v2
|
||||
with:
|
||||
workspaces: "./src-tauri -> target"
|
||||
|
||||
- name: Sync node version and setup cache
|
||||
uses: actions/setup-node@v3
|
||||
with:
|
||||
node-version: "lts/*"
|
||||
cache: "yarn" # Set this to npm, yarn or pnpm.
|
||||
|
||||
- name: Install frontend dependencies
|
||||
# If you don't have `beforeBuildCommand` configured you may want to build your frontend here too.
|
||||
run: yarn install # Change this to npm, yarn or pnpm.
|
||||
|
||||
- name: Build the app
|
||||
uses: tauri-apps/tauri-action@v0
|
||||
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
with:
|
||||
tagName: ${{ github.ref_name }} # This only works if your workflow triggers on new tags.
|
||||
releaseName: "App Name v__VERSION__" # tauri-action replaces \_\_VERSION\_\_ with the app version.
|
||||
releaseBody: "See the assets to download and install this version."
|
||||
releaseDraft: true
|
||||
prerelease: false
|
||||
```
|
||||
|
||||
### GitHub Environment Token
|
||||
|
||||
The GitHub Token is automatically issued by GitHub for each workflow run without further configuration, which means there is no risk of secret leakage. This token however only has read permissions by default and you may get a "Resource not accessible by integration" error when running the workflow. If this happens, you may need to add write permissions to this token. To do this go to your GitHub Project Settings, and then select Actions, scroll down to "Workflow permissions" and check "Read and write permissions".
|
||||
|
||||
You can see the GitHub Token being passed to the workflow below:
|
||||
|
||||
```yaml
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
```
|
||||
|
||||
### Usage Notes
|
||||
|
||||
Make sure to check the [documentation for GitHub Actions][github actions] to understand better how this workflow works. Take care to read the [Usage limits, billing, and administration][usage limits billing and administration] documentation for GitHub Actions. Some project templates may already implement this GitHub action workflow, such as [tauri-svelte-template]. You can use this action on a repo that doesn't have Tauri configured. Tauri automatically initializes before building and configuring it to use your web artifacts.
|
||||
|
||||
## Experimental: Build Windows apps on Linux and macOS
|
||||
|
||||
Tauri v1.3 added a new Windows installer type based on the [NSIS] installer framework. In contrast to WiX, NSIS itself can also work on Linux and macOS which makes it possible to build many Tauri apps on non-Windows hosts. Note that this is currently considered highly experimental and may not work on every system or for every project. Therefore it should only be used as a last resort if local VMs or CI solutions like GitHub Actions don't work for you.
|
||||
|
||||
Since Tauri officially only supports the MSVC Windows target, the setup is a bit more involved.
|
||||
|
||||
First, make sure all your Tauri dependencies are at least version 1.3, check out the [dependency update guide] if you're not sure how.
|
||||
|
||||
#### Install NSIS
|
||||
|
||||
Some Linux distributions have NSIS available in their repositories, for example on Ubuntu you can install NSIS by running this command:
|
||||
|
||||
```sh title=Ubuntu
|
||||
sudo apt install nsis
|
||||
```
|
||||
|
||||
But on many other distributions you have to compile NSIS yourself or download Stubs and Plugins manually that weren't included in the distro's binary package. Fedora for example only provides the binary but not the Stubs and Plugins:
|
||||
|
||||
```sh title=Fedora
|
||||
sudo dnf in mingw64-nsis
|
||||
wget https://github.com/tauri-apps/binary-releases/releases/download/nsis-3/nsis-3.zip
|
||||
unzip nsis-3.zip
|
||||
sudo cp nsis-3.08/Stubs/* /usr/share/nsis/Stubs/
|
||||
sudo cp -r nsis-3.08/Plugins/** /usr/share/nsis/Plugins/
|
||||
```
|
||||
|
||||
On macOS you will need [Homebrew] to install NSIS:
|
||||
|
||||
```sh title=macOS
|
||||
brew install nsis
|
||||
```
|
||||
|
||||
#### Install LLVM and the LLD Linker
|
||||
|
||||
Since the default Microsoft linker only works on Windows we will also need to install a new linker. To compile the Windows Resource file which is used for setting the app icon among other things we will also need the `llvm-rc` binary which is part of the LLVM project.
|
||||
|
||||
```sh title="Ubuntu"
|
||||
sudo apt install lld llvm
|
||||
```
|
||||
|
||||
```sh title=macOS
|
||||
brew install llvm
|
||||
```
|
||||
|
||||
On macOS you also have to add `/opt/homebrew/opt/llvm/bin` to your `$PATH` as suggested in the install output.
|
||||
|
||||
#### Install the Windows Rust target
|
||||
|
||||
Assuming you're building for 64-bit Windows systems:
|
||||
|
||||
```sh
|
||||
rustup target add x86_64-pc-windows-msvc
|
||||
```
|
||||
|
||||
#### Install the Windows SDKs
|
||||
|
||||
To get the Windows SDKs required by the msvc target we will use the [xwin] project:
|
||||
|
||||
```sh
|
||||
cargo install xwin
|
||||
```
|
||||
|
||||
Then you can use the `xwin` CLI to install the needed files to a location of your choice. Remember the location, we will need it in the next step. In this guide we will create a `.xwin` directory in the Home directory.
|
||||
|
||||
```sh
|
||||
xwin splat --output ~/.xwin
|
||||
```
|
||||
|
||||
If that fails with an error message like this:
|
||||
|
||||
```
|
||||
Error: failed to splat Microsoft.VC.14.29.16.10.CRT.x64.Desktop.base.vsix
|
||||
|
||||
Caused by:
|
||||
0: unable to symlink from .xwin/crt/lib/x86_64/LIBCMT.lib to libcmt.lib
|
||||
1: File exists (os error 17)
|
||||
```
|
||||
|
||||
you can try adding the `--disable-symlinks` flag to the command:
|
||||
|
||||
```sh
|
||||
xwin splat --output ~/.xwin --disable-symlinks
|
||||
```
|
||||
|
||||
Now, to make the Rust compiler use these files, you first have to create a `.cargo` directory in your project and create a `config.toml` file in it with the following content. Make sure to change the paths accordingly.
|
||||
|
||||
```toml title=.cargo/config.toml
|
||||
[target.x86_64-pc-windows-msvc]
|
||||
linker = "lld"
|
||||
rustflags = [
|
||||
"-Lnative=/home/username/.xwin/crt/lib/x86_64",
|
||||
"-Lnative=/home/username/.xwin/sdk/lib/um/x86_64",
|
||||
"-Lnative=/home/username/.xwin/sdk/lib/ucrt/x86_64"
|
||||
]
|
||||
```
|
||||
|
||||
Keep in mind that this file is specific to your machine so we don't recommend checking it into git if your project is public or will be shared with anyone.
|
||||
|
||||
#### Building the App
|
||||
|
||||
Now it should be as simple as adding the target to the `tauri build` command:
|
||||
|
||||
<Command name="build --target x86_64-pc-windows-msvc" />
|
||||
|
||||
The build output will then be in `target/x86_64-pc-windows-msvc/release/bundle/nsis/`.
|
||||
|
||||
[tauri action]: https://github.com/tauri-apps/tauri-action
|
||||
[tauri action production build workflow example]: https://github.com/tauri-apps/tauri-action#creating-a-release-and-uploading-the-tauri-bundles
|
||||
[github actions]: https://docs.github.com/en/actions
|
||||
[usage limits billing and administration]: https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration
|
||||
[tauri-svelte-template]: https://github.com/probablykasper/tauri-svelte-template
|
||||
[windows code signing with github actions]: ../distribution/sign-windows.md#bonus-sign-your-application-with-github-actions
|
||||
[macos code signing with github actions]: ../distribution/sign-macos.md#example
|
||||
[nsis]: https://nsis.sourceforge.io/Main_Page
|
||||
[dependency update guide]: ../development/updating-dependencies
|
||||
[homebrew]: https://brew.sh/
|
||||
[xwin]: https://github.com/Jake-Shadle/xwin
|
||||
@@ -1,73 +0,0 @@
|
||||
---
|
||||
title: linux bundle
|
||||
---
|
||||
|
||||
import TauriBuild from './\_tauri-build.md'
|
||||
|
||||
# Linux Bundle
|
||||
|
||||
Tauri applications for Linux are distributed either with a Debian bundle (`.deb` file) or an AppImage (`.AppImage` file). The Tauri CLI automatically bundles your application code in these formats by default. Please note that `.deb` and `.AppImage` bundles can **only be created on Linux** as cross-compilation doesn't work yet.
|
||||
|
||||
:::note
|
||||
|
||||
GUI apps on macOS and Linux do not inherit the `$PATH` from your shell dotfiles (`.bashrc`, `.bash_profile`, `.zshrc`, etc). Check out Tauri's [fix-path-env-rs] crate to fix this issue.
|
||||
|
||||
:::
|
||||
|
||||
<TauriBuild />
|
||||
|
||||
## Limitations
|
||||
|
||||
Core libraries such as glibc frequently break compatibility with older systems. For this reason, you must build your Tauri application using the oldest base system you intend to support. A relatively old system such as Ubuntu 18.04 is more suited than Ubuntu 22.04, as the binary compiled on Ubuntu 22.04 will have a higher requirement of the glibc version, so when running on an older system, you will face a runtime error like `/usr/lib/libc.so.6: version 'GLIBC_2.33' not found`. We recommend using a Docker container or GitHub Actions to build your Tauri application for Linux.
|
||||
|
||||
See the issues [tauri-apps/tauri#1355] and [rust-lang/rust#57497], in addition to the [AppImage guide] for more information.
|
||||
|
||||
## Debian
|
||||
|
||||
The stock Debian package generated by the Tauri bundler has everything you need to ship your application to Debian-based Linux distributions, defining your application's icons, generating a Desktop file, and specifying the dependencies `libwebkit2gtk-4.0-37` and `libgtk-3-0`, along with `libappindicator3-1` if your app uses the system tray.
|
||||
|
||||
### Custom Files
|
||||
|
||||
Tauri exposes a few configurations for the Debian package in case you need more control.
|
||||
|
||||
If your app depends on additional system dependencies you can specify them in `tauri.conf.json > tauri > bundle > deb > depends`.
|
||||
|
||||
To include custom files in the Debian package, you can provide a list of files or folders in `tauri.conf.json > tauri > bundle > deb > files`. The configuration object maps the path in the Debian package to the path to the file on your filesystem, relative to the `tauri.conf.json` file. Here's an example configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"bundle": {
|
||||
"deb": {
|
||||
"files": {
|
||||
"/usr/share/README.md": "../README.md", // copies the README.md file to /usr/share/README.md
|
||||
"usr/share/assets": "../assets/" // copies the entire assets directory to /usr/share/assets
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If you need to bundle files in a cross-platform way, check Tauri's [resource] and [sidecar] mechanisms.
|
||||
|
||||
## AppImage
|
||||
|
||||
AppImage is a distribution format that does not rely on the system installed packages and instead bundles all dependencies and files needed by the application. For this reason, the output file is larger but easier to distribute since it is supported on many Linux distributions and can be executed without installation. The user just needs to make the file executable (`chmod a+x MyProject.AppImage`) and can then run it (`./MyProject.AppImage`).
|
||||
|
||||
AppImages are convenient, simplifying the distribution process if you cannot make a package targeting the distribution's package manager. Still, you should carefully use it as the file size grows from the 2-6MBs range to 70+MBs.
|
||||
|
||||
:::caution
|
||||
|
||||
If your app plays audio/video you need to enable `tauri.conf.json > tauri > bundle > appimage > bundleMediaFramework`. This will increase the size of the AppImage bundle to include additional `gstreamer` files needed for media playback. This flag is currently only supported on Ubuntu build systems.
|
||||
|
||||
:::
|
||||
|
||||
[resource]: resources.md
|
||||
[sidecar]: sidecar.md
|
||||
[debian package]: https://wiki.debian.org/Packaging
|
||||
[appimage]: https://appimage.org/
|
||||
[tauri-apps/tauri#1355]: https://github.com/tauri-apps/tauri/issues/1355
|
||||
[rust-lang/rust#57497]: https://github.com/rust-lang/rust/issues/57497
|
||||
[appimage guide]: https://docs.appimage.org/reference/best-practices.html#binaries-compiled-on-old-enough-base-system
|
||||
[fix-path-env-rs]: https://github.com/tauri-apps/fix-path-env-rs
|
||||
@@ -1,70 +0,0 @@
|
||||
---
|
||||
title: macOS bundle
|
||||
---
|
||||
|
||||
import TauriBuild from './\_tauri-build.md'
|
||||
|
||||
# macOS Bundle
|
||||
|
||||
Tauri applications for macOS are distributed either with an [Application Bundle] (`.app` file) or an Apple Disk Image (`.dmg` file). The Tauri CLI automatically bundles your application code in these formats, providing options to codesign and notarize your application. Please note that `.app` and `.dmg` bundles can **only be created on macOS** as cross-compilation doesn't work yet.
|
||||
|
||||
:::note
|
||||
|
||||
GUI apps on macOS and Linux do not inherit the `$PATH` from your shell dotfiles (`.bashrc`, `.bash_profile`, `.zshrc`, etc). Check out Tauri's [fix-path-env-rs] crate to fix this issue.
|
||||
|
||||
:::
|
||||
|
||||
<TauriBuild />
|
||||
|
||||
## Setting a Minimum System Version
|
||||
|
||||
The minimum version of the operating system required for a Tauri app to run on macOS is `10.13`. If you need support for newer macOS APIs like `window.print` that is only supported from macOS version `11.0` onwards, you can change the [`tauri.bundle.macOS.minimumSystemVersion`]. This will in turn set the `Info.plist` [LSMinimumSystemVersion] property and the `MACOSX_DEPLOYMENT_TARGET` environment variable.
|
||||
|
||||
## Binary Targets
|
||||
|
||||
You can compile your application targeting Apple Silicon, Intel-based Mac computers, or universal macOS binaries. By default, the CLI builds a binary targeting your machine's architecture. If you want to build for a different target you must first install the missing rust target for that target by running `rustup target add aarch64-apple-darwin` or `rustup target add x86_64-apple-darwin`, then you can build your app using the `--target` flag:
|
||||
|
||||
- `tauri build --target aarch64-apple-darwin`: targets Apple silicon machines.
|
||||
- `tauri build --target x86_64-apple-darwin`: targets Intel-based machines.
|
||||
- `tauri build --target universal-apple-darwin`: produces a [universal macOS binary] that runs on both Apple silicon and Intel-based Macs.
|
||||
|
||||
While Apple silicon machines can run applications compiled for Intel-based Macs through a translation layer called [Rosetta], this leads to a reduction in performance due to processor instruction translations. It is common practice to let the user choose the correct target when downloading the app, but you can also choose to distribute a [Universal Binary][universal macos binary]. Universal Binaries include both `aarch64` and `x86_64` executables, giving you the best experience on both architectures. Note, however, that this increases your bundle size significantly.
|
||||
|
||||
## Application Bundle Customization
|
||||
|
||||
The Tauri configuration file provides the following options to customize your application bundle:
|
||||
|
||||
- **Bundle name:** Your app's human-readable name. Configured by the [`package.productName`] property.
|
||||
- **Bundle version:** Your app's version. Configured by the [`package.version`] property.
|
||||
- **Application category:** The category that describes your app. Configured by the [`tauri.bundle.category`] property. You can see a list of macOS categories [here][macos app categories].
|
||||
- **Copyright:** A copyright string associated with your app. Configured by the [`tauri.bundle.copyright`] property.
|
||||
- **Bundle icon:** Your app's icon. Uses the first `.icns` file listed in the [`tauri.bundle.icon`] array.
|
||||
- **Minimum system version:** Configured by the [`tauri.bundle.macOS.minimumSystemVersion`] property.
|
||||
- **DMG license file:** A license that is added to the `.dmg` file. Configure by the [`tauri.bundle.macOS.license`] property.
|
||||
- **[Entitlements.plist file]:** Entitlements control what APIs your app will have access to. Configured by the [`tauri.bundle.macOS.entitlements`] property.
|
||||
- **Exception domain:** an insecure domain that your application can access such as a `localhost` or a remote `http` domain. It is a convenience configuration around `NSAppTransportSecurity > NSExceptionDomains` setting `NSExceptionAllowsInsecureHTTPLoads` and `NSIncludesSubdomains` to true. See [`tauri.bundle.macOS.exceptionDomain`] for more information.
|
||||
|
||||
:::info
|
||||
|
||||
These options generate the application bundle [Info.plist file]. You can extend the generated file with your own `Info.plist` file stored in the Tauri folder (`src-tauri` by default). The CLI merges both `.plist` files in production, and the core layer embeds it in the binary during development.
|
||||
|
||||
:::
|
||||
|
||||
[application bundle]: https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/BundleTypes/BundleTypes.html
|
||||
[`tauri.bundle.macos.minimumsystemversion`]: ../../api/config.md#macconfig.minimumsystemversion
|
||||
[lsminimumsystemversion]: https://developer.apple.com/documentation/bundleresources/information_property_list/lsminimumsystemversion
|
||||
[apple silicon macs]: https://support.apple.com/en-us/HT211814
|
||||
[universal macos binary]: https://developer.apple.com/documentation/apple-silicon/building-a-universal-macos-binary
|
||||
[rosetta]: https://support.apple.com/en-gb/HT211861
|
||||
[macos app categories]: https://developer.apple.com/app-store/categories/
|
||||
[`package.productname`]: ../../api/config.md#packageconfig.productname
|
||||
[`package.version`]: ../../api/config.md#packageconfig.version
|
||||
[`tauri.bundle.category`]: ../../api/config.md#bundleconfig.category
|
||||
[`tauri.bundle.copyright`]: ../../api/config.md#bundleconfig.copyright
|
||||
[`tauri.bundle.icon`]: ../../api/config.md#bundleconfig.icon
|
||||
[`tauri.bundle.macos.license`]: ../../api/config.md#bundleconfig.icon
|
||||
[entitlements.plist file]: https://developer.apple.com/documentation/bundleresources/entitlements
|
||||
[`tauri.bundle.macos.entitlements`]: ../../api/config.md#macconfig.entitlements
|
||||
[`tauri.bundle.macos.exceptiondomain`]: ../../api/config.md#macconfig.exceptiondomain
|
||||
[info.plist file]: https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Introduction/Introduction.html
|
||||
[fix-path-env-rs]: https://github.com/tauri-apps/fix-path-env-rs
|
||||
@@ -1,108 +0,0 @@
|
||||
---
|
||||
title: embedding additional resources
|
||||
---
|
||||
|
||||
# Embedding Additional Files
|
||||
|
||||
You may need to include additional files in your application bundle that aren't part of your frontend (your `distDir`) directly or which are too big to be inlined into the binary. We call these files `resources`.
|
||||
|
||||
To bundle the files of your choice, you can add the `resources` property to the `tauri > bundle` object in your `tauri.conf.json` file.
|
||||
|
||||
See more about tauri.conf.json configuration [here][tauri.bundle].
|
||||
|
||||
`resources` expects a list of strings targeting files either with absolute or relative paths. It supports glob patterns in case you need to include multiple files from a directory.
|
||||
|
||||
Here is a sample to illustrate the configuration. This is not a complete `tauri.conf.json` file:
|
||||
|
||||
```json title=tauri.conf.json
|
||||
{
|
||||
"tauri": {
|
||||
"bundle": {
|
||||
"resources": [
|
||||
"/absolute/path/to/textfile.txt",
|
||||
"relative/path/to/jsonfile.json",
|
||||
"resources/*"
|
||||
]
|
||||
},
|
||||
"allowlist": {
|
||||
"fs": {
|
||||
"scope": ["$RESOURCE/*"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
Absolute paths and paths containing parent components (`../`) can only be allowed via `"$RESOURCE/*"`. Relative paths like `"path/to/file.txt"` can be allowed explicitly via `"$RESOURCE/path/to/file.txt"`.
|
||||
|
||||
:::
|
||||
|
||||
## Accessing files in JavaScript
|
||||
|
||||
In this example we want to bundle additional i18n json files that look like this:
|
||||
|
||||
```json title=de.json
|
||||
{
|
||||
"hello": "Guten Tag!",
|
||||
"bye": "Auf Wiedersehen!"
|
||||
}
|
||||
```
|
||||
|
||||
In this case, we store these files in a `lang` directory next to the `tauri.conf.json`. For this we add `"lang/*"` to `resources` and `$RESOURCE/lang/*` to the fs scope as shown above.
|
||||
|
||||
Note that you must configure the allowlist to enable `path > all` and the [`fs` APIs] you need, in this example `fs > readTextFile`.
|
||||
|
||||
```javascript
|
||||
import { resolveResource } from "@tauri-apps/api/path";
|
||||
// alternatively, use `window.__TAURI__.path.resolveResource`
|
||||
import { readTextFile } from "@tauri-apps/api/fs";
|
||||
// alternatively, use `window.__TAURI__.fs.readTextFile`
|
||||
|
||||
// `lang/de.json` is the value specified on `tauri.conf.json > tauri > bundle > resources`
|
||||
const resourcePath = await resolveResource("lang/de.json");
|
||||
const langDe = JSON.parse(await readTextFile(resourcePath));
|
||||
|
||||
console.log(langDe.hello); // This will print 'Guten Tag!' to the devtools console
|
||||
```
|
||||
|
||||
## Accessing files in Rust
|
||||
|
||||
This is based on the example above. On the Rust side, you need an instance of the [`PathResolver`] which you can get from [`App`] and [`AppHandle`]:
|
||||
|
||||
```rust
|
||||
tauri::Builder::default()
|
||||
.setup(|app| {
|
||||
let resource_path = app.path_resolver()
|
||||
.resolve_resource("lang/de.json")
|
||||
.expect("failed to resolve resource");
|
||||
|
||||
let file = std::fs::File::open(&resource_path).unwrap();
|
||||
let lang_de: serde_json::Value = serde_json::from_reader(file).unwrap();
|
||||
|
||||
println!("{}", lang_de.get("hello").unwrap()); // This will print 'Guten Tag!' to the terminal
|
||||
|
||||
Ok(())
|
||||
})
|
||||
```
|
||||
|
||||
```rust
|
||||
#[tauri::command]
|
||||
fn hello(handle: tauri::AppHandle) -> String {
|
||||
let resource_path = handle.path_resolver()
|
||||
.resolve_resource("lang/de.json")
|
||||
.expect("failed to resolve resource");
|
||||
|
||||
let file = std::fs::File::open(&resource_path).unwrap();
|
||||
let lang_de: serde_json::Value = serde_json::from_reader(file).unwrap();
|
||||
|
||||
lang_de.get("hello").unwrap()
|
||||
}
|
||||
```
|
||||
|
||||
[tauri.bundle]: ../../api/config.md#tauri.bundle
|
||||
[`fs` apis]: ../../api/js/fs/
|
||||
[`pathresolver`]: https://docs.rs/tauri/latest/tauri/struct.PathResolver.html
|
||||
[`app`]: https://docs.rs/tauri/latest/tauri/struct.App.html
|
||||
[`apphandle`]: https://docs.rs/tauri/latest/tauri/struct.AppHandle.html
|
||||
@@ -1,194 +0,0 @@
|
||||
---
|
||||
title: embedding external binaries
|
||||
---
|
||||
|
||||
# Embedding External Binaries
|
||||
|
||||
You may need to embed depending binaries to make your application work or prevent users from installing additional dependencies (e.g., Node.js or Python).
|
||||
We call this binary a `sidecar`.
|
||||
|
||||
To bundle the binaries of your choice, you can add the `externalBin` property to the `tauri > bundle` object in your `tauri.conf.json`.
|
||||
|
||||
See more about tauri.conf.json configuration [here][tauri.bundle].
|
||||
|
||||
`externalBin` expects a list of strings targeting binaries either with absolute or relative paths.
|
||||
|
||||
Here is a sample to illustrate the configuration. This is not a complete `tauri.conf.json` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"bundle": {
|
||||
"externalBin": [
|
||||
"/absolute/path/to/sidecar",
|
||||
"relative/path/to/binary",
|
||||
"binaries/my-sidecar"
|
||||
]
|
||||
},
|
||||
"allowlist": {
|
||||
"shell": {
|
||||
"sidecar": true,
|
||||
"scope": [
|
||||
{ "name": "/absolute/path/to/sidecar", "sidecar": true },
|
||||
{ "name": "relative/path/to/binary", "sidecar": true },
|
||||
{ "name": "binaries/my-sidecar", "sidecar": true }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A binary with the same name and a `-$TARGET_TRIPLE` suffix must exist on the specified path. For instance, `"externalBin": ["binaries/my-sidecar"]` requires a `src-tauri/binaries/my-sidecar-x86_64-unknown-linux-gnu` executable on Linux. You can find the **current** platform's target triple by looking at the `host:` property reported by the `rustc -Vv` command.
|
||||
|
||||
If the `grep` and `cut` commands are available, as they should on most Unix systems, you can extract the target triple directly with the following command:
|
||||
|
||||
```shell
|
||||
rustc -Vv | grep host | cut -f2 -d' '
|
||||
```
|
||||
|
||||
On Windows you can use PowerShell instead:
|
||||
|
||||
```powershell
|
||||
rustc -Vv | Select-String "host:" | ForEach-Object {$_.Line.split(" ")[1]}
|
||||
```
|
||||
|
||||
Here's a Node.js script to append the target triple to a binary:
|
||||
|
||||
```javascript
|
||||
const execa = require("execa");
|
||||
const fs = require("fs");
|
||||
|
||||
let extension = "";
|
||||
if (process.platform === "win32") {
|
||||
extension = ".exe";
|
||||
}
|
||||
|
||||
async function main() {
|
||||
const rustInfo = (await execa("rustc", ["-vV"])).stdout;
|
||||
const targetTriple = /host: (\S+)/g.exec(rustInfo)[1];
|
||||
if (!targetTriple) {
|
||||
console.error("Failed to determine platform target triple");
|
||||
}
|
||||
fs.renameSync(
|
||||
`src-tauri/binaries/sidecar${extension}`,
|
||||
`src-tauri/binaries/sidecar-${targetTriple}${extension}`
|
||||
);
|
||||
}
|
||||
|
||||
main().catch((e) => {
|
||||
throw e;
|
||||
});
|
||||
```
|
||||
|
||||
## Running it from JavaScript
|
||||
|
||||
In the JavaScript code, import the `Command` class on the `shell` module and use the `sidecar` static method.
|
||||
|
||||
Note that you must configure the allowlist to enable `shell > sidecar` and configure all binaries in `shell > scope`.
|
||||
|
||||
```javascript
|
||||
import { Command } from "@tauri-apps/api/shell";
|
||||
// alternatively, use `window.__TAURI__.shell.Command`
|
||||
// `binaries/my-sidecar` is the EXACT value specified on `tauri.conf.json > tauri > bundle > externalBin`
|
||||
const command = Command.sidecar("binaries/my-sidecar");
|
||||
const output = await command.execute();
|
||||
```
|
||||
|
||||
## Running it from Rust
|
||||
|
||||
On the Rust side, import the `Command` struct from the `tauri::api::process` module:
|
||||
|
||||
```rust
|
||||
// `new_sidecar()` expects just the filename, NOT the whole path like in JavaScript
|
||||
let (mut rx, mut child) = Command::new_sidecar("my-sidecar")
|
||||
.expect("failed to create `my-sidecar` binary command")
|
||||
.spawn()
|
||||
.expect("Failed to spawn sidecar");
|
||||
|
||||
tauri::async_runtime::spawn(async move {
|
||||
// read events such as stdout
|
||||
while let Some(event) = rx.recv().await {
|
||||
if let CommandEvent::Stdout(line) = event {
|
||||
window
|
||||
.emit("message", Some(format!("'{}'", line)))
|
||||
.expect("failed to emit event");
|
||||
// write to stdin
|
||||
child.write("message from Rust\n".as_bytes()).unwrap();
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
Note that you must enable the **process-command-api** Cargo feature (Tauri's CLI will do this for you once you changed the config):
|
||||
|
||||
```toml
|
||||
# Cargo.toml
|
||||
[dependencies]
|
||||
tauri = { version = "1", features = ["process-command-api", ...] }
|
||||
```
|
||||
|
||||
## Passing arguments
|
||||
|
||||
You can pass arguments to Sidecar commands just like you would for running normal `Command`s (see [Restricting access to the Command APIs]).
|
||||
|
||||
First, define the arguments that need to be passed to the Sidecar command in `tauri.conf.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"bundle": {
|
||||
"externalBin": [
|
||||
"/absolute/path/to/sidecar",
|
||||
"relative/path/to/binary",
|
||||
"binaries/my-sidecar"
|
||||
]
|
||||
},
|
||||
"allowlist": {
|
||||
"shell": {
|
||||
"sidecar": true,
|
||||
"scope": [
|
||||
{
|
||||
"name": "binaries/my-sidecar",
|
||||
"sidecar": true,
|
||||
"args": [
|
||||
"arg1",
|
||||
"-a",
|
||||
"--arg2",
|
||||
{
|
||||
"validator": "\\S+"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then, to call the sidecar command, simply pass in **all** the arguments as an array:
|
||||
|
||||
```js
|
||||
import { Command } from "@tauri-apps/api/shell";
|
||||
// alternatively, use `window.__TAURI__.shell.Command`
|
||||
// `binaries/my-sidecar` is the EXACT value specified on `tauri.conf.json > tauri > bundle > externalBin`
|
||||
// notice that the args array matches EXACTLY what is specified on `tauri.conf.json`.
|
||||
const command = Command.sidecar("binaries/my-sidecar", [
|
||||
"arg1",
|
||||
"-a",
|
||||
"--arg2",
|
||||
"any-string-that-matches-the-validator",
|
||||
]);
|
||||
const output = await command.execute();
|
||||
```
|
||||
|
||||
## Using Node.js on a Sidecar
|
||||
|
||||
The Tauri [sidecar example] demonstrates how to use the sidecar API to run a Node.js application on Tauri.
|
||||
It compiles the Node.js code using [pkg] and uses the scripts above to run it.
|
||||
|
||||
[tauri.bundle]: ../../api/config.md#tauri.bundle
|
||||
[sidecar example]: https://github.com/tauri-apps/tauri/tree/1.x/examples/sidecar
|
||||
[restricting access to the command apis]: ../../api/js/shell.md#restricting-access-to-the-command-apis
|
||||
[pkg]: https://github.com/vercel/pkg
|
||||
@@ -1,380 +0,0 @@
|
||||
---
|
||||
title: windows installer
|
||||
---
|
||||
|
||||
import Command from '@theme/Command'
|
||||
|
||||
# Windows Installer
|
||||
|
||||
Tauri applications for Windows are either distributed as Microsoft Installers (`.msi` files) using the [WiX Toolset v3] or starting with Tauri v1.3 as setup executables (`-setup.exe` files) using [NSIS]. The Tauri CLI bundles your application binary and additional resources. Please note that `.msi` installers can **only be created on Windows** as cross-compilation doesn't work yet. Cross-compilation for NSIS installers is experimental and being worked on.
|
||||
|
||||
This guide provides information about available customization options for the installer.
|
||||
|
||||
To build and bundle your whole Tauri application into a single installer simply run the following command:
|
||||
|
||||
<Command name="build" shell="powershell"/>
|
||||
|
||||
It will build your Frontend, compile the Rust binary, collect all external binaries and resources and finally produce neat platform-specific bundles and installers.
|
||||
|
||||
## Building for 32-bit or ARM
|
||||
|
||||
The Tauri CLI compiles your executable using your machine's architecture by default. Assuming that you're developing on a 64-bit machine, the CLI will produce 64-bit applications.
|
||||
|
||||
If you need to support **32-bit** machines, you can compile your application with a **different** [Rust target][platform support] using the `--target` flag:
|
||||
|
||||
```powershell
|
||||
tauri build --target i686-pc-windows-msvc
|
||||
```
|
||||
|
||||
By default, Rust only installs toolchains for your machine's target, so you need to install the 32-bit Windows toolchain first: `rustup target add i686-pc-windows-msvc`.
|
||||
|
||||
If you need to build for **ARM64** you first need to install additional build tools. To do this, open `Visual Studio Installer`, click on "Modify", and in the "Individual Components" tab install the "C++ ARM64 build tools". At the time of writing, the exact name in VS2022 is `MSVC v143 - VS 2022 C++ ARM64 build tools (Latest)`.
|
||||
Now you can add the rust target with `rustup target add aarch64-pc-windows-msvc` and then use the above-mentioned method to compile your app:
|
||||
|
||||
```powershell
|
||||
tauri build --target aarch64-pc-windows-msvc
|
||||
```
|
||||
|
||||
:::info
|
||||
|
||||
Only the NSIS target supports ARM64 targets, so if you configured tauri to compile all bundle types you may want to change the above command to `tauri build --target aarch64-pc-windows-msvc --bundles nsis` to only build the NSIS installer.
|
||||
|
||||
Note that the installer itself will still be x86 running on the ARM machine via emulation. The app itself will be a native ARM64 binary.
|
||||
|
||||
:::
|
||||
|
||||
## Supporting Windows 7
|
||||
|
||||
By default, the Microsoft Installer (`.msi`) does not work on Windows 7 because it needs to download the WebView2 bootstrapper if not installed (which might fail if TLS 1.2 is not enabled in the operating system). Tauri includes an option to embed the WebView2 bootstrapper (see the [Embedding the WebView2 Bootstrapper](#embedded-bootstrapper) section below). The NSIS based installer (`-setup.exe`) also supports the `downloadBootstrapper` mode on Windows 7.
|
||||
|
||||
Additionally, to use the Notification API in Windows 7, you need to enable the `windows7-compat` Cargo feature:
|
||||
|
||||
```toml title="Cargo.toml"
|
||||
[dependencies]
|
||||
tauri = { version = "1", features = [ "windows7-compat" ] }
|
||||
```
|
||||
|
||||
## FIPS Compliance
|
||||
|
||||
If your system requires the MSI bundle to be FIPS compliant you can set the `TAURI_FIPS_COMPLIANT` environment variable to `true` before running `tauri build`. In PowerShell you can set it for the current terminal session like this:
|
||||
|
||||
```powershell
|
||||
$env:TAURI_FIPS_COMPLIANT="true"
|
||||
```
|
||||
|
||||
## WebView2 Installation Options
|
||||
|
||||
The installers by default download the WebView2 bootstrapper and executes it if the runtime is not installed. Alternatively, you can embed the bootstrapper, embed the offline installer, or use a fixed WebView2 runtime version. See the following table for a comparison between these methods:
|
||||
|
||||
| Installation Method | Requires Internet Connection? | Additional Installer Size | Notes |
|
||||
| :------------------------------------------------- | :---------------------------- | :------------------------ | :---------------------------------------------------------------------------------------------------------------------- |
|
||||
| [`downloadBootstrapper`](#downloaded-bootstrapper) | Yes | 0MB | `Default` <br /> Results in a smaller installer size, but is not recommended for Windows 7 deployment via `.msi` files. |
|
||||
| [`embedBootstrapper`](#embedded-bootstrapper) | Yes | ~1.8MB | Better support on Windows 7 for `.msi` installers. |
|
||||
| [`offlineInstaller`](#offline-installer) | No | ~127MB | Embeds WebView2 installer. Recommended for offline environments. |
|
||||
| [`fixedVersion`](#fixed-version) | No | ~180MB | Embeds a fixed WebView2 version. |
|
||||
| [`skip`](#skipping-installation) | No | 0MB | ⚠️ Not recommended <br /> Does not install the WebView2 as part of the Windows Installer. |
|
||||
|
||||
:::info
|
||||
|
||||
On Windows 10 (April 2018 release or later) and Windows 11, the WebView2 runtime is distributed as part of the operating system.
|
||||
|
||||
:::
|
||||
|
||||
### Downloaded Bootstrapper
|
||||
|
||||
This is the default setting for building the Windows Installer. It downloads the bootstrapper and runs it. Requires an internet connection but results in a smaller installer size. This is not recommended if you're going to be distributing to Windows 7 via `.msi` installers.
|
||||
|
||||
```json title="tauri.config.json"
|
||||
{
|
||||
"tauri": {
|
||||
"bundle": {
|
||||
"windows": {
|
||||
"webviewInstallMode": {
|
||||
"type": "downloadBootstrapper"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Embedded Bootstrapper
|
||||
|
||||
To embed the WebView2 Bootstrapper, set the [webviewInstallMode] to `embedBootstrapper`. This increases the installer size by around 1.8MB, but increases compatibility with Windows 7 systems.
|
||||
|
||||
```json title="tauri.config.json"
|
||||
{
|
||||
"tauri": {
|
||||
"bundle": {
|
||||
"windows": {
|
||||
"webviewInstallMode": {
|
||||
"type": "embedBootstrapper"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Offline Installer
|
||||
|
||||
To embed the WebView2 Bootstrapper, set the [webviewInstallMode] to `offlineInstaller`. This increases the installer size by around 127MB, but allows your application to be installed even if an internet connection is not available.
|
||||
|
||||
```json title="tauri.config.json"
|
||||
{
|
||||
"tauri": {
|
||||
"bundle": {
|
||||
"windows": {
|
||||
"webviewInstallMode": {
|
||||
"type": "offlineInstaller"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Fixed Version
|
||||
|
||||
Using the runtime provided by the system is great for security as the webview vulnerability patches are managed by Windows. If you want to control the WebView2 distribution on each of your applications (either to manage the release patches yourself or distribute applications on environments where an internet connection might not be available) Tauri can bundle the runtime files for you.
|
||||
|
||||
:::caution
|
||||
|
||||
Distributing a fixed WebView2 Runtime version increases the Windows Installer by around 180MB.
|
||||
|
||||
:::
|
||||
|
||||
1. Download the WebView2 fixed version runtime from [Microsoft's website][download-webview2-runtime]. In this example, the downloaded filename is `Microsoft.WebView2.FixedVersionRuntime.98.0.1108.50.x64.cab`
|
||||
2. Extract the file to the core folder:
|
||||
|
||||
```powershell
|
||||
Expand .\Microsoft.WebView2.FixedVersionRuntime.98.0.1108.50.x64.cab -F:* ./src-tauri
|
||||
```
|
||||
|
||||
3. Configure the WebView2 runtime path in `tauri.conf.json`:
|
||||
|
||||
```json title="tauri.config.json"
|
||||
{
|
||||
"tauri": {
|
||||
"bundle": {
|
||||
"windows": {
|
||||
"webviewInstallMode": {
|
||||
"type": "fixedRuntime",
|
||||
"path": "./Microsoft.WebView2.FixedVersionRuntime.98.0.1108.50.x64/"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
4. Run `tauri build` to produce the Windows Installer with the fixed WebView2 runtime.
|
||||
|
||||
### Skipping Installation
|
||||
|
||||
You can remove the WebView2 Runtime download check from the installer by setting [webviewInstallMode] to `skip`. Your application WILL NOT work if the user does not have the runtime installed.
|
||||
|
||||
:::warning
|
||||
|
||||
Your application WILL NOT work if the user does not have the runtime installed and won't attempt to install it.
|
||||
|
||||
:::
|
||||
|
||||
```json title="tauri.config.json"
|
||||
{
|
||||
"tauri": {
|
||||
"bundle": {
|
||||
"windows": {
|
||||
"webviewInstallMode": {
|
||||
"type": "skip"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Customizing the WiX Installer Template
|
||||
|
||||
The `.msi` Windows Installer package is built using the [WiX Toolset v3]. Currently, apart from pre-defined [configurations](../../api/config.md#wixconfig), you can change it by using a custom WiX source code (an XML file with a `.wxs` file extension) or through WiX fragments.
|
||||
|
||||
### Replacing the Installer Code with a Custom WiX File
|
||||
|
||||
The Windows Installer XML defined by Tauri is configured to work for the common use case of simple webview-based applications (you can find it [here][default wix template]). It uses [handlebars] so the Tauri CLI can brand your installer according to your `tauri.conf.json` definition. If you need a completely different installer, a custom template file can be configured on [`tauri.bundle.windows.wix.template`].
|
||||
|
||||
### Extending the Installer with WiX Fragments
|
||||
|
||||
A [WiX fragment] is a container where you can configure almost everything offered by WiX. In this example, we will define a fragment that writes two registry entries:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
|
||||
<Fragment>
|
||||
<!-- these registry entries should be installed
|
||||
to the target user's machine -->
|
||||
<DirectoryRef Id="TARGETDIR">
|
||||
<!-- groups together the registry entries to be installed -->
|
||||
<!-- Note the unique `Id` we provide here -->
|
||||
<Component Id="MyFragmentRegistryEntries" Guid="*">
|
||||
<!-- the registry key will be under
|
||||
HKEY_CURRENT_USER\Software\MyCompany\MyApplicationName -->
|
||||
<!-- Tauri uses the second portion of the
|
||||
bundle identifier as the `MyCompany` name
|
||||
(e.g. `tauri-apps` in `com.tauri-apps.test`) -->
|
||||
<RegistryKey
|
||||
Root="HKCU"
|
||||
Key="Software\MyCompany\MyApplicationName"
|
||||
Action="createAndRemoveOnUninstall"
|
||||
>
|
||||
<!-- values to persist on the registry -->
|
||||
<RegistryValue
|
||||
Type="integer"
|
||||
Name="SomeIntegerValue"
|
||||
Value="1"
|
||||
KeyPath="yes"
|
||||
/>
|
||||
<RegistryValue Type="string" Value="Default Value" />
|
||||
</RegistryKey>
|
||||
</Component>
|
||||
</DirectoryRef>
|
||||
</Fragment>
|
||||
</Wix>
|
||||
```
|
||||
|
||||
<!-- Would be good to include here WHERE we recommend to save it -->
|
||||
|
||||
Save the fragment file with the `.wxs` extension somewhere in your project and reference it on `tauri.conf.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"bundle": {
|
||||
"windows": {
|
||||
"wix": {
|
||||
"fragmentPaths": ["./path/to/registry.wxs"],
|
||||
"componentRefs": ["MyFragmentRegistryEntries"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Note that `ComponentGroup`, `Component`, `FeatureGroup`, `Feature` and `Merge` element ids must be referenced on the `wix` object of `tauri.conf.json` on the `componentGroupRefs`, `componentRefs`, `featureGroupRefs`, `featureRefs` and `mergeRefs` respectively to be included in the installer.
|
||||
|
||||
## Customizing the NSIS Installer Template
|
||||
|
||||
The NSIS Installer's `.nsi` script defined by Tauri is configured to work for the common use case of simple webview-based applications (you can find it [here][default nsis template]). It uses [handlebars] so the Tauri CLI can brand your installer according to your `tauri.conf.json` definition. If you need a completely different installer, a custom template file can be configured on [`tauri.bundle.windows.nsis.template`] on Tauri v1.4 and above.
|
||||
|
||||
## Internationalization
|
||||
|
||||
The NSIS Installer is a multi-language installer, which means you always have a single installer which contains all the selected translations. You can specify which languages to include using the [`tauri.bundle.windows.nsis.languages`](../../api/config.md#nsisconfig.languages) property. A list of languages supported by NSIS is available in [the NSIS GitHub project]. There are a few [Tauri-specific translations] required, so if you see untranslated texts feel free to open a feature request in [Tauri's main repo]. Starting with v1.4 you can also provide [custom translation files](../../api/config.md#nsisconfig.customlanguagefiles).
|
||||
|
||||
The WiX Installer is built using the `en-US` language by default. Internationalization (i18n) can be configured using the [`tauri.bundle.windows.wix.language`] property, defining the languages Tauri should build an installer against. You can find the language names to use in the Language-Culture column on [Microsoft's website][localizing the error and actiontext tables].
|
||||
|
||||
### Compiling a WiX Installer for a Single Language
|
||||
|
||||
To create a single installer targeting a specific language, set the `language` value to a string:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"bundle": {
|
||||
"windows": {
|
||||
"wix": {
|
||||
"language": "fr-FR"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Compiling a WiX Installer for Each Language in a List
|
||||
|
||||
To compile an installer targeting a list of languages, use an array. A specific installer for each language will be created, with the language key as a suffix:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"bundle": {
|
||||
"windows": {
|
||||
"wix": {
|
||||
"language": ["en-US", "pt-BR", "fr-FR"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Configuring the WiX Installer for Each Language
|
||||
|
||||
A configuration object can be defined for each language to configure localization strings:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"bundle": {
|
||||
"windows": {
|
||||
"wix": {
|
||||
"language": {
|
||||
"en-US": null,
|
||||
"pt-BR": {
|
||||
"localePath": "./wix/locales/pt-BR.wxl"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `localePath` property defines the path to a language file, a XML configuring the language culture:
|
||||
|
||||
```xml
|
||||
<WixLocalization
|
||||
Culture="en-US"
|
||||
xmlns="http://schemas.microsoft.com/wix/2006/localization"
|
||||
>
|
||||
<String Id="LaunchApp"> Launch MyApplicationName </String>
|
||||
<String Id="DowngradeErrorMessage">
|
||||
A newer version of MyApplicationName is already installed.
|
||||
</String>
|
||||
<String Id="PathEnvVarFeature">
|
||||
Add the install location of the MyApplicationName executable to
|
||||
the PATH system environment variable. This allows the
|
||||
MyApplicationName executable to be called from any location.
|
||||
</String>
|
||||
<String Id="InstallAppFeature">
|
||||
Installs MyApplicationName.
|
||||
</String>
|
||||
</WixLocalization>
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
The `WixLocalization` element's `Culture` field must match the configured language.
|
||||
|
||||
:::
|
||||
|
||||
Currently, Tauri references the following locale strings: `LaunchApp`, `DowngradeErrorMessage`, `PathEnvVarFeature` and `InstallAppFeature`. You can define your own strings and reference them on your custom template or fragments with `"!(loc.TheStringId)"`. See the [WiX localization documentation] for more information.
|
||||
|
||||
[wix toolset v3]: https://wixtoolset.org/documentation/manual/v3/
|
||||
[nsis]: https://nsis.sourceforge.io/Main_Page
|
||||
[platform support]: https://doc.rust-lang.org/nightly/rustc/platform-support.html
|
||||
[webviewinstallmode]: ../../api/config.md#webviewinstallmode
|
||||
[download-webview2-runtime]: https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download-section
|
||||
[default wix template]: https://github.com/tauri-apps/tauri/blob/dev/tooling/bundler/src/bundle/windows/templates/main.wxs
|
||||
[default nsis template]: https://github.com/tauri-apps/tauri/blob/dev/tooling/bundler/src/bundle/windows/templates/installer.nsi
|
||||
[handlebars]: https://docs.rs/handlebars/latest/handlebars/
|
||||
[`tauri.bundle.windows.wix.template`]: ../../api/config.md#wixconfig.template
|
||||
[`tauri.bundle.windows.nsis.template`]: ../../api/config.md#nsisconfig.template
|
||||
[wix fragment]: https://wixtoolset.org/documentation/manual/v3/xsd/wix/fragment.html
|
||||
[`tauri.bundle.windows.wix.language`]: ../../api/config.md#wixconfig.language
|
||||
[wix localization documentation]: https://wixtoolset.org/documentation/manual/v3/howtos/ui_and_localization/make_installer_localizable.html
|
||||
[localizing the error and actiontext tables]: https://docs.microsoft.com/en-us/windows/win32/msi/localizing-the-error-and-actiontext-tables
|
||||
[the nsis github project]: https://github.com/kichik/nsis/tree/9465c08046f00ccb6eda985abbdbf52c275c6c4d/Contrib/Language%20files
|
||||
[tauri-specific translations]: https://github.com/tauri-apps/tauri/tree/dev/tooling/bundler/src/bundle/windows/templates/nsis-languages
|
||||
[tauri's main repo]: https://github.com/tauri-apps/tauri/issues/new?assignees=&labels=type%3A+feature+request&template=feature_request.yml&title=%5Bfeat%5D+
|
||||
@@ -1,108 +0,0 @@
|
||||
---
|
||||
title: application debugging
|
||||
---
|
||||
|
||||
import Command from '@theme/Command'
|
||||
|
||||
# Application Debugging
|
||||
|
||||
With all the moving pieces in Tauri, you may run into a problem that requires debugging. There are many locations where error details are printed, and Tauri includes some tools to make the debugging process more straightforward.
|
||||
|
||||
## Rust Console
|
||||
|
||||
The first place to look for errors is in the Rust Console. This is in the terminal where you ran, e.g., `tauri dev`. You can use the following code to print something to that console from within a Rust file:
|
||||
|
||||
```rust
|
||||
println!("Message from Rust: {}", msg);
|
||||
```
|
||||
|
||||
Sometimes you may have an error in your Rust code, and the Rust compiler can give you lots of information. If, for example, `tauri dev` crashes, you can rerun it like this on Linux and macOS:
|
||||
|
||||
```shell
|
||||
RUST_BACKTRACE=1 tauri dev
|
||||
```
|
||||
|
||||
or like this on Windows:
|
||||
|
||||
```shell
|
||||
set RUST_BACKTRACE=1
|
||||
tauri dev
|
||||
```
|
||||
|
||||
This command gives you a granular stack trace. Generally speaking, the Rust compiler helps you by
|
||||
giving you detailed information about the issue, such as:
|
||||
|
||||
```
|
||||
error[E0425]: cannot find value `sun` in this scope
|
||||
--> src/main.rs:11:5
|
||||
|
|
||||
11 | sun += i.to_string().parse::<u64>().unwrap();
|
||||
| ^^^ help: a local variable with a similar name exists: `sum`
|
||||
|
||||
error: aborting due to previous error
|
||||
|
||||
For more information about this error, try `rustc --explain E0425`.
|
||||
```
|
||||
|
||||
## WebView Console
|
||||
|
||||
Right-click in the WebView, and choose `Inspect Element`. This opens up a web-inspector similar to the Chrome or Firefox dev tools you are used to.
|
||||
You can also use the `Ctrl + Shift + i` shortcut on Linux and Windows, and `Command + Option + i` on macOS to open the inspector.
|
||||
|
||||
The inspector is platform-specific, rendering the webkit2gtk WebInspector on Linux, Safari's inspector on macOS and the Microsoft Edge DevTools on Windows.
|
||||
|
||||
### Opening Devtools Programmatically
|
||||
|
||||
You can control the inspector window visibility by using the [`Window::open_devtools`] and [`Window::close_devtools`] functions:
|
||||
|
||||
```rust
|
||||
use tauri::Manager;
|
||||
tauri::Builder::default()
|
||||
.setup(|app| {
|
||||
#[cfg(debug_assertions)] // only include this code on debug builds
|
||||
{
|
||||
let window = app.get_window("main").unwrap();
|
||||
window.open_devtools();
|
||||
window.close_devtools();
|
||||
}
|
||||
Ok(())
|
||||
});
|
||||
```
|
||||
|
||||
### Using the Inspector in Production
|
||||
|
||||
By default, the inspector is only enabled in development and debug builds unless you enable it with a Cargo feature.
|
||||
|
||||
#### Create a Debug Build
|
||||
|
||||
To create a debug build, run the `tauri build --debug` command.
|
||||
|
||||
<Command name="build --debug" />
|
||||
|
||||
Like the normal build and dev processes, building takes some time the first time you run this command but is significantly faster on subsequent runs.
|
||||
The final bundled app has the development console enabled and is placed in `src-tauri/target/debug/bundle`.
|
||||
|
||||
You can also run a built app from the terminal, giving you the Rust compiler notes (in case of errors) or your `println` messages. Browse to the file `src-tauri/target/(release|debug)/[app name]` and run it in directly in your console or double-click the executable itself in the filesystem (note: the console closes on errors with this method).
|
||||
|
||||
#### Enable Devtools Feature
|
||||
|
||||
:::warning
|
||||
|
||||
The devtools API is private on macOS. Using private APIs on macOS prevents your application from being accepted to the App Store.
|
||||
|
||||
:::
|
||||
|
||||
To enable the devtools in production builds, you must enable the `devtools` Cargo feature in the `src-tauri/Cargo.toml` file:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
tauri = { version = "...", features = ["...", "devtools"] }
|
||||
```
|
||||
|
||||
## Debugging the Core Process
|
||||
|
||||
The Core process is powered by Rust so you can use GDB or LLDB to debug it. You can follow the [Debugging in VS Code] guide to learn how to use the LLDB VS Code Extension to debug the Core Process of Tauri applications.
|
||||
|
||||
[debugging in vs code]: ./vs-code.md
|
||||
[`window::open_devtools`]: https://docs.rs/tauri/1/tauri/window/struct.Window.html#method.open_devtools
|
||||
[`window::close_devtools`]: https://docs.rs/tauri/1/tauri/window/struct.Window.html#method.close_devtools
|
||||
@@ -1,61 +0,0 @@
|
||||
---
|
||||
title: clion
|
||||
---
|
||||
|
||||
# Debugging in CLion
|
||||
|
||||
In this guide, we’ll be setting up IntelliJ CLion for debugging the [Core Process of your Tauri app].
|
||||
|
||||
## Prerequisites
|
||||
|
||||
You need to install the [IntelliJ Rust Plugin](https://plugins.jetbrains.com/plugin/8182-rust/docs) so that Rust features are enabled.
|
||||
|
||||
## Top-level Cargo Workspace
|
||||
|
||||
By default, Tauri places the Rust project in a subdirectory called `src-tauri`. CLion may not recognize Cargo projects that are not at the top-level, in which case you should be able to attach it by using `Cargo -> Attach Cargo project`. If this option does not work, you will need to create a top-level Workspace that just points to the main `Cargo.toml` file:
|
||||
|
||||
```toml title=Cargo.toml
|
||||
[workspace]
|
||||
members = ["src-tauri"]
|
||||
```
|
||||
|
||||
Before you proceed, make sure that your project is fully loaded. If the indexing is finished and the Cargo tool window shows all the modules and targets of the workspace, you’re good to go.
|
||||
|
||||
## Run/Debug Configuration
|
||||
|
||||
We will set up a Run/Debug configuration that we can use to launch our Tauri app in debugging mode. To create a configuration, go to Edit Configurations, click **+**, and then select Cargo Command.
|
||||
|
||||
|
||||
|
||||
|
||||
With that created we need to configure CLion so it instructs Cargo to build our app without any default features. This will tell Tauri to use your development server instead of reading assets from disk. Normally this flag is passed by the Tauri CLI, but since we're completely sidestepping that here, we need to pass the flag manually.
|
||||
|
||||
|
||||
|
||||
|
||||
Now we can optionally rename the Run/Debug Configuration to something more memorable, in this example we called it "Run Tauri App", but you can name it whatever you want.
|
||||
|
||||
|
||||
|
||||
|
||||
:::caution
|
||||
|
||||
On Windows you must also make sure that CLion uses the correct debugger toolchain. To do this, open the Settings (`File -> Settings...`), select `Build, Execution, Deployment -> Toolchains` and move the `Visual Studio` toolchain to the top.
|
||||
|
||||
:::
|
||||
|
||||
## Launch the Development Server
|
||||
|
||||
The above configuration will use Cargo directly to build the Rust application and attach the debugger to it. This means we completely sidestep the Tauri CLI, so features like the `beforeDevCommand` and `beforeBuildCommand` will **not** be executed. We need to take care of that by opening a new Terminal and starting running the development server manually:
|
||||
|
||||
```sh
|
||||
pnpm vite dev
|
||||
```
|
||||
|
||||
> Note that CLion currently has no support for background tasks in Run/Debug configurations like VS Code has, so for now you need to manually run the development server.
|
||||
|
||||
## Launch a Debugging Session
|
||||
|
||||
With the development server running and the Run/Debug Configuration selected in the Switcher, you can now start a new debugging session by clicking Debug. CLion will automatically recognize breakpoints placed in any Rust file in your project.
|
||||
|
||||
[core process of your tauri app]: ../../references/architecture/process-model.md#the-core-process
|
||||
@@ -1,88 +0,0 @@
|
||||
---
|
||||
title: vs code
|
||||
---
|
||||
|
||||
# Debugging in VS Code
|
||||
|
||||
This guide will walk you through setting up VS Code for debugging the [Core Process of your Tauri app].
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Install the [`vscode-lldb`] extension.
|
||||
|
||||
[`vscode-lldb`]: https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb
|
||||
|
||||
## Configure launch.json
|
||||
|
||||
Create a `.vscode/launch.json` file and paste the below JSON contents into it:
|
||||
|
||||
```json title=".vscode/launch.json"
|
||||
{
|
||||
// Use IntelliSense to learn about possible attributes.
|
||||
// Hover to view descriptions of existing attributes.
|
||||
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"type": "lldb",
|
||||
"request": "launch",
|
||||
"name": "Tauri Development Debug",
|
||||
"cargo": {
|
||||
"args": [
|
||||
"build",
|
||||
"--manifest-path=./src-tauri/Cargo.toml",
|
||||
"--no-default-features"
|
||||
]
|
||||
},
|
||||
// task for the `beforeDevCommand` if used, must be configured in `.vscode/tasks.json`
|
||||
"preLaunchTask": "ui:dev"
|
||||
},
|
||||
{
|
||||
"type": "lldb",
|
||||
"request": "launch",
|
||||
"name": "Tauri Production Debug",
|
||||
"cargo": {
|
||||
"args": ["build", "--release", "--manifest-path=./src-tauri/Cargo.toml"]
|
||||
},
|
||||
// task for the `beforeBuildCommand` if used, must be configured in `.vscode/tasks.json`
|
||||
"preLaunchTask": "ui:build"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
This uses `cargo` directly to build the Rust application and load it in both development and production modes.
|
||||
|
||||
Note that it does not use the Tauri CLI, so exclusive CLI features are not executed. The `beforeDevCommand` and `beforeBuildCommand` scripts must be executed beforehand or configured as a task in the `preLaunchTask` field. Below is an example `.vscode/tasks.json` file that has two tasks, one for a `beforeDevCommand` that spawns a development server and one for `beforeBuildCommand`:
|
||||
|
||||
```json title=".vscode/tasks.json"
|
||||
{
|
||||
// See https://go.microsoft.com/fwlink/?LinkId=733558
|
||||
// for the documentation about the tasks.json format
|
||||
"version": "2.0.0",
|
||||
"tasks": [
|
||||
{
|
||||
"label": "ui:dev",
|
||||
"type": "shell",
|
||||
// `dev` keeps running in the background
|
||||
// ideally you should also configure a `problemMatcher`
|
||||
// see https://code.visualstudio.com/docs/editor/tasks#_can-a-background-task-be-used-as-a-prelaunchtask-in-launchjson
|
||||
"isBackground": true,
|
||||
// change this to your `beforeDevCommand`:
|
||||
"command": "yarn",
|
||||
"args": ["dev"]
|
||||
},
|
||||
{
|
||||
"label": "ui:build",
|
||||
"type": "shell",
|
||||
// change this to your `beforeBuildCommand`:
|
||||
"command": "yarn",
|
||||
"args": ["build"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Now you can set breakpoints in `src-tauri/src/main.rs` or any other Rust file and start debugging by pressing `F5`.
|
||||
|
||||
[core process of your tauri app]: ../../references/architecture/process-model.md#the-core-process
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
title: development cycle
|
||||
---
|
||||
|
||||
import Command from '@theme/Command'
|
||||
|
||||
# Development Cycle
|
||||
|
||||
### 1. Start Your Dev server
|
||||
|
||||
Now that you have everything set up, you should start your application development server provided by your UI framework or bundler (assuming you're using one, of course).
|
||||
|
||||
:::note
|
||||
|
||||
Every framework has its own development tooling. It is outside of the scope of this document to cover them all or stay up to date.
|
||||
:::
|
||||
|
||||
### 2. Start Tauri Development Window
|
||||
|
||||
<Command name="dev" />
|
||||
|
||||
The first time you run this command, the Rust package manager takes several minutes to download and build all the required packages. Since they are cached, subsequent builds are much faster, as only your code needs rebuilding.
|
||||
|
||||
Once Rust has finished building, the webview opens, displaying your web app. You can make changes to your web app, and if your tooling enables it, the webview should update automatically, just like a browser. When you make changes to your Rust files, they are rebuilt automatically, and your app automatically restarts.
|
||||
|
||||
:::info About Cargo.toml and Source Control
|
||||
|
||||
In your project repository, you SHOULD commit the "src-tauri/Cargo.lock" along with the "src-tauri/Cargo.toml" to git because Cargo uses the lockfile to provide deterministic builds. As a result, it is recommended that all applications check in their Cargo.lock. You SHOULD NOT commit the "src-tauri/target" folder or any of its contents.
|
||||
|
||||
:::
|
||||
@@ -1,132 +0,0 @@
|
||||
---
|
||||
title: updating dependencies
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs'
|
||||
import TabItem from '@theme/TabItem'
|
||||
|
||||
# Updating Dependencies
|
||||
|
||||
## Update npm Packages
|
||||
|
||||
If you are using the `tauri` package:
|
||||
|
||||
<Tabs groupId="package-manager">
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm install @tauri-apps/cli@latest @tauri-apps/api@latest
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Yarn Classic">
|
||||
|
||||
```shell
|
||||
yarn upgrade @tauri-apps/cli @tauri-apps/api --latest
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Yarn Berry">
|
||||
|
||||
```shell
|
||||
yarn up @tauri-apps/cli @tauri-apps/api
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="pnpm">
|
||||
|
||||
```shell
|
||||
pnpm update @tauri-apps/cli @tauri-apps/api --latest
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
You can also detect what the latest version of Tauri is on the command line, using:
|
||||
|
||||
<Tabs groupId="package-manager">
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm outdated @tauri-apps/cli
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Yarn">
|
||||
|
||||
```shell
|
||||
yarn outdated @tauri-apps/cli
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="pnpm">
|
||||
|
||||
```shell
|
||||
pnpm outdated @tauri-apps/cli
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
Alternatively, if you are using the `vue-cli-plugin-tauri` approach:
|
||||
|
||||
<Tabs groupId="package-manager">
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm install vue-cli-plugin-tauri@latest
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Yarn Classic">
|
||||
|
||||
```shell
|
||||
yarn upgrade vue-cli-plugin-tauri --latest
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Yarn Berry">
|
||||
|
||||
```shell
|
||||
yarn up vue-cli-plugin-tauri
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="pnpm">
|
||||
|
||||
```shell
|
||||
pnpm update vue-cli-plugin-tauri --latest
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Update Cargo Packages
|
||||
|
||||
You can check for outdated packages with [`cargo outdated`] or on the crates.io pages: [tauri] / [tauri-build].
|
||||
|
||||
Go to `src-tauri/Cargo.toml` and change `tauri` and `tauri-build` to
|
||||
|
||||
```toml
|
||||
[build-dependencies]
|
||||
tauri-build = "%version%"
|
||||
|
||||
[dependencies]
|
||||
tauri = { version = "%version%" }
|
||||
```
|
||||
|
||||
where `%version%` is the corresponding version number from above. <!-- TODO: (You can just use the `MAJOR.MINOR`) version, like `0.9`. -->
|
||||
|
||||
Then do the following:
|
||||
|
||||
```shell
|
||||
cd src-tauri
|
||||
cargo update
|
||||
```
|
||||
|
||||
Alternatively, you can run the `cargo upgrade` command provided by [cargo-edit] which does all of this automatically.
|
||||
|
||||
[`cargo outdated`]: https://github.com/kbknapp/cargo-outdated
|
||||
[tauri]: https://crates.io/crates/tauri/versions
|
||||
[tauri-build]: https://crates.io/crates/tauri-build/versions
|
||||
[cargo-edit]: https://github.com/killercup/cargo-edit
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
title: app publishing
|
||||
---
|
||||
|
||||
import Command from '@theme/Command'
|
||||
|
||||
# App Publishing
|
||||
|
||||
### 1. Build Your Web App
|
||||
|
||||
Now that you are ready to package your project, you need to run your framework's or bundler's build command (assuming you're using one, of course).
|
||||
|
||||
:::note
|
||||
|
||||
Every framework has its publishing tooling. It is outside of the scope of this document to treat them all or keep them up to date.
|
||||
|
||||
:::
|
||||
|
||||
### 2. Bundle your application with Tauri
|
||||
|
||||
<Command name="build" />
|
||||
|
||||
This command embeds your web assets into a single binary with your Rust code. The binary itself will be located in `src-tauri/target/release/[app name]`, and installers will be located in `src-tauri/target/release/bundle/`.
|
||||
|
||||
Like the `tauri dev` command, the first time you run this, it takes some time to collect the Rust crates and build everything - but on subsequent runs, it only needs to rebuild your app's code, which is much quicker.
|
||||
@@ -1,45 +0,0 @@
|
||||
---
|
||||
title: linux code signing
|
||||
---
|
||||
|
||||
# Code Signing Linux packages
|
||||
|
||||
This guide provides information on code signing for Linux packages.
|
||||
|
||||
## Requirements
|
||||
|
||||
- gpg or gpg2
|
||||
|
||||
A key for signing must be prepared. A new one can be generated using:
|
||||
|
||||
```shell
|
||||
gpg2 --full-gen-key
|
||||
```
|
||||
|
||||
Please refer to the gpg or gpg2 documentation for additional information.
|
||||
You should take additional care to back up your private and public keys in a secure location.
|
||||
|
||||
## Signing for AppImages
|
||||
|
||||
You can embed a signature in the AppImage by setting the following environment variables:
|
||||
|
||||
- **SIGN**: set to `1` to sign the AppImage.
|
||||
- **SIGN_KEY**: optional variable to use a specific GPG Key ID for signing.
|
||||
- **APPIMAGETOOL_SIGN_PASSPHRASE**: the signing key password. If unset, gpg shows a dialog so you can input it. You must set this when running automated tasks.
|
||||
|
||||
You can display the signature embedded in the AppImage by running the following command:
|
||||
|
||||
```shell
|
||||
./src-tauri/target/release/bundle/appimage/$APPNAME_$VERSION_amd64.AppImage --appimage-signature
|
||||
```
|
||||
|
||||
Note that you need to change the $APPNAME and $VERSION values with the correct ones based on your configuration.
|
||||
|
||||
:::caution The signature is not verified
|
||||
|
||||
AppImage does not validate the signature, so you can't rely on it to check whether the file has been tampered with or not.
|
||||
To validate the signature, you must provide an external tool for your users. See [the official AppImage documentation] for additional information.
|
||||
|
||||
:::
|
||||
|
||||
[the official appimage documentation]: https://docs.appimage.org/packaging-guide/optional/signatures.html
|
||||
@@ -1,174 +0,0 @@
|
||||
---
|
||||
title: code sign macOS
|
||||
---
|
||||
|
||||
# Code Signing macOS Applications
|
||||
|
||||
This guide provides information on code signing and notarization for macOS applications.
|
||||
|
||||
:::note
|
||||
|
||||
If you are not utilizing GitHub Actions to perform builds of OSX DMGs, you will need to ensure the environment variable <i>CI=true</i> exists. For more information refer to [tauri-apps/tauri#592].
|
||||
|
||||
:::
|
||||
|
||||
## Requirements
|
||||
|
||||
- macOS 10.13.6 or later
|
||||
- Xcode 10 or later
|
||||
- An Apple Developer account enrolled in the [Apple Developer Program]
|
||||
|
||||
For more details please read the developer article on [notarizing macOS software before distribution].
|
||||
|
||||
## tl;dr
|
||||
|
||||
The Tauri code signing and notarization process is configured through the following environment variables:
|
||||
|
||||
- `APPLE_SIGNING_IDENTITY`: the name of the keychain entry that contains the signing certificate.
|
||||
- `APPLE_CERTIFICATE`: base64 string of the `.p12` certificate, exported from the keychain. Useful if you don't have the certificate on the keychain (e.g., CI machines).
|
||||
- `APPLE_CERTIFICATE_PASSWORD`: the password for the `.p12` certificate.
|
||||
- `APPLE_ID` and `APPLE_PASSWORD`: your Apple account email and an [app-specific password]. Only required to notarize the app.
|
||||
- `APPLE_API_ISSUER` and `APPLE_API_KEY`: authentication with an App Store Connect API key instead of the Apple ID. Only required if you notarize the app.
|
||||
- `APPLE_PROVIDER_SHORT_NAME`: Team provider short name. If your Apple ID is connected to multiple teams, you have to specify the provider short name of the team you want to use to notarize your app. You can list your account providers using `xcrun altool --list-providers -u "AC_USERNAME" -p "AC_PASSWORD"` as explained in the notarization [workflow](https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/customizing_the_notarization_workflow).
|
||||
|
||||
## Signing Tauri apps
|
||||
|
||||
The first step to signing a macOS application is getting a signing certificate from the Apple Developer Program.
|
||||
|
||||
### Creating a signing certificate
|
||||
|
||||
To create a new signing certificate, you must generate a Certificate Signing Request (CSR) file from your Mac computer. [Create a certificate signing request] describes creating a CSR.
|
||||
|
||||
On your Apple Developer account, navigate to the [Certificates, IDs & Profiles page] and click on the `Create a certificate` button to open the interface to create a new certificate. Choose the appropriate certificate type (`Apple Distribution` to submit apps to the App Store, and `Developer ID Application` to ship apps outside the App Store). Upload your CSR, and the certificate will be created.
|
||||
|
||||
:::note
|
||||
|
||||
Only the Apple Developer `Account Holder` can create _Developer ID Application_ certificates. But it can be associated with a different Apple ID by creating a CSR with a different user email address.
|
||||
|
||||
:::
|
||||
|
||||
### Downloading a certificate
|
||||
|
||||
On the [Certificates, IDs & Profiles page], click on the certificate you want to use and click on the `Download` button. It saves a `.cer` file that installs the certificate on the keychain once opened. The name of the keychain entry represents the `signing identity`, which can also be found by executing `security find-identity -v -p codesigning`.
|
||||
|
||||
:::note
|
||||
|
||||
A signing certificate is only valid if associated with your Apple ID. An invalid certificate won't be listed on the <i>Keychain Access > My Certificates</i> tab or the <i>security find-identity -v -p codesigning</i> output. If the certificate does not download to the correct location, make sure the "login" option is selected in <i>Keychain Access</i> under "Default Keychains" when downloading the .cer file.
|
||||
|
||||
:::
|
||||
|
||||
### Signing the Tauri application
|
||||
|
||||
The signing configuration is provided to the Tauri bundler via environment variables. You need to configure the certificate to use and an optional authentication configuration to notarize the application.
|
||||
|
||||
#### Certificate environment variables
|
||||
|
||||
- `APPLE_SIGNING_IDENTITY`: this is the `signing identity` we highlighted above. It must be defined to sign apps both locally and on CI machines.
|
||||
|
||||
Additionally, to simplify the code signing process on CI, Tauri can install the certificate on the keychain for you if you define the `APPLE_CERTIFICATE` and `APPLE_CERTIFICATE_PASSWORD` environment variables.
|
||||
|
||||
1. Open the `Keychain Access` app to <i>login > My Certificates</i> and find your certificate's keychain entry.
|
||||
2. Expand the entry, double-click on the key item, and select `Export "$KEYNAME"`.
|
||||
3. Select the path to save the `.p12` file and define the exported certificate password.
|
||||
4. Convert the `.p12` file to base64 running the following script on the terminal: `openssl base64 -in /path/to/certificate.p12 -out certificate-base64.txt`.
|
||||
5. Set the contents of the `certificate-base64.txt` file to the `APPLE_CERTIFICATE` environment variable.
|
||||
6. Set the certificate password to the `APPLE_CERTIFICATE_PASSWORD` environment variable.
|
||||
|
||||
#### Authentication environment variables
|
||||
|
||||
These variables are only required to notarize the application.
|
||||
|
||||
:::note
|
||||
|
||||
Notarization is required when using a <i>Developer ID Application</i> certificate.
|
||||
|
||||
:::
|
||||
|
||||
- `APPLE_ID` and `APPLE_PASSWORD`: to authenticate with your Apple ID, set the `APPLE_ID` to your Apple account email (example: `export APPLE_ID=tauri@icloud.com`) and the `APPLE_PASSWORD` to an [app-specific password] for the Apple account.
|
||||
- `APPLE_API_ISSUER` and `APPLE_API_KEY`: alternatively, you can authenticate using an App Store Connect API key. Open the App Store Connect's [Users and Access page], select the `Keys` tab, click on the `Add` button and select a name and the `Developer` access. The `APPLE_API_ISSUER` (`Issuer ID`) is presented above the keys table, and the `APPLE_API_KEY` is the value on the `Key ID` column on that table. You also need to download the private key, which can only be done once and is only visible after a page reload (the button is shown on the table row for the newly created key). The private key file must be saved on `./private_keys`, `~/private_keys`, `~/.private_keys` or `~/.appstoreconnect/private_keys`, as stated on the `xcrun altool --help` command.
|
||||
|
||||
### Building the application
|
||||
|
||||
The Tauri bundler automatically signs and notarizes your application with all these environment variables set when running the `tauri build` command.
|
||||
|
||||
### Example
|
||||
|
||||
The following example uses GitHub Actions to sign an application using the [Tauri action].
|
||||
|
||||
We first define the environment variables we listed above as Secrets on GitHub.
|
||||
|
||||
:::note
|
||||
|
||||
You can view <a href="https://docs.github.com/en/actions/reference/encrypted-secrets">this guide</a> to learn about GitHub secrets.
|
||||
|
||||
:::
|
||||
|
||||
Once we have established the GitHub Secrets, we create a GitHub publish workflow in `.github/workflows/main.yml`:
|
||||
|
||||
```yml
|
||||
name: "publish"
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- release
|
||||
|
||||
jobs:
|
||||
publish-tauri:
|
||||
permissions:
|
||||
contents: write
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
platform: [macos-latest]
|
||||
runs-on: ${{ matrix.platform }}
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v3
|
||||
|
||||
- name: Rust setup
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Rust cache
|
||||
uses: swatinem/rust-cache@v2
|
||||
with:
|
||||
workspaces: "./src-tauri -> target"
|
||||
|
||||
- name: Sync node version and setup cache
|
||||
uses: actions/setup-node@v3
|
||||
with:
|
||||
node-version: "lts/*"
|
||||
cache: "yarn" # Set this to npm, yarn or pnpm.
|
||||
|
||||
- name: Install frontend dependencies
|
||||
# If you don't have `beforeBuildCommand` configured you may want to build your frontend here too.
|
||||
run: yarn install # Change this to npm, yarn or pnpm.
|
||||
|
||||
- name: Build the app
|
||||
uses: tauri-apps/tauri-action@v0
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
ENABLE_CODE_SIGNING: ${{ secrets.APPLE_CERTIFICATE }}
|
||||
APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
|
||||
APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
|
||||
APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
|
||||
APPLE_ID: ${{ secrets.APPLE_ID }}
|
||||
APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
|
||||
with:
|
||||
tagName: app-v__VERSION__ # the action automatically replaces \_\_VERSION\_\_ with the app version
|
||||
releaseName: "App v__VERSION__"
|
||||
releaseBody: "See the assets to download this version and install."
|
||||
releaseDraft: true
|
||||
prerelease: false
|
||||
```
|
||||
|
||||
The workflow pulls the secrets from GitHub and defines them as environment variables before building the application using the Tauri action. The output is a GitHub release with the signed and notarized macOS application.
|
||||
|
||||
[tauri-apps/tauri#592]: https://github.com/tauri-apps/tauri/issues/592
|
||||
[apple developer program]: https://developer.apple.com/programs/
|
||||
[notarizing macos software before distribution]: https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution
|
||||
[app-specific password]: https://support.apple.com/en-ca/HT204397
|
||||
[create a certificate signing request]: https://developer.apple.com/help/account/create-certificates/create-a-certificate-signing-request
|
||||
[certificates, ids & profiles page]: https://developer.apple.com/account/resources/certificates/list
|
||||
[users and access page]: https://appstoreconnect.apple.com/access/users
|
||||
[tauri action]: https://github.com/tauri-apps/tauri-action
|
||||
@@ -1,195 +0,0 @@
|
||||
---
|
||||
title: code sign windows
|
||||
---
|
||||
|
||||
# Windows - Code signing guide locally & with GitHub Actions
|
||||
|
||||
## Intro
|
||||
|
||||
Code signing your application lets users know that they downloaded the official executable of your app and not some 3rd party malware that poses as your app. While it is not required, it improves users' confidence in your app.
|
||||
|
||||
:::danger
|
||||
|
||||
This guide only applies to OV code signing certificates acquired before June 1st 2023! For code signing with EV certificates and OV certificates received after that date please consult the documentation of your certificate issuer instead.
|
||||
|
||||
:::
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Windows - you can likely use other platforms, but this tutorial uses Powershell native features.
|
||||
- A working Tauri application
|
||||
- Code signing certificate - you can acquire one of these on services listed in [Microsoft's docs]. There are likely additional authorities for non-EV certificates than included in that list, please compare them yourself and choose one at your own risk.
|
||||
- Please make sure to get a **code signing** certificate, SSL certificates do not work!
|
||||
|
||||
This guide assumes that you have a standard code signing certificate> If you have an EV certificate, which generally involves a hardware token, please follow your issuer's documentation instead.
|
||||
|
||||
:::note
|
||||
|
||||
If you sign the app with an EV Certificate, it'll receive an immediate reputation with Microsoft SmartScreen and won't show any warnings to users.
|
||||
|
||||
If you opt for an OV Certificate, which is generally cheaper and available to individuals, Microsoft SmartScreen will still show a warning to users when they download the app. It might take some time until your certificate builds enough reputation. You may opt for [submitting your app] to Microsoft for manual review. Although not guaranteed, if the app does not contain any malicious code, Microsoft may grant additional reputation and potentially remove the warning for that specific uploaded file.
|
||||
|
||||
:::
|
||||
|
||||
## Getting Started
|
||||
|
||||
There are a few things we have to do to get Windows prepared for code signing. This includes converting our certificate to a specific format, installing this certificate, and decoding the required information from the certificate.
|
||||
|
||||
### A. Convert your `.cer` to `.pfx`
|
||||
|
||||
1. You will need the following:
|
||||
|
||||
- certificate file (mine is `cert.cer`)
|
||||
- private key file (mine is `private-key.key`)
|
||||
|
||||
2. Open up a command prompt and change to your current directory using `cd Documents/Certs`
|
||||
|
||||
3. Convert your `.cer` to a `.pfx` using `openssl pkcs12 -export -in cert.cer -inkey private-key.key -out certificate.pfx`
|
||||
|
||||
4. You should be prompted to enter an export password **DON'T FORGET IT!**
|
||||
|
||||
### B. Import your `.pfx` file into the keystore.
|
||||
|
||||
We now need to import our `.pfx` file.
|
||||
|
||||
1. Assign your export password to a variable using `$WINDOWS_PFX_PASSWORD = 'MYPASSWORD'`
|
||||
|
||||
2. Now Import the certificate using `Import-PfxCertificate -FilePath Certs/certificate.pfx -CertStoreLocation Cert:\CurrentUser\My -Password (ConvertTo-SecureString -String $env:WINDOWS_PFX_PASSWORD -Force -AsPlainText)`
|
||||
|
||||
### C. Prepare Variables
|
||||
|
||||
1. Start ➡️ `certmgr.msc` to open Personal Certificate Management, then open Personal/Certificates.
|
||||
|
||||
2. Find the certificate we just imported and double-click on it, then click on the Details tab.
|
||||
|
||||
3. The Signature hash algorithm will be our `digestAlgorithm`. (Hint: this is likely `sha256`)
|
||||
|
||||
4. Scroll down to Thumbprint. There should be a value like `A1B1A2B2A3B3A4B4A5B5A6B6A7B7A8B8A9B9A0B0`. This is our `certificateThumbprint`.
|
||||
|
||||
5. We also need a timestamp URL; this is a time server used to verify the time of the certificate signing. I'm using `http://timestamp.comodoca.com`, but whoever you got your certificate from likely has one as well.
|
||||
|
||||
## Prepare `tauri.conf.json` file
|
||||
|
||||
1. Now that we have our `certificateThumbprint`, `digestAlgorithm`, & `timestampUrl` we will open up the `tauri.conf.json`.
|
||||
|
||||
2. In the `tauri.conf.json` you will look for the `tauri` -> `bundle` -> `windows` section. You see, there are three variables for the information we have captured. Fill it out like below.
|
||||
|
||||
```json tauri.conf.json
|
||||
"windows": {
|
||||
"certificateThumbprint": "A1B1A2B2A3B3A4B4A5B5A6B6A7B7A8B8A9B9A0B0",
|
||||
"digestAlgorithm": "sha256",
|
||||
"timestampUrl": "http://timestamp.comodoca.com"
|
||||
}
|
||||
```
|
||||
|
||||
3. Save and run `yarn | yarn build`
|
||||
|
||||
4. In the console output, you should see the following output.
|
||||
|
||||
```
|
||||
info: signing app
|
||||
info: running signtool "C:\\Program Files (x86)\\Windows Kits\\10\\bin\\10.0.19041.0\\x64\\signtool.exe"
|
||||
info: "Done Adding Additional Store\r\nSuccessfully signed: APPLICATION FILE PATH HERE
|
||||
```
|
||||
|
||||
Which shows you have successfully signed the `.exe`.
|
||||
|
||||
And that's it! You have successfully signed your .exe file.
|
||||
|
||||
## BONUS: Sign your application with GitHub Actions.
|
||||
|
||||
We can also create a workflow to sign the application with GitHub actions.
|
||||
|
||||
### GitHub Secrets
|
||||
|
||||
We need to add a few GitHub secrets for the proper configuration of the GitHub Action. These can be named however you would like.
|
||||
|
||||
- You can view the [encrypted secrets] guide on how to add GitHub secrets.
|
||||
|
||||
The secrets we used are as follows
|
||||
|
||||
| GitHub Secrets | Value for Variable |
|
||||
| :--------------------------: | :-------------------------------------------------------------------------------------------------------------------------------: |
|
||||
| WINDOWS_CERTIFICATE | Base64 encoded version of your .pfx certificate, can be done using this command `certutil -encode certificate.pfx base64cert.txt` |
|
||||
| WINDOWS_CERTIFICATE_PASSWORD | Certificate export password used on creation of certificate .pfx |
|
||||
|
||||
### Workflow Modifications
|
||||
|
||||
1. We need to add a step in the workflow to import the certificate into the Windows environment. This workflow accomplishes the following
|
||||
|
||||
1. Assign GitHub secrets to environment variables
|
||||
2. Create a new `certificate` directory
|
||||
3. Import `WINDOWS_CERTIFICATE` into tempCert.txt
|
||||
4. Use `certutil` to decode the tempCert.txt from base64 into a `.pfx` file.
|
||||
5. Remove tempCert.txt
|
||||
6. Import the `.pfx` file into the Cert store of Windows & convert the `WINDOWS_CERTIFICATE_PASSWORD` to a secure string to be used in the import command.
|
||||
|
||||
2. We will be using the [`tauri-action` publish template].
|
||||
|
||||
```yml
|
||||
name: "publish"
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- release
|
||||
|
||||
jobs:
|
||||
publish-tauri:
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
platform: [macos-latest, ubuntu-latest, windows-latest]
|
||||
|
||||
runs-on: ${{ matrix.platform }}
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- name: setup node
|
||||
uses: actions/setup-node@v1
|
||||
with:
|
||||
node-version: 12
|
||||
- name: install Rust stable
|
||||
uses: actions-rs/toolchain@v1
|
||||
with:
|
||||
toolchain: stable
|
||||
- name: install webkit2gtk (ubuntu only)
|
||||
if: matrix.platform == 'ubuntu-latest'
|
||||
run: |
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y webkit2gtk-4.0
|
||||
- name: install app dependencies and build it
|
||||
run: yarn && yarn build
|
||||
- uses: tauri-apps/tauri-action@v0
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
with:
|
||||
tagName: app-v__VERSION__ # the action automatically replaces \_\_VERSION\_\_ with the app version
|
||||
releaseName: "App v__VERSION__"
|
||||
releaseBody: "See the assets to download this version and install."
|
||||
releaseDraft: true
|
||||
prerelease: false
|
||||
```
|
||||
|
||||
3. Right above `-name: install app dependencies and build it` you will want to add the following step
|
||||
|
||||
```yml
|
||||
- name: import windows certificate
|
||||
if: matrix.platform == 'windows-latest'
|
||||
env:
|
||||
WINDOWS_CERTIFICATE: ${{ secrets.WINDOWS_CERTIFICATE }}
|
||||
WINDOWS_CERTIFICATE_PASSWORD: ${{ secrets.WINDOWS_CERTIFICATE_PASSWORD }}
|
||||
run: |
|
||||
New-Item -ItemType directory -Path certificate
|
||||
Set-Content -Path certificate/tempCert.txt -Value $env:WINDOWS_CERTIFICATE
|
||||
certutil -decode certificate/tempCert.txt certificate/certificate.pfx
|
||||
Remove-Item -path certificate -include tempCert.txt
|
||||
Import-PfxCertificate -FilePath certificate/certificate.pfx -CertStoreLocation Cert:\CurrentUser\My -Password (ConvertTo-SecureString -String $env:WINDOWS_CERTIFICATE_PASSWORD -Force -AsPlainText)
|
||||
```
|
||||
|
||||
4. Save and push to your repo.
|
||||
|
||||
5. Your workflow can now import your windows certificate and import it into the GitHub runner, allowing for automated code signing!
|
||||
|
||||
[microsoft's docs]: https://learn.microsoft.com/en-us/windows-hardware/drivers/dashboard/code-signing-cert-manage
|
||||
[submitting your app]: https://www.microsoft.com/en-us/wdsi/filesubmission/
|
||||
[encrypted secrets]: https://docs.github.com/en/actions/reference/encrypted-secrets
|
||||
[`tauri-action` publish template]: https://github.com/tauri-apps/tauri-action
|
||||
@@ -1,288 +0,0 @@
|
||||
---
|
||||
title: updater
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs'
|
||||
import TabItem from '@theme/TabItem'
|
||||
import Command from '@theme/Command'
|
||||
import updaterDialogImage from '/img/guides/distribution/updater/update-available.png'
|
||||
|
||||
# Updater
|
||||
|
||||
Tauri offers a built-in updater for the NSIS (Windows), MSI (Windows), AppImage (Linux) and App bundle (macOS) distribution formats.
|
||||
|
||||
Once your Tauri project is ready, you can configure Tauri's updater to enable auto updating for your users.
|
||||
|
||||
## Signing Updates
|
||||
|
||||
Tauri's updater has a built-in signature mechanism to ensure that updates are safe to be installed.
|
||||
|
||||
To sign your updates you need two things:
|
||||
|
||||
1. The _public key_, which will be added to your `tauri.conf.json` file later, to validate update artifacts before the installation.
|
||||
2. The _private key_, which is used to sign your update artifacts and should NEVER be shared with anyone. Also, if you lose this key, you will NOT be able to publish new updates to your current user base. It is crucial to store it in a safe place where you can always access it.
|
||||
|
||||
To generate the keys on Linux and macOS you can use the Tauri CLI:
|
||||
|
||||
<Command name="signer generate -w ~/.tauri/myapp.key" />
|
||||
|
||||
If you are on Windows, you should use `$HOME/.tauri/myapp.key` or a different path of your choice instead:
|
||||
|
||||
<Command name="signer generate -w $HOME/.tauri/myapp.key" />
|
||||
|
||||
## Tauri Configuration
|
||||
|
||||
Now you need to configure Tauri's updater. To do this, add this to your [Tauri config](../../api/config.md#updaterconfig):
|
||||
|
||||
```json title=tauri.conf.json
|
||||
{
|
||||
"tauri": {
|
||||
"updater": {
|
||||
"active": true,
|
||||
"endpoints": [
|
||||
"https://releases.myapp.com/{{target}}/{{arch}}/{{current_version}}"
|
||||
],
|
||||
"dialog": true,
|
||||
"pubkey": "YOUR_UPDATER_SIGNATURE_PUBKEY_HERE"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The required keys are `"active"`, `"endpoints"` and `"pubkey"` to enable the updater. `"dialog"` is optional and will default to `true` if not set.
|
||||
|
||||
`"active"` must be a boolean. By default it's set to false.
|
||||
|
||||
`"endpoints"` must be an array of updater endpoint URLs as strings. TLS is enforced in production mode.<br/>
|
||||
Each updater URL can contain the following variables allowing you to determine [server-side](#update-server-json-format) if an update is available:
|
||||
|
||||
- `{{current_version}}`: The version of the app that is requesting the update.
|
||||
- `{{target}}`: The operating system name (one of `linux`, `windows` or `darwin`).
|
||||
- `{{arch}}`: The architecture of the machine (one of `x86_64`, `i686`, `aarch64` or `armv7`).
|
||||
|
||||
`"pubkey"` must be a valid public key generated with Tauri's CLI [above](#signing-updates).
|
||||
|
||||
`"dialog"` if present must be a boolean. By default it's set to true. If enabled, updater [events](#events) will be disabled as the built-in dialog handles everything. If you need custom events, you must turn off the built-in dialog.
|
||||
|
||||
### `installMode` on Windows
|
||||
|
||||
On Windows there is an additional optional config [`"installMode"`](../../api/config.md#updaterwindowsconfig.installmode) to change how the update is installed.
|
||||
|
||||
```json title=tauri.conf.json
|
||||
{
|
||||
"tauri": {
|
||||
"updater": {
|
||||
"windows": {
|
||||
"installMode": "passive"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `"passive"`: There will be a small window with a progress bar. The update will be installed without requiring any user interaction. Generally recommended and the default mode.
|
||||
- `"basicUi"`: There will be a basic user interface shown which requires user interaction to finish the installation.
|
||||
- `"quiet"`: There will be no progress feedback to the user. With this mode the installer cannot request admin privileges by itself so it only works in user-wide installations or when your app itself already runs with admin privileges. Generally not recommended.
|
||||
|
||||
## Update Artifacts
|
||||
|
||||
Tauri's bundler will automatically generate and sign update artifacts once the updater is correctly configured and enabled.
|
||||
|
||||
Before building your app, you need to set environment variables for the private key and password:
|
||||
|
||||
- `TAURI_PRIVATE_KEY`: Path or content of your private key
|
||||
- `TAURI_KEY_PASSWORD`: Your private key password (optional)
|
||||
|
||||
If you want to set these variables for the current console session you could execute these commands in the console which you will use to build the app later:
|
||||
|
||||
<Tabs groupId="set-env-vars">
|
||||
<TabItem value="Bash">
|
||||
|
||||
```shell
|
||||
export TAURI_PRIVATE_KEY="content of the generated key"
|
||||
export TAURI_KEY_PASSWORD="password"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="PowerShell">
|
||||
|
||||
```powershell
|
||||
$env:TAURI_PRIVATE_KEY="content of the generated key"
|
||||
$env:TAURI_KEY_PASSWORD="password"
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
After that, you can run `tauri build` as usual and Tauri will generate the update bundle and its signature.
|
||||
|
||||
- **Linux**: On Linux, Tauri will create a `.tar.gz` archive from the AppImage inside the `target/release/bundle/appimage/` folder:
|
||||
|
||||
- `myapp.AppImage` - the standard app bundle.
|
||||
- `myapp.AppImage.tar.gz` - the updater bundle.
|
||||
- `myapp.AppImage.tar.gz.sig` - the signature of the update bundle.
|
||||
|
||||
- **macOS**: On macOS, Tauri will create a `.tar.gz` archive from the application bundle inside the `target/release/bundle/macos/` folder:
|
||||
|
||||
- `myapp.app` - the standard app bundle.
|
||||
- `myapp.app.tar.gz` - the updater bundle.
|
||||
- `myapp.app.tar.gz.sig` - the signature of the update bundle.
|
||||
|
||||
- **Windows**: On Windows, Tauri will create `.zip` archives from the MSI and NSIS installers inside the `target/release/bundle/msi/` and `target/release/bundle/nsis` folders:
|
||||
- `myapp-setup.exe` - the standard app bundle.
|
||||
- `myapp-setup.nsis.zip` - the updater bundle.
|
||||
- `myapp-setup.nsis.zip.sig` - the signature of the update bundle.
|
||||
- `myapp.msi` - the standard app bundle.
|
||||
- `myapp.msi.zip` - the updater bundle.
|
||||
- `myapp.msi.zip.sig` - the signature of the update bundle.
|
||||
|
||||
The signature can be uploaded and shared safely as long as your private key is secure.
|
||||
|
||||
## Server Support
|
||||
|
||||
Tauri's updater supports two ways of announcing update data:
|
||||
|
||||
- A static JSON file (to use on services like S3 or GitHub gists)
|
||||
- A dynamic update server
|
||||
|
||||
The static JSON file is easier to use while a dynamic update server will give you finer control over the update mechanism.
|
||||
|
||||
### Static JSON File
|
||||
|
||||
With this approach, Tauri will always request the same JSON file and determine if the app needs to be updated by comparing the version field of the response with the requesting app's current version. Tauri will expect a response in this format:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "v1.0.0",
|
||||
"notes": "Test version",
|
||||
"pub_date": "2020-06-22T19:25:57Z",
|
||||
"platforms": {
|
||||
"darwin-x86_64": {
|
||||
"signature": "Content of app.tar.gz.sig",
|
||||
"url": "https://github.com/username/reponame/releases/download/v1.0.0/app-x86_64.app.tar.gz"
|
||||
},
|
||||
"darwin-aarch64": {
|
||||
"signature": "Content of app.tar.gz.sig",
|
||||
"url": "https://github.com/username/reponame/releases/download/v1.0.0/app-aarch64.app.tar.gz"
|
||||
},
|
||||
"linux-x86_64": {
|
||||
"signature": "Content of app.AppImage.tar.gz.sig",
|
||||
"url": "https://github.com/username/reponame/releases/download/v1.0.0/app-amd64.AppImage.tar.gz"
|
||||
},
|
||||
"windows-x86_64": {
|
||||
"signature": "Content of app-setup.nsis.sig or app.msi.sig, depending on the chosen format",
|
||||
"url": "https://github.com/username/reponame/releases/download/v1.0.0/app-x64-setup.nsis.zip"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The required keys are `"version"`, `"platforms.[target].url"` and `"platforms.[target].signature"`; the others are optional.
|
||||
|
||||
- `"version"` must be a valid semver, with or without a leading `v`, meaning that both `1.0.0` and `v1.0.0` are valid.
|
||||
- `"platforms"`: Each platform key is in the `OS-ARCH` format, where `OS` is one of `linux`, `darwin` or `windows`, and `ARCH` is one of `x86_64`, `aarch64`, `i686` or `armv7`.
|
||||
- `"url"` must be a valid url to the update bundle.
|
||||
- `"signature"` must be the **content** of the generated `.sig` file. The signature may change each time you run `tauri build` so make sure to always update it.
|
||||
- `"notes"`: Here you can add notes about the update, like release notes. Tauri's default dialog will present this to the user when it asks if it's allowed to update.
|
||||
- `"pub_date"` must be formatted according to [RFC 3339] if present.
|
||||
|
||||
Note that Tauri will validate the _whole_ file before checking the version field, so make sure all existing platform configurations are valid and complete.
|
||||
|
||||
### Dynamic Update Server
|
||||
|
||||
With this approach, Tauri will follow the update server's instructions. To disable the internal version check you can [overwrite Tauri's version comparison] to always install the version sent by the server. This could be useful if you need to roll back your app version quickly.
|
||||
|
||||
Your server can use variables defined in the [`endpoint`](../../api/config.md#updaterconfig.endpoints) url above to determine if an update is required. If you need more data, you can include additional [request headers in Rust] to your liking.
|
||||
|
||||
Your server should respond with a status code of [`204 No Content`] if there is no update available.
|
||||
|
||||
If an update is required, your server should respond with a status code of [`200 OK`] and a JSON response in this format:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"pub_date": "2020-09-18T12:29:53+01:00",
|
||||
"url": "https://mycompany.example.com/myapp/releases/myrelease.tar.gz",
|
||||
"signature": "Content of the relevant .sig file",
|
||||
"notes": "These are some release notes"
|
||||
}
|
||||
```
|
||||
|
||||
The required keys are "url", "version" and "signature"; the others are optional.
|
||||
|
||||
- `"version"` must be a valid semver, with or without a leading `v`, meaning that both `1.0.0` and `v1.0.0` are valid.
|
||||
- `"url"` must be a valid url to the update bundle.
|
||||
- `"signature"` must be the **content** of the generated `.sig` file. The signature may change each time you run `tauri build` so make sure to always update it.
|
||||
- `"notes"`: Here you can add notes about the update, like release notes. Tauri's default dialog will present this to the user when it asks if it's allowed to update.
|
||||
- `"pub_date"` must be formatted according to [RFC 3339] if present.
|
||||
|
||||
## Checking for Updates
|
||||
|
||||
### Built-In Dialog
|
||||
|
||||
By default, the updater shows a dialog using Tauri's [dialog.ask](../../api/js/dialog.md#ask) API internally. The dialog will only check for a new update when the app was just launched or when you manually [emit](../../api/js/event.md#emit) the `"tauri://update"` event.
|
||||
|
||||
<img src={updaterDialogImage} alt="Default updater dialog" style={{maxHeight: "200px", textAlign: 'center'}} />
|
||||
|
||||
The dialog release notes are represented by the update `notes` provided by the [server](#server-support).
|
||||
If the user accepts, the update is downloaded and installed. Afterwards, the user is prompted to restart the application.
|
||||
|
||||
### Custom Dialog
|
||||
|
||||
:::caution
|
||||
|
||||
You need to disable the built-in dialog in your [Tauri configuration](#tauri-configuration) to enable the JavaScript APIs and updater events!
|
||||
|
||||
:::
|
||||
|
||||
#### Rust
|
||||
|
||||
Please see the updater module documentation at [docs.rs] for the Rust API.
|
||||
|
||||
#### JavaScript
|
||||
|
||||
For the complete API docs see [here](../../api/js/updater.md). An example using the JavaScript API looks like this:
|
||||
|
||||
```js title=updater.ts
|
||||
import {
|
||||
checkUpdate,
|
||||
installUpdate,
|
||||
onUpdaterEvent,
|
||||
} from "@tauri-apps/api/updater";
|
||||
import { relaunch } from "@tauri-apps/api/process";
|
||||
|
||||
const unlisten = await onUpdaterEvent(({ error, status }) => {
|
||||
// This will log all updater events, including status updates and errors.
|
||||
console.log("Updater event", error, status);
|
||||
});
|
||||
|
||||
try {
|
||||
const { shouldUpdate, manifest } = await checkUpdate();
|
||||
|
||||
if (shouldUpdate) {
|
||||
// You could show a dialog asking the user if they want to install the update here.
|
||||
console.log(
|
||||
`Installing update ${manifest?.version}, ${manifest?.date}, ${manifest?.body}`
|
||||
);
|
||||
|
||||
// Install the update. This will also restart the app on Windows!
|
||||
await installUpdate();
|
||||
|
||||
// On macOS and Linux you will need to restart the app manually.
|
||||
// You could use this step to display another confirmation dialog.
|
||||
await relaunch();
|
||||
}
|
||||
} catch (error) {
|
||||
console.error(error);
|
||||
}
|
||||
|
||||
// you need to call unlisten if your handler goes out of scope, for example if the component is unmounted.
|
||||
unlisten();
|
||||
```
|
||||
|
||||
[overwrite tauri's version comparison]: https://docs.rs/tauri/latest/tauri/updater/struct.UpdateBuilder.html#method.should_install
|
||||
[request headers in rust]: https://docs.rs/tauri/latest/tauri/updater/struct.UpdateBuilder.html#method.header
|
||||
[`200 ok`]: http://tools.ietf.org/html/rfc2616#section-10.2.1
|
||||
[`204 no content`]: http://tools.ietf.org/html/rfc2616#section-10.2.5
|
||||
[rfc 3339]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.8
|
||||
[docs.rs]: https://docs.rs/tauri/latest/tauri/updater/index.html
|
||||
@@ -1,127 +0,0 @@
|
||||
---
|
||||
title: Frequently Asked Questions
|
||||
---
|
||||
|
||||
## How can I use unpublished Tauri changes?
|
||||
|
||||
To use Tauri from GitHub (bleeding edge version) you need to change your `Cargo.toml` file and update your CLI and API.
|
||||
|
||||
<details>
|
||||
<summary>Pulling the Rust crate from source</summary>
|
||||
|
||||
Append this to your `Cargo.toml` file:
|
||||
|
||||
```toml title=Cargo.toml
|
||||
[patch.crates-io]
|
||||
tauri = { git = "https://github.com/tauri-apps/tauri", branch = "1.x" }
|
||||
tauri-build = { git = "https://github.com/tauri-apps/tauri", branch = "1.x" }
|
||||
```
|
||||
|
||||
This will force all your dependencies to use `tauri` and `tauri-build` from Git instead of crates.io.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Using the Tauri CLI from source</summary>
|
||||
|
||||
If you are using the Cargo CLI, you can install it directly from GitHub:
|
||||
|
||||
```shell
|
||||
cargo install --git https://github.com/tauri-apps/tauri --branch 1.x tauri-cli
|
||||
```
|
||||
|
||||
If you are using the `@tauri-apps/cli` package, you will need to clone the repo and build it:
|
||||
|
||||
```shell
|
||||
git clone https://github.com/tauri-apps/tauri
|
||||
cd tauri
|
||||
git checkout 1.x
|
||||
cd tauri/tooling/cli/node
|
||||
yarn
|
||||
yarn build
|
||||
```
|
||||
|
||||
To use it, run directly with node:
|
||||
|
||||
```shell
|
||||
node /path/to/tauri/tooling/cli/node/tauri.js dev
|
||||
node /path/to/tauri/tooling/cli/node/tauri.js build
|
||||
```
|
||||
|
||||
Alternatively, you can run your app with Cargo directly:
|
||||
|
||||
```shell
|
||||
cd src-tauri
|
||||
cargo run --no-default-features # instead of tauri dev
|
||||
cargo build # instead of tauri build - won't bundle your app though
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Using the Tauri API from source</summary>
|
||||
|
||||
It is recommended to also use the Tauri API package from source when using the Tauri crate from GitHub (though it might not be needed).
|
||||
To build it from source, run the following script:
|
||||
|
||||
```shell
|
||||
git clone https://github.com/tauri-apps/tauri
|
||||
cd tauri
|
||||
git checkout 1.x
|
||||
cd tauri/tooling/api
|
||||
yarn
|
||||
yarn build
|
||||
```
|
||||
|
||||
Now you can link it using yarn:
|
||||
|
||||
```shell
|
||||
cd dist
|
||||
yarn link
|
||||
cd /path/to/your/project
|
||||
yarn link @tauri-apps/api
|
||||
```
|
||||
|
||||
Or you can change your package.json to point to the dist folder directly:
|
||||
|
||||
```json title=package.json
|
||||
{
|
||||
"dependencies": {
|
||||
"@tauri-apps/api": "/path/to/tauri/tooling/api/dist"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## Should I use Node or Cargo? {#node-or-cargo}
|
||||
|
||||
Even though installing the CLI through Cargo is the preferred option, it has to compile the whole binary from scratch when you install it. If you're in a CI environment or on a very slow machine you're better off choosing another installation method.
|
||||
|
||||
As the CLI is written in Rust, it is naturally available through [crates.io] and installable with Cargo.
|
||||
|
||||
We also compile the CLI as a native Node.js addon and distribute it [via npm]. This has several advantages compared to the Cargo installation method:
|
||||
|
||||
1. The CLI is pre-compiled, leading to much faster install times
|
||||
2. You can pin a specific version in your package.json file
|
||||
3. If you develop custom tooling around Tauri, you can import the CLI as a regular JavaScript module
|
||||
4. You can install the CLI using a JavaScript manager
|
||||
|
||||
## Recommended Browserlist
|
||||
|
||||
We recommend using `es2021`, `last 3 Chrome versions`, and `safari13` for your browserlist and build targets. Tauri leverages the OS's native rendering engine (WebKit on macOS, WebView2 on Windows and WebKitGTK on Linux).
|
||||
|
||||
## Build Conflict with Homebrew on Linux
|
||||
|
||||
Homebrew on Linux includes its own `pkg-config` (a utility to find libraries on the system). This can cause conflicts when installing the same `pkg-config` package for Tauri (usually installed through the package manager like `apt`). When you try to build a Tauri app it will try to invoke `pkg-config` and will end up invoking the one from Homebrew. If Homebrew wasn't used to install Tauri's dependencies, this can cause errors.
|
||||
|
||||
Errors will _usually_ contain messages along the lines of `error: failed to run custom build command for X` - `Package Y was not found in the pkg-config search path.`. Note that you may see similar errors if the required dependencies are not installed at all.
|
||||
|
||||
There are two solutions to this issue:
|
||||
|
||||
1. [Uninstall Homebrew]
|
||||
2. Set the `PKG_CONFIG_PATH` environment variable to point to the correct `pkg-config` before building a Tauri app
|
||||
|
||||
[crates.io]: https://crates.io/crates/tauri-cli
|
||||
[via npm]: https://www.npmjs.com/package/@tauri-apps/cli
|
||||
[uninstall homebrew]: https://docs.brew.sh/FAQ#how-do-i-uninstall-homebrew
|
||||
@@ -1,10 +0,0 @@
|
||||
---
|
||||
title: features
|
||||
---
|
||||
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
||||
|
||||
# Features
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
@@ -1,165 +0,0 @@
|
||||
---
|
||||
title: cli
|
||||
---
|
||||
|
||||
# Making Your Own CLI
|
||||
|
||||
Tauri enables your app to have a CLI through [clap](https://github.com/clap-rs/clap), a robust command line argument parser. With a simple CLI definition in your `tauri.conf.json` file, you can define your interface and read its argument matches map on JavaScript and/or Rust.
|
||||
|
||||
## Base Configuration
|
||||
|
||||
Under `tauri.conf.json`, you have the following structure to configure the interface:
|
||||
|
||||
```json title=src-tauri/tauri.conf.json
|
||||
{
|
||||
"tauri": {
|
||||
"cli": {
|
||||
"description": "", // command description that's shown on help
|
||||
"longDescription": "", // command long description that's shown on help
|
||||
"beforeHelp": "", // content to show before the help text
|
||||
"afterHelp": "", // content to show after the help text
|
||||
"args": [], // list of arguments of the command, we'll explain it later
|
||||
"subcommands": {
|
||||
"subcommand-name": {
|
||||
// configures a subcommand that is accessible
|
||||
// with `./app subcommand-name --arg1 --arg2 --etc`
|
||||
// configuration as above, with "description", "args", etc.
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
All JSON configurations here are just samples, many other fields have been omitted for the sake of clarity.
|
||||
|
||||
:::
|
||||
|
||||
## Adding Arguments
|
||||
|
||||
The `args` array represents the list of arguments accepted by its command or subcommand. You can find more details about the way to configure them [here][tauri config].
|
||||
|
||||
### Positional Arguments
|
||||
|
||||
A positional argument is identified by its position in the list of arguments. With the following configuration:
|
||||
|
||||
```json tauri.conf.json
|
||||
{
|
||||
"args": [
|
||||
{
|
||||
"name": "source",
|
||||
"index": 1,
|
||||
"takesValue": true
|
||||
},
|
||||
{
|
||||
"name": "destination",
|
||||
"index": 2,
|
||||
"takesValue": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Users can run your app as `./app tauri.txt dest.txt` and the arg matches map will define `source` as `"tauri.txt"` and `destination` as `"dest.txt"`.
|
||||
|
||||
### Named Arguments
|
||||
|
||||
A named argument is a (key, value) pair where the key identifies the value. With the following configuration:
|
||||
|
||||
```json tauri.conf.json
|
||||
{
|
||||
"args": [
|
||||
{
|
||||
"name": "type",
|
||||
"short": "t",
|
||||
"takesValue": true,
|
||||
"multiple": true,
|
||||
"possibleValues": ["foo", "bar"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Users can run your app as `./app --type foo bar`, `./app -t foo -t bar` or `./app --type=foo,bar` and the arg matches map will define `type` as `["foo", "bar"]`.
|
||||
|
||||
### Flag Arguments
|
||||
|
||||
A flag argument is a standalone key whose presence or absence provides information to your application. With the following configuration:
|
||||
|
||||
```json tauri.conf.json
|
||||
{
|
||||
"args": [
|
||||
{
|
||||
"name": "verbose",
|
||||
"short": "v",
|
||||
"multipleOccurrences": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Users can run your app as `./app -v -v -v`, `./app --verbose --verbose --verbose` or `./app -vvv` and the arg matches map will define `verbose` as `true`, with `occurrences = 3`.
|
||||
|
||||
## Subcommands
|
||||
|
||||
Some CLI applications have additional interfaces as subcommands. For instance, the `git` CLI has `git branch`, `git commit` and `git push`. You can define additional nested interfaces with the `subcommands` array:
|
||||
|
||||
```json tauri.conf.json
|
||||
{
|
||||
"cli": {
|
||||
...
|
||||
"subcommands": {
|
||||
"branch": {
|
||||
"args": []
|
||||
},
|
||||
"push": {
|
||||
"args": []
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Its configuration is the same as the root application configuration, with the `description`, `longDescription`, `args`, etc.
|
||||
|
||||
## Reading the matches
|
||||
|
||||
### Rust
|
||||
|
||||
```rust
|
||||
fn main() {
|
||||
tauri::Builder::default()
|
||||
.setup(|app| {
|
||||
match app.get_cli_matches() {
|
||||
// `matches` here is a Struct with { args, subcommand }.
|
||||
// `args` is `HashMap<String, ArgData>` where `ArgData` is a struct with { value, occurrences }.
|
||||
// `subcommand` is `Option<Box<SubcommandMatches>>` where `SubcommandMatches` is a struct with { name, matches }.
|
||||
Ok(matches) => {
|
||||
println!("{:?}", matches)
|
||||
}
|
||||
Err(_) => {}
|
||||
}
|
||||
Ok(())
|
||||
})
|
||||
.run(tauri::generate_context!())
|
||||
.expect("error while running tauri application");
|
||||
}
|
||||
```
|
||||
|
||||
### JavaScript
|
||||
|
||||
```js
|
||||
import { getMatches } from "@tauri-apps/api/cli";
|
||||
|
||||
getMatches().then((matches) => {
|
||||
// do something with the { args, subcommand } matches
|
||||
});
|
||||
```
|
||||
|
||||
## Complete documentation
|
||||
|
||||
You can find more about the CLI configuration [here][tauri config].
|
||||
|
||||
[tauri config]: ../../api/config.md#tauri
|
||||
@@ -1,367 +0,0 @@
|
||||
---
|
||||
title: command
|
||||
---
|
||||
|
||||
# Calling Rust from the frontend
|
||||
|
||||
Tauri provides a simple yet powerful `command` system for calling Rust functions from your web app.
|
||||
Commands can accept arguments and return values. They can also return errors and be `async`.
|
||||
|
||||
## Basic Example
|
||||
|
||||
Commands are defined in your `src-tauri/src/main.rs` file. To create a command, just add a function and annotate it with `#[tauri::command]`:
|
||||
|
||||
```rust
|
||||
#[tauri::command]
|
||||
fn my_custom_command() {
|
||||
println!("I was invoked from JS!");
|
||||
}
|
||||
```
|
||||
|
||||
You will have to provide a list of your commands to the builder function like so:
|
||||
|
||||
```rust
|
||||
// Also in main.rs
|
||||
fn main() {
|
||||
tauri::Builder::default()
|
||||
// This is where you pass in your commands
|
||||
.invoke_handler(tauri::generate_handler![my_custom_command])
|
||||
.run(tauri::generate_context!())
|
||||
.expect("failed to run app");
|
||||
}
|
||||
```
|
||||
|
||||
Now, you can invoke the command from your JS code:
|
||||
|
||||
```js
|
||||
// When using the Tauri API npm package:
|
||||
import { invoke } from "@tauri-apps/api/tauri";
|
||||
// When using the Tauri global script (if not using the npm package)
|
||||
// Be sure to set `build.withGlobalTauri` in `tauri.conf.json` to true
|
||||
const invoke = window.__TAURI__.invoke;
|
||||
|
||||
// Invoke the command
|
||||
invoke("my_custom_command");
|
||||
```
|
||||
|
||||
## Passing Arguments
|
||||
|
||||
Your command handlers can take arguments:
|
||||
|
||||
```rust
|
||||
#[tauri::command]
|
||||
fn my_custom_command(invoke_message: String) {
|
||||
println!("I was invoked from JS, with this message: {}", invoke_message);
|
||||
}
|
||||
```
|
||||
|
||||
Arguments should be passed as a JSON object with camelCase keys:
|
||||
|
||||
```js
|
||||
invoke("my_custom_command", { invokeMessage: "Hello!" });
|
||||
```
|
||||
|
||||
Arguments can be of any type, as long as they implement [`serde::Deserialize`].
|
||||
|
||||
Please note, when declaring arguments in Rust using snake_case, the arguments are converted to camelCase for JavaScript.
|
||||
To use snake_case in JavaScript, you have to declare it in the `tauri::command` statement:
|
||||
|
||||
```rust
|
||||
#[tauri::command(rename_all = "snake_case")]
|
||||
fn my_custom_command(invoke_message: String) {
|
||||
println!("I was invoked from JS, with this message: {}", invoke_message);
|
||||
}
|
||||
```
|
||||
|
||||
The corresponding JavaScript:
|
||||
|
||||
```js
|
||||
invoke("my_custom_command", { invoke_message: "Hello!" });
|
||||
```
|
||||
|
||||
## Returning Data
|
||||
|
||||
Command handlers can return data as well:
|
||||
|
||||
```rust
|
||||
#[tauri::command]
|
||||
fn my_custom_command() -> String {
|
||||
"Hello from Rust!".into()
|
||||
}
|
||||
```
|
||||
|
||||
The `invoke` function returns a promise that resolves with the returned value:
|
||||
|
||||
```js
|
||||
invoke("my_custom_command").then((message) => console.log(message));
|
||||
```
|
||||
|
||||
Returned data can be of any type, as long as it implements [`serde::Serialize`].
|
||||
|
||||
## Error Handling
|
||||
|
||||
If your handler could fail and needs to be able to return an error, have the function return a `Result`:
|
||||
|
||||
```rust
|
||||
#[tauri::command]
|
||||
fn my_custom_command() -> Result<String, String> {
|
||||
// If something fails
|
||||
Err("This failed!".into())
|
||||
// If it worked
|
||||
Ok("This worked!".into())
|
||||
}
|
||||
```
|
||||
|
||||
If the command returns an error, the promise will reject, otherwise, it resolves:
|
||||
|
||||
```js
|
||||
invoke("my_custom_command")
|
||||
.then((message) => console.log(message))
|
||||
.catch((error) => console.error(error));
|
||||
```
|
||||
|
||||
As mentioned above, everything returned from commands must implement [`serde::Serialize`], including errors.
|
||||
This can be problematic if you're working with error types from Rust's std library or external crates as most error types do not implement it.
|
||||
In simple scenarios you can use `map_err` to convert these errors to `String`s:
|
||||
|
||||
```rust
|
||||
#[tauri::command]
|
||||
fn my_custom_command() -> Result<(), String> {
|
||||
// This will return an error
|
||||
std::fs::File::open("path/that/does/not/exist").map_err(|err| err.to_string())?;
|
||||
// Return nothing on success
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
Since this is not very idiomatic you may want to create your own error type which implements `serde::Serialize`. In the following example, we use the [`thiserror`] crate to help create the error type. It allows you to turn enums into error types by deriving the `thiserror::Error` trait. You can consult its documentation for more details.
|
||||
|
||||
```rust
|
||||
// create the error type that represents all errors possible in our program
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
enum Error {
|
||||
#[error(transparent)]
|
||||
Io(#[from] std::io::Error)
|
||||
}
|
||||
|
||||
// we must manually implement serde::Serialize
|
||||
impl serde::Serialize for Error {
|
||||
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
|
||||
where
|
||||
S: serde::ser::Serializer,
|
||||
{
|
||||
serializer.serialize_str(self.to_string().as_ref())
|
||||
}
|
||||
}
|
||||
|
||||
#[tauri::command]
|
||||
fn my_custom_command() -> Result<(), Error> {
|
||||
// This will return an error
|
||||
std::fs::File::open("path/that/does/not/exist")?;
|
||||
// Return nothing on success
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
A custom error type has the advantage of making all possible errors explicit so readers can quickly identify what errors can happen. This saves other people (and yourself) enormous amounts of time when reviewing and refactoring code later.<br/>
|
||||
It also gives you full control over the way your error type gets serialized. In the above example, we simply returned the error message as a string, but you could assign each error a code similar to C, this way you could more easily map it to a similar looking TypeScript error enum for example.
|
||||
|
||||
## Async Commands
|
||||
|
||||
Asynchronous functions are benefical in Tauri to perform heavy work in a manner that doesn't result in UI freezes or slowdowns.
|
||||
|
||||
:::note
|
||||
|
||||
Async commands are executed on a separate thread using [`async_runtime::spawn`].
|
||||
Commands without the _async_ keyword are executed on the main thread unless defined with _#[tauri::command(async)]_.
|
||||
|
||||
:::
|
||||
|
||||
**If your command needs to run asynchronously, simply declare it as `async`.**
|
||||
|
||||
:::caution
|
||||
|
||||
You need to be careful when creating asynchronous functions using Tauri. Currently, you cannot simply include borrowed arguments in the signature of an asynchronous function. Some common examples of types like this are `&str` and `State<'_, Data>`. This limitation is tracked here: https://github.com/tauri-apps/tauri/issues/2533 and workarounds are shown below.
|
||||
|
||||
:::
|
||||
|
||||
When working with borrowed types, you have to make additional changes. These are your two main options:
|
||||
|
||||
**Option 1**: Convert the type, such as `&str` to a similar type that is not borrowed, such as `String`. This may not work for all types, for example `State<'_, Data>`.
|
||||
|
||||
_Example:_
|
||||
|
||||
```rust
|
||||
// Declare the async function using String instead of &str, as &str is borrowed and thus unsupported
|
||||
#[tauri::command]
|
||||
async fn my_custom_command(value: String) -> String {
|
||||
// Call another async function and wait for it to finish
|
||||
some_async_function().await;
|
||||
format!(value)
|
||||
}
|
||||
```
|
||||
|
||||
**Option 2**: Wrap the return type in a [`Result`]. This one is a bit harder to implement, but should work for all types.
|
||||
|
||||
Use the return type `Result<a, b>`, replacing `a` with the type you wish to return, or `()` if you wish to return nothing, and replacing `b` with an error type to return if something goes wrong, or `()` if you wish to have no optional error returned. For example:
|
||||
|
||||
- `Result<String, ()>` to return a String, and no error.
|
||||
- `Result<(), ()>` to return nothing.
|
||||
- `Result<bool, Error>` to return a boolean or an error as shown in the [Error Handling](#error-handling) section above.
|
||||
|
||||
_Example:_
|
||||
|
||||
```rust
|
||||
// Return a Result<String, ()> to bypass the borrowing issue
|
||||
#[tauri::command]
|
||||
async fn my_custom_command(value: &str) -> Result<String, ()> {
|
||||
// Call another async function and wait for it to finish
|
||||
some_async_function().await;
|
||||
// Note that the return value must be wrapped in `Ok()` now.
|
||||
Ok(format!(value))
|
||||
}
|
||||
```
|
||||
|
||||
#### Invoking from JS
|
||||
|
||||
Since invoking the command from JavaScript already returns a promise, it works just like any other command:
|
||||
|
||||
```js
|
||||
invoke("my_custom_command", { value: "Hello, Async!" }).then(() =>
|
||||
console.log("Completed!")
|
||||
);
|
||||
```
|
||||
|
||||
## Accessing the Window in Commands
|
||||
|
||||
Commands can access the `Window` instance that invoked the message:
|
||||
|
||||
```rust
|
||||
#[tauri::command]
|
||||
async fn my_custom_command(window: tauri::Window) {
|
||||
println!("Window: {}", window.label());
|
||||
}
|
||||
```
|
||||
|
||||
## Accessing an AppHandle in Commands
|
||||
|
||||
Commands can access an `AppHandle` instance:
|
||||
|
||||
```rust
|
||||
#[tauri::command]
|
||||
async fn my_custom_command(app_handle: tauri::AppHandle) {
|
||||
let app_dir = app_handle.path_resolver().app_dir();
|
||||
use tauri::GlobalShortcutManager;
|
||||
app_handle.global_shortcut_manager().register("CTRL + U", move || {});
|
||||
}
|
||||
```
|
||||
|
||||
## Accessing managed state
|
||||
|
||||
Tauri can manage state using the `manage` function on `tauri::Builder`.
|
||||
The state can be accessed on a command using `tauri::State`:
|
||||
|
||||
```rust
|
||||
struct MyState(String);
|
||||
|
||||
#[tauri::command]
|
||||
fn my_custom_command(state: tauri::State<MyState>) {
|
||||
assert_eq!(state.0 == "some state value", true);
|
||||
}
|
||||
|
||||
fn main() {
|
||||
tauri::Builder::default()
|
||||
.manage(MyState("some state value".into()))
|
||||
.invoke_handler(tauri::generate_handler![my_custom_command])
|
||||
.run(tauri::generate_context!())
|
||||
.expect("error while running tauri application");
|
||||
}
|
||||
```
|
||||
|
||||
## Creating Multiple Commands
|
||||
|
||||
The `tauri::generate_handler!` macro takes an array of commands. To register
|
||||
multiple commands, you cannot call invoke_handler multiple times. Only the last
|
||||
call will be used. You must pass each command to a single call of
|
||||
`tauri::generate_handler!`.
|
||||
|
||||
```rust
|
||||
#[tauri::command]
|
||||
fn cmd_a() -> String {
|
||||
"Command a"
|
||||
}
|
||||
#[tauri::command]
|
||||
fn cmd_b() -> String {
|
||||
"Command b"
|
||||
}
|
||||
|
||||
fn main() {
|
||||
tauri::Builder::default()
|
||||
.invoke_handler(tauri::generate_handler![cmd_a, cmd_b])
|
||||
.run(tauri::generate_context!())
|
||||
.expect("error while running tauri application");
|
||||
}
|
||||
```
|
||||
|
||||
## Complete Example
|
||||
|
||||
Any or all of the above features can be combined:
|
||||
|
||||
```rust main.rs
|
||||
|
||||
struct Database;
|
||||
|
||||
#[derive(serde::Serialize)]
|
||||
struct CustomResponse {
|
||||
message: String,
|
||||
other_val: usize,
|
||||
}
|
||||
|
||||
async fn some_other_function() -> Option<String> {
|
||||
Some("response".into())
|
||||
}
|
||||
|
||||
#[tauri::command]
|
||||
async fn my_custom_command(
|
||||
window: tauri::Window,
|
||||
number: usize,
|
||||
database: tauri::State<'_, Database>,
|
||||
) -> Result<CustomResponse, String> {
|
||||
println!("Called from {}", window.label());
|
||||
let result: Option<String> = some_other_function().await;
|
||||
if let Some(message) = result {
|
||||
Ok(CustomResponse {
|
||||
message,
|
||||
other_val: 42 + number,
|
||||
})
|
||||
} else {
|
||||
Err("No result".into())
|
||||
}
|
||||
}
|
||||
|
||||
fn main() {
|
||||
tauri::Builder::default()
|
||||
.manage(Database {})
|
||||
.invoke_handler(tauri::generate_handler![my_custom_command])
|
||||
.run(tauri::generate_context!())
|
||||
.expect("error while running tauri application");
|
||||
}
|
||||
```
|
||||
|
||||
```js
|
||||
// Invocation from JS
|
||||
|
||||
invoke("my_custom_command", {
|
||||
number: 42,
|
||||
})
|
||||
.then((res) =>
|
||||
console.log(`Message: ${res.message}, Other Val: ${res.other_val}`)
|
||||
)
|
||||
.catch((e) => console.error(e));
|
||||
```
|
||||
|
||||
[`async_runtime::spawn`]: https://docs.rs/tauri/1/tauri/async_runtime/fn.spawn.html
|
||||
[`serde::serialize`]: https://docs.serde.rs/serde/trait.Serialize.html
|
||||
[`serde::deserialize`]: https://docs.serde.rs/serde/trait.Deserialize.html
|
||||
[`thiserror`]: https://github.com/dtolnay/thiserror
|
||||
[`result`]: https://doc.rust-lang.org/std/result/index.html
|
||||
@@ -1,132 +0,0 @@
|
||||
---
|
||||
title: events
|
||||
---
|
||||
|
||||
# Events
|
||||
|
||||
The Tauri event system is a multi-producer multi-consumer communication primitive that allows message passing between the frontend and the backend.
|
||||
It is analogous to the command system, but a payload type check must be written on the event handler and it simplifies communication from the backend to the frontend, working like a channel.
|
||||
|
||||
A Tauri application can listen and emit global and window-specific events. Usage from the frontend and the backend is described below.
|
||||
|
||||
## Frontend
|
||||
|
||||
The event system is accessible on the frontend on the `event` and `window` modules of the `@tauri-apps/api` package.
|
||||
|
||||
### Global events
|
||||
|
||||
To use the global event channel, import the `event` module and use the `emit` and `listen` functions:
|
||||
|
||||
```js
|
||||
import { emit, listen } from "@tauri-apps/api/event";
|
||||
|
||||
// listen to the `click` event and get a function to remove the event listener
|
||||
// there's also a `once` function that subscribes to an event and automatically unsubscribes the listener on the first event
|
||||
const unlisten = await listen("click", (event) => {
|
||||
// event.event is the event name (useful if you want to use a single callback fn for multiple event types)
|
||||
// event.payload is the payload object
|
||||
});
|
||||
|
||||
// emits the `click` event with the object payload
|
||||
emit("click", {
|
||||
theMessage: "Tauri is awesome!",
|
||||
});
|
||||
```
|
||||
|
||||
### Window-specific events
|
||||
|
||||
Window-specific events are exposed on the `window` module.
|
||||
|
||||
```js
|
||||
import { appWindow, WebviewWindow } from "@tauri-apps/api/window";
|
||||
|
||||
// emit an event that is only visible to the current window
|
||||
appWindow.emit("event", { message: "Tauri is awesome!" });
|
||||
|
||||
// create a new webview window and emit an event only to that window
|
||||
const webview = new WebviewWindow("window");
|
||||
webview.emit("event");
|
||||
```
|
||||
|
||||
## Backend
|
||||
|
||||
On the backend, the global event channel is exposed on the `App` struct, and window-specific events can be emitted using the `Window` trait.
|
||||
|
||||
### Global events
|
||||
|
||||
```rust
|
||||
use tauri::Manager;
|
||||
|
||||
// the payload type must implement `Serialize` and `Clone`.
|
||||
#[derive(Clone, serde::Serialize)]
|
||||
struct Payload {
|
||||
message: String,
|
||||
}
|
||||
|
||||
fn main() {
|
||||
tauri::Builder::default()
|
||||
.setup(|app| {
|
||||
// listen to the `event-name` (emitted on any window)
|
||||
let id = app.listen_global("event-name", |event| {
|
||||
println!("got event-name with payload {:?}", event.payload());
|
||||
});
|
||||
// unlisten to the event using the `id` returned on the `listen_global` function
|
||||
// a `once_global` API is also exposed on the `App` struct
|
||||
app.unlisten(id);
|
||||
|
||||
// emit the `event-name` event to all webview windows on the frontend
|
||||
app.emit_all("event-name", Payload { message: "Tauri is awesome!".into() }).unwrap();
|
||||
Ok(())
|
||||
})
|
||||
.run(tauri::generate_context!())
|
||||
.expect("failed to run app");
|
||||
}
|
||||
```
|
||||
|
||||
### Window-specific events
|
||||
|
||||
To use the window-specific event channel, a `Window` object can be obtained on a command handler or with the `get_window` function:
|
||||
|
||||
```rust
|
||||
use tauri::{Manager, Window};
|
||||
|
||||
// the payload type must implement `Serialize` and `Clone`.
|
||||
#[derive(Clone, serde::Serialize)]
|
||||
struct Payload {
|
||||
message: String,
|
||||
}
|
||||
|
||||
// init a background process on the command, and emit periodic events only to the window that used the command
|
||||
#[tauri::command]
|
||||
fn init_process(window: Window) {
|
||||
std::thread::spawn(move || {
|
||||
loop {
|
||||
window.emit("event-name", Payload { message: "Tauri is awesome!".into() }).unwrap();
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
fn main() {
|
||||
tauri::Builder::default()
|
||||
.setup(|app| {
|
||||
// `main` here is the window label; it is defined on the window creation or under `tauri.conf.json`
|
||||
// the default value is `main`. note that it must be unique
|
||||
let main_window = app.get_window("main").unwrap();
|
||||
|
||||
// listen to the `event-name` (emitted on the `main` window)
|
||||
let id = main_window.listen("event-name", |event| {
|
||||
println!("got window event-name with payload {:?}", event.payload());
|
||||
});
|
||||
// unlisten to the event using the `id` returned on the `listen` function
|
||||
// an `once` API is also exposed on the `Window` struct
|
||||
main_window.unlisten(id);
|
||||
|
||||
// emit the `event-name` event to the `main` window
|
||||
main_window.emit("event-name", Payload { message: "Tauri is awesome!".into() }).unwrap();
|
||||
Ok(())
|
||||
})
|
||||
.invoke_handler(tauri::generate_handler![init_process])
|
||||
.run(tauri::generate_context!())
|
||||
.expect("failed to run app");
|
||||
}
|
||||
```
|
||||
@@ -1,76 +0,0 @@
|
||||
---
|
||||
title: icons
|
||||
---
|
||||
|
||||
import Command from '@theme/Command'
|
||||
|
||||
# Icons
|
||||
|
||||
Tauri ships with a default iconset based on its logo. This is NOT what you want when you ship your application. To remedy this common situation, Tauri provides the `icon` command that will take an input file (`"./app-icon.png"` by default) and create all the icons needed for the various platforms.
|
||||
|
||||
:::info Note on filetypes
|
||||
|
||||
- `icon.icns` = macOS
|
||||
- `icon.ico` = Windows
|
||||
- `*.png` = Linux
|
||||
- `Square*Logo.png` & `StoreLogo.png` = Currently unused but intended for AppX/MS Store targets.
|
||||
|
||||
Note that icon types may be used on platforms other than those listed above (especially `png`). Therefore we recommend including all icons even if you intend to only build for a subset of platforms.
|
||||
|
||||
:::
|
||||
|
||||
## Command Usage
|
||||
|
||||
Starting with `@tauri-apps/cli` / `tauri-cli` version 1.1 the `icon` subcommand is part of the main cli:
|
||||
|
||||
<Command name="icon" />
|
||||
|
||||
```console
|
||||
> cargo tauri icon --help
|
||||
cargo-tauri-icon 1.1.0
|
||||
|
||||
Generates various icons for all major platforms
|
||||
|
||||
USAGE:
|
||||
cargo tauri icon [OPTIONS] [INPUT]
|
||||
|
||||
ARGS:
|
||||
<INPUT> Path to the source icon (png, 1024x1024px with transparency) [default: ./app-icon.png]
|
||||
|
||||
OPTIONS:
|
||||
-h, --help Print help information
|
||||
-o, --output <OUTPUT> Output directory. Default: 'icons' directory next to the tauri.conf.json file
|
||||
-v, --verbose Enables verbose logging
|
||||
-V, --version Print version information
|
||||
```
|
||||
|
||||
By default, the icons will be placed in your `src-tauri/icons` folder where they will automatically be included in your built app. If you want to source your icons from a different location, you can edit this part of the `tauri.conf.json` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"bundle": {
|
||||
"icon": [
|
||||
"icons/32x32.png",
|
||||
"icons/128x128.png",
|
||||
"icons/128x128@2x.png",
|
||||
"icons/icon.icns",
|
||||
"icons/icon.ico"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Creating the icons manually
|
||||
|
||||
If you prefer to build these icons yourself, for example if you want to have a simpler design for small sizes or because you don't want to depend on the CLI's internal image resizing, you must make sure your icons meet some requirements:
|
||||
|
||||
- `icon.icns`: The required layer sizes and names for the [`icns`] file are described [in the Tauri repo]
|
||||
- `icon.ico`: The [`ico`] file must include layers for 16, 24, 32, 48, 64 and 256 pixels. For an optimal display of the ICO image _in development_, the 32px layer should be the first layer.
|
||||
- `png`: The requirements for the png icons are: width == height, RGBA (RGB + Transparency), and 32bit per pixel (8bit per channel). Commonly expected sizes are 32, 128, 256, and 512 pixels. We recommend to at least match the output of `tauri icon`: `32x32.png`, `128x128.png`, `128x128@2x.png`, and `icon.png`.
|
||||
|
||||
[`tauricon`]: https://github.com/tauri-apps/tauricon
|
||||
[in the tauri repo]: https://github.com/tauri-apps/tauri/blob/dev/tooling/cli/src/helpers/icns.json
|
||||
[`icns`]: https://en.wikipedia.org/wiki/Apple_Icon_Image_format
|
||||
[`ico`]: https://en.wikipedia.org/wiki/ICO_(file_format)
|
||||
@@ -1,158 +0,0 @@
|
||||
---
|
||||
title: menu
|
||||
---
|
||||
|
||||
# Window Menu
|
||||
|
||||
Native application menus can be attached to a window.
|
||||
|
||||
### Creating a menu
|
||||
|
||||
To create a native window menu, import the `Menu`, `Submenu`, `MenuItem` and `CustomMenuItem` types.
|
||||
The `MenuItem` enum contains a collection of platform-specific items (currently not implemented on Windows).
|
||||
The `CustomMenuItem` allows you to create your own menu items and add special functionality to them.
|
||||
|
||||
```rust
|
||||
use tauri::{CustomMenuItem, Menu, MenuItem, Submenu};
|
||||
```
|
||||
|
||||
Create a `Menu` instance:
|
||||
|
||||
```rust
|
||||
// here `"quit".to_string()` defines the menu item id, and the second parameter is the menu item label.
|
||||
let quit = CustomMenuItem::new("quit".to_string(), "Quit");
|
||||
let close = CustomMenuItem::new("close".to_string(), "Close");
|
||||
let submenu = Submenu::new("File", Menu::new().add_item(quit).add_item(close));
|
||||
let menu = Menu::new()
|
||||
.add_native_item(MenuItem::Copy)
|
||||
.add_item(CustomMenuItem::new("hide", "Hide"))
|
||||
.add_submenu(submenu);
|
||||
```
|
||||
|
||||
### Adding the menu to all windows
|
||||
|
||||
The defined menu can be set to all windows using the `menu` API on the `tauri::Builder` struct:
|
||||
|
||||
```rust
|
||||
use tauri::{CustomMenuItem, Menu, MenuItem, Submenu};
|
||||
|
||||
fn main() {
|
||||
let menu = Menu::new(); // configure the menu
|
||||
tauri::Builder::default()
|
||||
.menu(menu)
|
||||
.run(tauri::generate_context!())
|
||||
.expect("error while running tauri application");
|
||||
}
|
||||
```
|
||||
|
||||
### Adding the menu to a specific window
|
||||
|
||||
You can create a window and set the menu to be used. This allows for defining a specific menu set for each application window.
|
||||
|
||||
```rust
|
||||
use tauri::{CustomMenuItem, Menu, MenuItem, Submenu};
|
||||
use tauri::WindowBuilder;
|
||||
|
||||
fn main() {
|
||||
let menu = Menu::new(); // configure the menu
|
||||
tauri::Builder::default()
|
||||
.setup(|app| {
|
||||
WindowBuilder::new(
|
||||
app,
|
||||
"main-window".to_string(),
|
||||
tauri::WindowUrl::App("index.html".into()),
|
||||
)
|
||||
.menu(menu)
|
||||
.build()?;
|
||||
Ok(())
|
||||
})
|
||||
.run(tauri::generate_context!())
|
||||
.expect("error while running tauri application");
|
||||
}
|
||||
```
|
||||
|
||||
### Listening to events on custom menu items
|
||||
|
||||
Each `CustomMenuItem` triggers an event when clicked. Use the `on_menu_event` API to handle them, either on the global `tauri::Builder` or on a specific window.
|
||||
|
||||
#### Listening to events on global menus
|
||||
|
||||
```rust
|
||||
use tauri::{CustomMenuItem, Menu, MenuItem};
|
||||
|
||||
fn main() {
|
||||
let menu = Menu::new(); // configure the menu
|
||||
tauri::Builder::default()
|
||||
.menu(menu)
|
||||
.on_menu_event(|event| {
|
||||
match event.menu_item_id() {
|
||||
"quit" => {
|
||||
std::process::exit(0);
|
||||
}
|
||||
"close" => {
|
||||
event.window().close().unwrap();
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
})
|
||||
.run(tauri::generate_context!())
|
||||
.expect("error while running tauri application");
|
||||
}
|
||||
```
|
||||
|
||||
#### Listening to events on window menus
|
||||
|
||||
```rust
|
||||
use tauri::{CustomMenuItem, Menu, MenuItem};
|
||||
use tauri::{Manager, WindowBuilder};
|
||||
|
||||
fn main() {
|
||||
let menu = Menu::new(); // configure the menu
|
||||
tauri::Builder::default()
|
||||
.setup(|app| {
|
||||
let window = WindowBuilder::new(
|
||||
app,
|
||||
"main-window".to_string(),
|
||||
tauri::WindowUrl::App("index.html".into()),
|
||||
)
|
||||
.menu(menu)
|
||||
.build()?;
|
||||
let window_ = window.clone();
|
||||
window.on_menu_event(move |event| {
|
||||
match event.menu_item_id() {
|
||||
"quit" => {
|
||||
std::process::exit(0);
|
||||
}
|
||||
"close" => {
|
||||
window_.close().unwrap();
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
});
|
||||
Ok(())
|
||||
})
|
||||
.run(tauri::generate_context!())
|
||||
.expect("error while running tauri application");
|
||||
}
|
||||
```
|
||||
|
||||
### Updating menu items
|
||||
|
||||
The `Window` struct has a `menu_handle` method, which allows updating menu items:
|
||||
|
||||
```rust
|
||||
fn main() {
|
||||
let menu = Menu::new(); // configure the menu
|
||||
tauri::Builder::default()
|
||||
.menu(menu)
|
||||
.setup(|app| {
|
||||
let main_window = app.get_window("main").unwrap();
|
||||
let menu_handle = main_window.menu_handle();
|
||||
std::thread::spawn(move || {
|
||||
// you can also `set_selected`, `set_enabled` and `set_native_image` (macOS only).
|
||||
menu_handle.get_item("item_id").set_title("New title");
|
||||
});
|
||||
Ok(())
|
||||
})
|
||||
}
|
||||
```
|
||||
@@ -1,194 +0,0 @@
|
||||
---
|
||||
title: multiwindow
|
||||
---
|
||||
|
||||
# Multiwindow
|
||||
|
||||
Manage multiple windows on a single application.
|
||||
|
||||
## Creating a window
|
||||
|
||||
A window can be created statically from the Tauri configuration file or at runtime.
|
||||
|
||||
### Static window
|
||||
|
||||
Multiple windows can be created with the [tauri.windows] configuration array.
|
||||
The following JSON snippet demonstrates how to statically create several windows through the config:
|
||||
|
||||
```json tauri.conf.json
|
||||
{
|
||||
"tauri": {
|
||||
"windows": [
|
||||
{
|
||||
"label": "external",
|
||||
"title": "Tauri Docs",
|
||||
"url": "https://tauri.app"
|
||||
},
|
||||
{
|
||||
"label": "local",
|
||||
"title": "Tauri",
|
||||
"url": "index.html"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Note that the window label must be unique and can be used at runtime to access the window instance.
|
||||
The complete list of configuration options available for static windows can be found in the [WindowConfig] documentation.
|
||||
|
||||
### Runtime window
|
||||
|
||||
You can also create windows at runtime either via the Rust layer or through the Tauri API.
|
||||
|
||||
#### Create a window in Rust
|
||||
|
||||
A window can be created at runtime using the [WindowBuilder] struct.
|
||||
|
||||
To create a window, you must have an instance of the running [App] or an [AppHandle].
|
||||
|
||||
##### Create a window using the [App] instance
|
||||
|
||||
The [App] instance can be obtained in the setup hook or after a call to [Builder::build].
|
||||
|
||||
```rust Using the setup hook
|
||||
tauri::Builder::default()
|
||||
.setup(|app| {
|
||||
let docs_window = tauri::WindowBuilder::new(
|
||||
app,
|
||||
"external", /* the unique window label */
|
||||
tauri::WindowUrl::External("https://tauri.app/".parse().unwrap())
|
||||
).build()?;
|
||||
let local_window = tauri::WindowBuilder::new(
|
||||
app,
|
||||
"local",
|
||||
tauri::WindowUrl::App("index.html".into())
|
||||
).build()?;
|
||||
Ok(())
|
||||
})
|
||||
.run(tauri::generate_context!())
|
||||
.expect("error while running app");
|
||||
```
|
||||
|
||||
Using the setup hook ensures static windows and Tauri plugins are initialized.
|
||||
Alternatively, you can create a window after building the [App]:
|
||||
|
||||
```rust Using the built app
|
||||
let app = tauri::Builder::default()
|
||||
.build(tauri::generate_context!())
|
||||
.expect("error while building tauri application");
|
||||
|
||||
let docs_window = tauri::WindowBuilder::new(
|
||||
&app,
|
||||
"external", /* the unique window label */
|
||||
tauri::WindowUrl::External("https://tauri.app/".parse().unwrap())
|
||||
).build().expect("failed to build window");
|
||||
|
||||
let local_window = tauri::WindowBuilder::new(
|
||||
&app,
|
||||
"local",
|
||||
tauri::WindowUrl::App("index.html".into())
|
||||
).build()?;
|
||||
|
||||
// This will start the app and no other code below this will run.
|
||||
app.run(|_, _| {});
|
||||
```
|
||||
|
||||
This method is useful when you cannot move ownership of values to the setup closure.
|
||||
|
||||
##### Create a window using an [AppHandle] instance
|
||||
|
||||
An [AppHandle] instance can be obtained using the [`App::handle`] function or directly injected in Tauri commands.
|
||||
|
||||
```rust Create a window in a separate thread
|
||||
tauri::Builder::default()
|
||||
.setup(|app| {
|
||||
let handle = app.handle();
|
||||
std::thread::spawn(move || {
|
||||
let local_window = tauri::WindowBuilder::new(
|
||||
&handle,
|
||||
"local",
|
||||
tauri::WindowUrl::App("index.html".into())
|
||||
).build()?;
|
||||
});
|
||||
Ok(())
|
||||
})
|
||||
```
|
||||
|
||||
```rust Create a window in a Tauri command
|
||||
#[tauri::command]
|
||||
async fn open_docs(handle: tauri::AppHandle) {
|
||||
let docs_window = tauri::WindowBuilder::new(
|
||||
&handle,
|
||||
"external", /* the unique window label */
|
||||
tauri::WindowUrl::External("https://tauri.app/".parse().unwrap())
|
||||
).build().unwrap();
|
||||
}
|
||||
```
|
||||
|
||||
:::info
|
||||
|
||||
When creating windows in a Tauri command, ensure the command function is `async` to avoid a deadlock on Windows due to the [wry#583] issue.
|
||||
|
||||
:::
|
||||
|
||||
#### Create a window in JavaScript
|
||||
|
||||
Using the Tauri API you can easily create a window at runtime by importing the [WebviewWindow] class.
|
||||
|
||||
```js Create a window using the WebviewWindow class
|
||||
import { WebviewWindow } from "@tauri-apps/api/window";
|
||||
const webview = new WebviewWindow("theUniqueLabel", {
|
||||
url: "path/to/page.html",
|
||||
});
|
||||
// since the webview window is created asynchronously,
|
||||
// Tauri emits the `tauri://created` and `tauri://error` to notify you of the creation response
|
||||
webview.once("tauri://created", function () {
|
||||
// webview window successfully created
|
||||
});
|
||||
webview.once("tauri://error", function (e) {
|
||||
// an error occurred during webview window creation
|
||||
});
|
||||
```
|
||||
|
||||
## Creating additional HTML pages
|
||||
|
||||
If you want to create additional pages beyond `index.html`, you will need to make sure they are present in the `dist` directory at build time. How you do this depends on your frontend setup. If you use Vite, create an additional [input](https://vitejs.dev/guide/build.html#multi-page-app) for the second HTML page in `vite.config.js`.
|
||||
|
||||
## Accessing a window at runtime
|
||||
|
||||
The window instance can be queried using its label and the [get_window] method on Rust or [WebviewWindow.getByLabel] on JavaScript.
|
||||
|
||||
```rust Using get_window
|
||||
use tauri::Manager;
|
||||
tauri::Builder::default()
|
||||
.setup(|app| {
|
||||
let main_window = app.get_window("main").unwrap();
|
||||
Ok(())
|
||||
})
|
||||
```
|
||||
|
||||
Note that you must import [tauri::Manager] to use the [get_window] method on [App] or [AppHandle] instances.
|
||||
|
||||
```js Using WebviewWindow.getByLabel
|
||||
import { WebviewWindow } from "@tauri-apps/api/window";
|
||||
const mainWindow = WebviewWindow.getByLabel("main");
|
||||
```
|
||||
|
||||
## Communicating with other windows
|
||||
|
||||
Window communication can be done using the event system. See the [Event Guide] for more information.
|
||||
|
||||
[tauri.windows]: ../../api/config.md#tauriconfig.windows
|
||||
[windowconfig]: ../../api/config.md#windowconfig
|
||||
[windowbuilder]: https://docs.rs/tauri/1.0.0/tauri/window/struct.WindowBuilder.html
|
||||
[app]: https://docs.rs/tauri/1.0.0/tauri/struct.App.html
|
||||
[apphandle]: https://docs.rs/tauri/1.0.0/tauri/struct.AppHandle.html
|
||||
[builder::build]: https://docs.rs/tauri/1.0.0/tauri/struct.Builder.html#method.build
|
||||
[app::handle]: https://docs.rs/tauri/1.0.0/tauri/struct.App.html#method.handle
|
||||
[get_window]: https://docs.rs/tauri/1.0.0/tauri/trait.Manager.html#method.get_window
|
||||
[wry#583]: https://github.com/tauri-apps/wry/issues/583
|
||||
[webviewwindow]: ../../api/js/window.md#webviewwindow
|
||||
[webviewwindow.getbylabel]: ../../api/js/window.md#getbylabel
|
||||
[tauri::manager]: https://docs.rs/tauri/1.0.0/tauri/trait.Manager.html
|
||||
[event guide]: ./events.md
|
||||
@@ -1,179 +0,0 @@
|
||||
---
|
||||
title: plugin
|
||||
---
|
||||
|
||||
import Command from '@theme/Command'
|
||||
|
||||
# Tauri Plugins
|
||||
|
||||
Plugins allow you to hook into the Tauri application lifecycle and introduce new commands.
|
||||
|
||||
## Using a Plugin
|
||||
|
||||
To use a plugin, just pass the plugin instance to the App's `plugin` method:
|
||||
|
||||
```rust
|
||||
fn main() {
|
||||
tauri::Builder::default()
|
||||
.plugin(my_awesome_plugin::init())
|
||||
.run(tauri::generate_context!())
|
||||
.expect("failed to run app");
|
||||
}
|
||||
```
|
||||
|
||||
## Writing a Plugin
|
||||
|
||||
Plugins are reusable extensions to the Tauri API that solve common problems. They are also a very convenient way to structure your code base!
|
||||
|
||||
If you intend to share your plugin with others, we provide a ready-made template! With Tauri's [CLI](../../api/cli.md)installed just run:
|
||||
|
||||
<Command name="plugin init --name awesome" />
|
||||
|
||||
### API package
|
||||
|
||||
By default consumers of your plugin can call provided commands like this:
|
||||
|
||||
```js
|
||||
import { invoke } from "@tauri-apps/api";
|
||||
invoke("plugin:awesome|do_something");
|
||||
```
|
||||
|
||||
where `awesome` will be replaced by your plugin name.
|
||||
|
||||
This isn't very convenient, however, so it's common for plugins to provide a so-called _API package_, a JavaScript package that provides convenient access to your commands.
|
||||
|
||||
> An example of this is the [tauri-plugin-store](https://github.com/tauri-apps/tauri-plugin-store), which provides a convenient class structure for accessing a store.
|
||||
> You can scaffold a tauri plugin with an attached javascript API package like this:
|
||||
|
||||
<Command name="plugin init --name awesome --api" />
|
||||
|
||||
## Writing a Plugin
|
||||
|
||||
Using the `tauri::plugin::Builder` you can define plugins similar to how you define your app:
|
||||
|
||||
```rust
|
||||
use tauri::{
|
||||
plugin::{Builder, TauriPlugin},
|
||||
Runtime,
|
||||
};
|
||||
|
||||
// the plugin custom command handlers if you choose to extend the API:
|
||||
|
||||
#[tauri::command]
|
||||
// this will be accessible with `invoke('plugin:awesome|initialize')`.
|
||||
// where `awesome` is the plugin name.
|
||||
fn initialize() {}
|
||||
|
||||
#[tauri::command]
|
||||
// this will be accessible with `invoke('plugin:awesome|do_something')`.
|
||||
fn do_something() {}
|
||||
|
||||
pub fn init<R: Runtime>() -> TauriPlugin<R> {
|
||||
Builder::new("awesome")
|
||||
.invoke_handler(tauri::generate_handler![initialize, do_something])
|
||||
.build()
|
||||
}
|
||||
```
|
||||
|
||||
Plugins can set up and maintain state, just like your app can:
|
||||
|
||||
```rust
|
||||
use tauri::{
|
||||
plugin::{Builder, TauriPlugin},
|
||||
AppHandle, Manager, Runtime, State,
|
||||
};
|
||||
|
||||
#[derive(Default)]
|
||||
struct MyState {}
|
||||
|
||||
#[tauri::command]
|
||||
// this will be accessible with `invoke('plugin:awesome|do_something')`.
|
||||
fn do_something<R: Runtime>(_app: AppHandle<R>, state: State<'_, MyState>) {
|
||||
// you can access `MyState` here!
|
||||
}
|
||||
|
||||
pub fn init<R: Runtime>() -> TauriPlugin<R> {
|
||||
Builder::new("awesome")
|
||||
.invoke_handler(tauri::generate_handler![do_something])
|
||||
.setup(|app_handle| {
|
||||
// setup plugin specific state here
|
||||
app_handle.manage(MyState::default());
|
||||
Ok(())
|
||||
})
|
||||
.build()
|
||||
}
|
||||
```
|
||||
|
||||
### Conventions
|
||||
|
||||
- The crate exports an `init` method to create the plugin.
|
||||
- Plugins should have a clear name with `tauri-plugin-` prefix.
|
||||
- Include `tauri-plugin` keyword in `Cargo.toml`/`package.json`.
|
||||
- Document your plugin in English.
|
||||
- Add an example app showcasing your plugin.
|
||||
|
||||
### Advanced
|
||||
|
||||
Instead of relying on the `tauri::plugin::TauriPlugin` struct returned by `tauri::plugin::Builder::build`, you can implement the `tauri::plugin::Plugin` yourself. This allows you to have full control over the associated data.
|
||||
|
||||
Note that each function on the `Plugin` trait is optional, except the `name` function.
|
||||
|
||||
```rust
|
||||
use tauri::{plugin::{Plugin, Result as PluginResult}, Runtime, PageLoadPayload, Window, Invoke, AppHandle};
|
||||
|
||||
struct MyAwesomePlugin<R: Runtime> {
|
||||
invoke_handler: Box<dyn Fn(Invoke<R>) + Send + Sync>,
|
||||
// plugin state, configuration fields
|
||||
}
|
||||
|
||||
// the plugin custom command handlers if you choose to extend the API.
|
||||
#[tauri::command]
|
||||
// this will be accessible with `invoke('plugin:awesome|initialize')`.
|
||||
// where `awesome` is the plugin name.
|
||||
fn initialize() {}
|
||||
|
||||
#[tauri::command]
|
||||
// this will be accessible with `invoke('plugin:awesome|do_something')`.
|
||||
fn do_something() {}
|
||||
|
||||
impl<R: Runtime> MyAwesomePlugin<R> {
|
||||
// you can add configuration fields here,
|
||||
// see https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
|
||||
pub fn new() -> Self {
|
||||
Self {
|
||||
invoke_handler: Box::new(tauri::generate_handler![initialize, do_something]),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl<R: Runtime> Plugin<R> for MyAwesomePlugin<R> {
|
||||
/// The plugin name. Must be defined and used on the `invoke` calls.
|
||||
fn name(&self) -> &'static str {
|
||||
"awesome"
|
||||
}
|
||||
|
||||
/// The JS script to evaluate on initialization.
|
||||
/// Useful when your plugin is accessible through `window`
|
||||
/// or needs to perform a JS task on app initialization
|
||||
/// e.g. "window.awesomePlugin = { ... the plugin interface }"
|
||||
fn initialization_script(&self) -> Option<String> {
|
||||
None
|
||||
}
|
||||
|
||||
/// initialize plugin with the config provided on `tauri.conf.json > plugins > $yourPluginName` or the default value.
|
||||
fn initialize(&mut self, app: &AppHandle<R>, config: serde_json::Value) -> PluginResult<()> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Callback invoked when the Window is created.
|
||||
fn created(&mut self, window: Window<R>) {}
|
||||
|
||||
/// Callback invoked when the webview performs navigation.
|
||||
fn on_page_load(&mut self, window: Window<R>, payload: PageLoadPayload) {}
|
||||
|
||||
/// Extend the invoke handler.
|
||||
fn extend_api(&mut self, message: Invoke<R>) {
|
||||
(self.invoke_handler)(message)
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,116 +0,0 @@
|
||||
---
|
||||
title: splashscreen
|
||||
---
|
||||
|
||||
# Splashscreen
|
||||
|
||||
If your webpage could take some time to load, or if you need to run an initialization procedure in Rust before displaying your main window, a splashscreen could improve the loading experience for the user.
|
||||
|
||||
### Setup
|
||||
|
||||
First, create a `splashscreen.html` in your `distDir` that contains the HTML code for a splashscreen. Then, update your `tauri.conf.json` like so:
|
||||
|
||||
```diff
|
||||
"windows": [
|
||||
{
|
||||
"title": "Tauri App",
|
||||
"width": 800,
|
||||
"height": 600,
|
||||
"resizable": true,
|
||||
"fullscreen": false,
|
||||
+ "visible": false // Hide the main window by default
|
||||
},
|
||||
// Add the splashscreen window
|
||||
+ {
|
||||
+ "width": 400,
|
||||
+ "height": 200,
|
||||
+ "decorations": false,
|
||||
+ "url": "splashscreen.html",
|
||||
+ "label": "splashscreen"
|
||||
+ }
|
||||
]
|
||||
```
|
||||
|
||||
Now, your main window will be hidden and the splashscreen window will show when your app is launched. Next, you'll need a way to close the splashscreen and show the main window when your app is ready. How you do this depends on what you are waiting for before closing the splashscreen.
|
||||
|
||||
### Waiting for Webpage
|
||||
|
||||
If you are waiting for your web code, you'll want to create a `close_splashscreen` [command](command).
|
||||
|
||||
```rust src-tauri/main.rs
|
||||
use tauri::Manager;
|
||||
// Create the command:
|
||||
// This command must be async so that it doesn't run on the main thread.
|
||||
#[tauri::command]
|
||||
async fn close_splashscreen(window: tauri::Window) {
|
||||
// Close splashscreen
|
||||
if let Some(splashscreen) = window.get_window("splashscreen") {
|
||||
splashscreen.close().unwrap();
|
||||
}
|
||||
// Show main window
|
||||
window.get_window("main").unwrap().show().unwrap();
|
||||
}
|
||||
|
||||
// Register the command:
|
||||
fn main() {
|
||||
tauri::Builder::default()
|
||||
// Add this line
|
||||
.invoke_handler(tauri::generate_handler![close_splashscreen])
|
||||
.run(tauri::generate_context!())
|
||||
.expect("failed to run app");
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
You can then import it to your project in one of two ways:
|
||||
|
||||
```js
|
||||
// With the Tauri API npm package:
|
||||
import { invoke } from "@tauri-apps/api/tauri";
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```js
|
||||
// With the Tauri global script:
|
||||
const invoke = window.__TAURI__.invoke;
|
||||
```
|
||||
|
||||
And finally, add an Event Listener (or just call `invoke()` whenever you want):
|
||||
|
||||
```js
|
||||
document.addEventListener("DOMContentLoaded", () => {
|
||||
// This will wait for the window to load, but you could
|
||||
// run this function on whatever trigger you want
|
||||
invoke("close_splashscreen");
|
||||
});
|
||||
```
|
||||
|
||||
### Waiting for Rust
|
||||
|
||||
If you are waiting for Rust code to run, put it in the `setup` function handler so you have access to the `App` instance:
|
||||
|
||||
```rust src-tauri/main.rs
|
||||
use tauri::Manager;
|
||||
fn main() {
|
||||
tauri::Builder::default()
|
||||
.setup(|app| {
|
||||
let splashscreen_window = app.get_window("splashscreen").unwrap();
|
||||
let main_window = app.get_window("main").unwrap();
|
||||
// we perform the initialization code on a new task so the app doesn't freeze
|
||||
tauri::async_runtime::spawn(async move {
|
||||
// initialize your app here instead of sleeping :)
|
||||
println!("Initializing...");
|
||||
std::thread::sleep(std::time::Duration::from_secs(2));
|
||||
println!("Done initializing.");
|
||||
|
||||
// After it's done, close the splashscreen and display the main window
|
||||
splashscreen_window.close().unwrap();
|
||||
main_window.show().unwrap();
|
||||
});
|
||||
Ok(())
|
||||
})
|
||||
.run(tauri::generate_context!())
|
||||
.expect("failed to run app");
|
||||
}
|
||||
```
|
||||
@@ -1,239 +0,0 @@
|
||||
---
|
||||
title: system tray
|
||||
---
|
||||
|
||||
# System Tray
|
||||
|
||||
Native application system tray.
|
||||
|
||||
### Setup
|
||||
|
||||
Configure the `systemTray` object on `tauri.conf.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"systemTray": {
|
||||
"iconPath": "icons/icon.png",
|
||||
"iconAsTemplate": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `iconAsTemplate` is a boolean value that determines whether the image represents a [Template Image] on macOS.
|
||||
|
||||
#### Linux Setup
|
||||
|
||||
On Linux, you need to install one of `libayatana-appindicator` or `libappindicator3` packages.
|
||||
Tauri determines which package to use at runtime, with `libayatana` being the preferred one if both are installed.
|
||||
|
||||
By default, the Debian package (`.deb` file) will add a dependency on `libayatana-appindicator3-1`. To create a Debian package targetting `libappindicator3`, set the `TAURI_TRAY` environment variable to `libappindicator3`.
|
||||
|
||||
The AppImage bundle automatically embeds the installed tray library, and you can also use the `TAURI_TRAY` environment variable to manually select it.
|
||||
|
||||
:::info
|
||||
|
||||
`libappindicator3` is unmaintained and does not exist on some distros like `debian11`, but `libayatana-appindicator` does not exist on older releases.
|
||||
|
||||
:::
|
||||
|
||||
### Creating a system tray
|
||||
|
||||
To create a native system tray, import the `SystemTray` type:
|
||||
|
||||
```rust
|
||||
use tauri::SystemTray;
|
||||
```
|
||||
|
||||
Initialize a new tray instance:
|
||||
|
||||
```rust
|
||||
let tray = SystemTray::new();
|
||||
```
|
||||
|
||||
### Configuring a system tray context menu
|
||||
|
||||
Optionally you can add a context menu that is visible when the tray icon is right-clicked. Import the `SystemTrayMenu`, `SystemTrayMenuItem` and `CustomMenuItem` types:
|
||||
|
||||
```rust
|
||||
use tauri::{CustomMenuItem, SystemTrayMenu, SystemTrayMenuItem};
|
||||
```
|
||||
|
||||
Create the `SystemTrayMenu`:
|
||||
|
||||
```rust
|
||||
// here `"quit".to_string()` defines the menu item id, and the second parameter is the menu item label.
|
||||
let quit = CustomMenuItem::new("quit".to_string(), "Quit");
|
||||
let hide = CustomMenuItem::new("hide".to_string(), "Hide");
|
||||
let tray_menu = SystemTrayMenu::new()
|
||||
.add_item(quit)
|
||||
.add_native_item(SystemTrayMenuItem::Separator)
|
||||
.add_item(hide);
|
||||
```
|
||||
|
||||
Add the tray menu to the `SystemTray` instance:
|
||||
|
||||
```rust
|
||||
let tray = SystemTray::new().with_menu(tray_menu);
|
||||
```
|
||||
|
||||
### Configure the app system tray
|
||||
|
||||
The created `SystemTray` instance can be set using the `system_tray` API on the `tauri::Builder` struct:
|
||||
|
||||
```rust
|
||||
use tauri::{CustomMenuItem, SystemTray, SystemTrayMenu};
|
||||
|
||||
fn main() {
|
||||
let tray_menu = SystemTrayMenu::new(); // insert the menu items here
|
||||
let system_tray = SystemTray::new()
|
||||
.with_menu(tray_menu);
|
||||
tauri::Builder::default()
|
||||
.system_tray(system_tray)
|
||||
.run(tauri::generate_context!())
|
||||
.expect("error while running tauri application");
|
||||
}
|
||||
```
|
||||
|
||||
### Listening to system tray events
|
||||
|
||||
Each `CustomMenuItem` triggers an event when clicked.
|
||||
Also, Tauri emits tray icon click events.
|
||||
Use the `on_system_tray_event` API to handle them:
|
||||
|
||||
```rust
|
||||
use tauri::{CustomMenuItem, SystemTray, SystemTrayMenu, SystemTrayEvent};
|
||||
use tauri::Manager;
|
||||
|
||||
fn main() {
|
||||
let tray_menu = SystemTrayMenu::new(); // insert the menu items here
|
||||
tauri::Builder::default()
|
||||
.system_tray(SystemTray::new().with_menu(tray_menu))
|
||||
.on_system_tray_event(|app, event| match event {
|
||||
SystemTrayEvent::LeftClick {
|
||||
position: _,
|
||||
size: _,
|
||||
..
|
||||
} => {
|
||||
println!("system tray received a left click");
|
||||
}
|
||||
SystemTrayEvent::RightClick {
|
||||
position: _,
|
||||
size: _,
|
||||
..
|
||||
} => {
|
||||
println!("system tray received a right click");
|
||||
}
|
||||
SystemTrayEvent::DoubleClick {
|
||||
position: _,
|
||||
size: _,
|
||||
..
|
||||
} => {
|
||||
println!("system tray received a double click");
|
||||
}
|
||||
SystemTrayEvent::MenuItemClick { id, .. } => {
|
||||
match id.as_str() {
|
||||
"quit" => {
|
||||
std::process::exit(0);
|
||||
}
|
||||
"hide" => {
|
||||
let window = app.get_window("main").unwrap();
|
||||
window.hide().unwrap();
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
_ => {}
|
||||
})
|
||||
.run(tauri::generate_context!())
|
||||
.expect("error while running tauri application");
|
||||
}
|
||||
```
|
||||
|
||||
### Updating system tray
|
||||
|
||||
The `AppHandle` struct has a `tray_handle` method, which returns a handle to the system tray allowing updating tray icon and context menu items:
|
||||
|
||||
#### Updating context menu items
|
||||
|
||||
```rust
|
||||
use tauri::{CustomMenuItem, SystemTray, SystemTrayMenu, SystemTrayEvent};
|
||||
use tauri::Manager;
|
||||
|
||||
fn main() {
|
||||
let tray_menu = SystemTrayMenu::new(); // insert the menu items here
|
||||
tauri::Builder::default()
|
||||
.system_tray(SystemTray::new().with_menu(tray_menu))
|
||||
.on_system_tray_event(|app, event| match event {
|
||||
SystemTrayEvent::MenuItemClick { id, .. } => {
|
||||
// get a handle to the clicked menu item
|
||||
// note that `tray_handle` can be called anywhere,
|
||||
// just get an `AppHandle` instance with `app.handle()` on the setup hook
|
||||
// and move it to another function or thread
|
||||
let item_handle = app.tray_handle().get_item(&id);
|
||||
match id.as_str() {
|
||||
"hide" => {
|
||||
let window = app.get_window("main").unwrap();
|
||||
window.hide().unwrap();
|
||||
// you can also `set_selected`, `set_enabled` and `set_native_image` (macOS only).
|
||||
item_handle.set_title("Show").unwrap();
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
_ => {}
|
||||
})
|
||||
.run(tauri::generate_context!())
|
||||
.expect("error while running tauri application");
|
||||
}
|
||||
```
|
||||
|
||||
#### Updating tray icon
|
||||
|
||||
Note that you need to add `icon-ico` or `icon-png` feature flag to the tauri dependency in your Cargo.toml to be able to use `Icon::Raw`
|
||||
|
||||
```rust
|
||||
app.tray_handle().set_icon(tauri::Icon::Raw(include_bytes!("../path/to/myicon.ico").to_vec())).unwrap();
|
||||
```
|
||||
|
||||
### Preventing the App from Closing
|
||||
|
||||
By default, Tauri closes the application when the last window is closed. You can simply call `api.prevent_close()` to prevent this.
|
||||
|
||||
Depending on your needs you can use one of the two following options:
|
||||
|
||||
**Keep the Backend Running in the Background**
|
||||
|
||||
If your backend should run in the background, you can call `api.prevent_exit()` like so:
|
||||
|
||||
```rust
|
||||
tauri::Builder::default()
|
||||
.build(tauri::generate_context!())
|
||||
.expect("error while building tauri application")
|
||||
.run(|_app_handle, event| match event {
|
||||
tauri::RunEvent::ExitRequested { api, .. } => {
|
||||
api.prevent_exit();
|
||||
}
|
||||
_ => {}
|
||||
});
|
||||
```
|
||||
|
||||
**Keep the Frontend Running in the Background**
|
||||
|
||||
If you need to keep the frontend running in the background, this can be achieved like this:
|
||||
|
||||
```rust
|
||||
tauri::Builder::default().on_window_event(|event| match event.event() {
|
||||
tauri::WindowEvent::CloseRequested { api, .. } => {
|
||||
event.window().hide().unwrap();
|
||||
api.prevent_close();
|
||||
}
|
||||
_ => {}
|
||||
})
|
||||
.run(tauri::generate_context!())
|
||||
.expect("error while running tauri application");
|
||||
```
|
||||
|
||||
[template image]: https://developer.apple.com/documentation/appkit/nsimage/1520017-template?language=objc
|
||||
[libayatana-appindicator]: https://github.com/AyatanaIndicators/libayatana-appindicator
|
||||
@@ -1,121 +0,0 @@
|
||||
---
|
||||
title: window customization
|
||||
---
|
||||
|
||||
# Window Customization
|
||||
|
||||
Tauri provides lots of options for customizing the look and feel of your app's window. You can create custom titlebars, have transparent windows, enforce size constraints, and more.
|
||||
|
||||
## Configuration
|
||||
|
||||
There are three ways to change the window configuration:
|
||||
|
||||
- [Through tauri.conf.json](../../api/config.md#tauri.windows)
|
||||
- [Through the JS API](../../api/js/window.md#webviewwindow)
|
||||
- [Through the Window in Rust](https://docs.rs/tauri/1/tauri/window/struct.Window.html)
|
||||
|
||||
## Creating a Custom Titlebar
|
||||
|
||||
A common use of these window features is creating a custom titlebar. This short tutorial will guide you through that process.
|
||||
|
||||
### CSS
|
||||
|
||||
You'll need to add some CSS for the titlebar to keep it at the top of the screen and style the buttons:
|
||||
|
||||
```css
|
||||
.titlebar {
|
||||
height: 30px;
|
||||
background: #329ea3;
|
||||
user-select: none;
|
||||
display: flex;
|
||||
justify-content: flex-end;
|
||||
position: fixed;
|
||||
top: 0;
|
||||
left: 0;
|
||||
right: 0;
|
||||
}
|
||||
.titlebar-button {
|
||||
display: inline-flex;
|
||||
justify-content: center;
|
||||
align-items: center;
|
||||
width: 30px;
|
||||
height: 30px;
|
||||
}
|
||||
.titlebar-button:hover {
|
||||
background: #5bbec3;
|
||||
}
|
||||
```
|
||||
|
||||
### HTML
|
||||
|
||||
Now, you'll need to add the HTML for the titlebar. Put this at the top of your `<body>` tag:
|
||||
|
||||
```html
|
||||
<div data-tauri-drag-region class="titlebar">
|
||||
<div class="titlebar-button" id="titlebar-minimize">
|
||||
<img
|
||||
src="https://api.iconify.design/mdi:window-minimize.svg"
|
||||
alt="minimize"
|
||||
/>
|
||||
</div>
|
||||
<div class="titlebar-button" id="titlebar-maximize">
|
||||
<img
|
||||
src="https://api.iconify.design/mdi:window-maximize.svg"
|
||||
alt="maximize"
|
||||
/>
|
||||
</div>
|
||||
<div class="titlebar-button" id="titlebar-close">
|
||||
<img src="https://api.iconify.design/mdi:close.svg" alt="close" />
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
Note that you may need to move the rest of your content down so that the titlebar doesn't cover it.
|
||||
|
||||
### JS
|
||||
|
||||
Finally, you'll need to make the buttons work:
|
||||
|
||||
```js
|
||||
import { appWindow } from "@tauri-apps/api/window";
|
||||
document
|
||||
.getElementById("titlebar-minimize")
|
||||
.addEventListener("click", () => appWindow.minimize());
|
||||
document
|
||||
.getElementById("titlebar-maximize")
|
||||
.addEventListener("click", () => appWindow.toggleMaximize());
|
||||
document
|
||||
.getElementById("titlebar-close")
|
||||
.addEventListener("click", () => appWindow.close());
|
||||
```
|
||||
|
||||
### tauri.conf.json
|
||||
|
||||
To make calls to `appWindow` work don't forget to add [window](../../api/js/window.md) permissions in `tauri.conf.json` file:
|
||||
|
||||
```json
|
||||
"tauri": {
|
||||
"allowList": {
|
||||
...
|
||||
"window": {
|
||||
"all": false,
|
||||
"close": true,
|
||||
"hide": true,
|
||||
"show": true,
|
||||
"maximize": true,
|
||||
"minimize": true,
|
||||
"unmaximize": true,
|
||||
"unminimize": true,
|
||||
"startDragging": true
|
||||
}
|
||||
}
|
||||
...
|
||||
|
||||
"windows": [
|
||||
{
|
||||
"decorations": false,
|
||||
...
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -1,388 +0,0 @@
|
||||
---
|
||||
title: prerequisites
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Prerequisites
|
||||
|
||||
## Installing
|
||||
|
||||
The first step is to install [Rust] and system dependencies. Keep in mind that this setup is only needed for _developing Tauri apps_. Your end-users are not required to do any of this.
|
||||
|
||||
### Setting Up Windows
|
||||
|
||||
#### 1. Microsoft Visual Studio C++ Build Tools
|
||||
|
||||
You will need to install Microsoft Visual Studio C++ build tools. The easiest way is to install [Build Tools for Visual Studio 2022]. When asked which workloads to install, ensure "C++ build tools" and the Windows 10 SDK are selected.
|
||||
|
||||
<figure>
|
||||
|
||||
|
||||
|
||||
|
||||
<figcaption>Listing 1-1: Selecting "C++ build tools" and "Windows 10 SDK" using the Visual Studio Build Tools 2022 installer.</figcaption>
|
||||
</figure>
|
||||
|
||||
#### 2. WebView2
|
||||
|
||||
:::note
|
||||
|
||||
On Windows 10 (Version 1803 and later with all updates applied) and Windows 11, the WebView2 runtime is distributed as part of the operating system.
|
||||
|
||||
:::
|
||||
|
||||
Tauri heavily depends on WebView2 to render web content on Windows, therefore you must have WebView2 installed. The easiest way is to download and run the Evergreen Bootstrapper from [Microsoft's website][download webview2].
|
||||
|
||||
The bootstrapper script will try to determine the correct architecture and version for your system. Still, if you run into issues (especially with Windows on ARM) you can select the correct standalone installer.
|
||||
|
||||
#### 3. Rust
|
||||
|
||||
Lastly, go to [https://www.rust-lang.org/tools/install][install rust] to install `rustup` (the Rust installer). Note that you have to restart your terminal, and in some cases, Windows itself, for the changes to take effect.
|
||||
|
||||
Alternatively, you could use `winget` to install rustup using the following command in PowerShell:
|
||||
|
||||
```powershell
|
||||
winget install --id Rustlang.Rustup
|
||||
```
|
||||
|
||||
:::caution MSVC toolchain as default
|
||||
|
||||
For full support for Tauri and tools like [`trunk`] make sure the MSVC Rust toolchain is the selected `default host triple` in the installer dialog. Depending on your system it should be either `x86_64-pc-windows-msvc`, `i686-pc-windows-msvc`, or `aarch64-pc-windows-msvc`.
|
||||
|
||||
If you already have Rust installed, you can make sure the correct toolchain is installed by running this command:
|
||||
|
||||
```powershell
|
||||
rustup default stable-msvc
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### Setting Up macOS
|
||||
|
||||
#### 1. CLang and macOS Development Dependencies
|
||||
|
||||
You will need to install CLang and macOS development dependencies. To do this, run the following command in your terminal:
|
||||
|
||||
```shell
|
||||
xcode-select --install
|
||||
```
|
||||
|
||||
#### 2. Rust
|
||||
|
||||
To install Rust on macOS, open a terminal and enter the following command:
|
||||
|
||||
```shell
|
||||
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
We have audited this bash script, and it does what it says it is supposed to do. Nevertheless, before blindly curl-bashing a script, it is always wise to look at it first. Here is the file as a plain script: [rustup.sh]
|
||||
|
||||
:::
|
||||
|
||||
The command downloads a script and starts the installation of the `rustup` tool, which installs the latest stable version of Rust. You might be prompted for your password. If the installation was
|
||||
successful, the following line will appear:
|
||||
|
||||
```text
|
||||
Rust is installed now. Great!
|
||||
```
|
||||
|
||||
Make sure to restart your terminal for the changes to take effect.
|
||||
|
||||
### Setting Up Linux
|
||||
|
||||
#### 1. System Dependencies
|
||||
|
||||
You will need to install a couple of system dependencies, such as a C compiler and `webkit2gtk`. Below are commands for a few popular distributions:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="debian" label="Debian" default>
|
||||
|
||||
```sh
|
||||
sudo apt update
|
||||
sudo apt install libwebkit2gtk-4.0-dev \
|
||||
build-essential \
|
||||
curl \
|
||||
wget \
|
||||
file \
|
||||
libssl-dev \
|
||||
libgtk-3-dev \
|
||||
libayatana-appindicator3-dev \
|
||||
librsvg2-dev
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="arch" label="Arch">
|
||||
|
||||
```sh
|
||||
sudo pacman -Syu
|
||||
sudo pacman -S --needed \
|
||||
webkit2gtk \
|
||||
base-devel \
|
||||
curl \
|
||||
wget \
|
||||
file \
|
||||
openssl \
|
||||
appmenu-gtk-module \
|
||||
gtk3 \
|
||||
libappindicator-gtk3 \
|
||||
librsvg \
|
||||
libvips
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fedora" label="Fedora">
|
||||
|
||||
```sh
|
||||
sudo dnf check-update
|
||||
sudo dnf install webkit2gtk4.0-devel \
|
||||
openssl-devel \
|
||||
curl \
|
||||
wget \
|
||||
file \
|
||||
libappindicator-gtk3-devel \
|
||||
librsvg2-devel
|
||||
sudo dnf group install "C Development Tools and Libraries"
|
||||
```
|
||||
|
||||
Note that on Fedora 36 and below the `webkit2gtk4.0-devel` package was called `webkit2gtk3-devel`.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="gentoo" label="Gentoo">
|
||||
|
||||
```sh
|
||||
sudo emerge --ask \
|
||||
net-libs/webkit-gtk:4 \
|
||||
dev-libs/libappindicator \
|
||||
net-misc/curl \
|
||||
net-misc/wget \
|
||||
sys-apps/file
|
||||
```
|
||||
|
||||
Note: A desktop profile is recommended to set the appropriate USE flags for webkit-gtk
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="opensuse" label="openSUSE">
|
||||
|
||||
```sh
|
||||
sudo zypper up
|
||||
sudo zypper in webkit2gtk3-soup2-devel \
|
||||
libopenssl-devel \
|
||||
curl \
|
||||
wget \
|
||||
file \
|
||||
libappindicator3-1 \
|
||||
librsvg-devel
|
||||
sudo zypper in -t pattern devel_basis
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="nixos" label="NixOS">
|
||||
|
||||
Working on NixOS requires a slightly different setup, as Tauri needs to find the required system libraries both at compile time and
|
||||
dynamically at runtime. To make them available to Tauri the `LD_LIBRARY_PATH` environment variable needs to be populated with the correct paths.
|
||||
|
||||
When using [Nix Flakes], copy the following code into `flake.nix` on your repository, then run `nix develop` to activate the development environment. You can also use [direnv's Flakes integration] to automatically start the dev shell when entering the project folder.
|
||||
|
||||
```nix
|
||||
{
|
||||
inputs = {
|
||||
nixpkgs.url = "nixpkgs";
|
||||
flake-utils.url = "github:numtide/flake-utils";
|
||||
};
|
||||
|
||||
outputs = { self, nixpkgs, flake-utils }:
|
||||
flake-utils.lib.eachDefaultSystem (system:
|
||||
let
|
||||
pkgs = nixpkgs.legacyPackages.${system};
|
||||
|
||||
libraries = with pkgs;[
|
||||
webkitgtk
|
||||
gtk3
|
||||
cairo
|
||||
gdk-pixbuf
|
||||
glib
|
||||
dbus
|
||||
openssl_3
|
||||
librsvg
|
||||
];
|
||||
|
||||
packages = with pkgs; [
|
||||
curl
|
||||
wget
|
||||
pkg-config
|
||||
dbus
|
||||
openssl_3
|
||||
glib
|
||||
gtk3
|
||||
libsoup
|
||||
webkitgtk
|
||||
librsvg
|
||||
];
|
||||
in
|
||||
{
|
||||
devShell = pkgs.mkShell {
|
||||
buildInputs = packages;
|
||||
|
||||
shellHook =
|
||||
''
|
||||
export LD_LIBRARY_PATH=${pkgs.lib.makeLibraryPath libraries}:$LD_LIBRARY_PATH
|
||||
'';
|
||||
};
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
If you don't use Nix Flakes, the [Nix Shell] can be configured using the following `shell.nix` script. Run `nix-shell` to activate the development environment, or use [direnv's Shell integration] to automatically start the dev shell when entering the project folder.
|
||||
|
||||
```nix
|
||||
let
|
||||
pkgs = import <nixpkgs> { };
|
||||
|
||||
libraries = with pkgs;[
|
||||
webkitgtk
|
||||
gtk3
|
||||
cairo
|
||||
gdk-pixbuf
|
||||
glib
|
||||
dbus
|
||||
openssl_3
|
||||
];
|
||||
|
||||
packages = with pkgs; [
|
||||
pkg-config
|
||||
dbus
|
||||
openssl_3
|
||||
glib
|
||||
gtk3
|
||||
libsoup
|
||||
webkitgtk
|
||||
appimagekit
|
||||
];
|
||||
in
|
||||
pkgs.mkShell {
|
||||
buildInputs = packages;
|
||||
|
||||
shellHook =
|
||||
''
|
||||
export LD_LIBRARY_PATH=${pkgs.lib.makeLibraryPath libraries}:$LD_LIBRARY_PATH
|
||||
'';
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="gnu_guix" label="GNU Guix">
|
||||
|
||||
To create Tauri development environments using [Guix shell], copy the following code into `manifest.scm` on your repository, then run `guix shell` to activate. You can also use [direnv's Guix shell support] to automatically start the Guix shell when entering the project folder.
|
||||
|
||||
```scheme
|
||||
(specifications->manifest
|
||||
(list "gtk+@3"
|
||||
"webkitgtk-with-libsoup2"
|
||||
"libsoup-minimal@2"
|
||||
"cairo"
|
||||
"gdk-pixbuf"
|
||||
"glib"
|
||||
"dbus"
|
||||
"openssl@3"
|
||||
"gcc:lib"
|
||||
|
||||
"curl"
|
||||
"wget"
|
||||
"file"
|
||||
"pkg-config"
|
||||
"gsettings-desktop-schemas"))
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="void" label="Void">
|
||||
|
||||
```sh
|
||||
sudo xbps-install -Syu
|
||||
sudo xbps-install -S \
|
||||
webkit2gtk-devel \
|
||||
curl \
|
||||
wget \
|
||||
file \
|
||||
openssl \
|
||||
gtk+3-devel \
|
||||
libappindicator \
|
||||
librsvg-devel \
|
||||
gcc \
|
||||
pkg-config
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
#### 2. Rust
|
||||
|
||||
To install Rust on Linux, open a terminal and enter the following command:
|
||||
|
||||
```shell
|
||||
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
We have audited this bash script, and it does what it says it is supposed to do. Nevertheless, before blindly curl-bashing a script, it is always wise to look at it first. Here is the file as a plain script: [rustup.sh]
|
||||
|
||||
:::
|
||||
|
||||
The command downloads a script and starts the installation of the `rustup` tool, which installs the latest stable version of Rust. You might be prompted for your password. If the installation was successful, the following line will appear:
|
||||
|
||||
```text
|
||||
Rust is installed now. Great!
|
||||
```
|
||||
|
||||
Make sure to restart your Terminal for the changes to take effect.
|
||||
|
||||
## Managing The Rust Installation
|
||||
|
||||
You should keep your Rust version up to date whenever possible to always benefit from the latest improvements. To update Rust, open a terminal and run the following command:
|
||||
|
||||
```shell
|
||||
rustup update
|
||||
```
|
||||
|
||||
`rustup` can also be used to uninstall Rust from your machine fully:
|
||||
|
||||
```shell
|
||||
rustup self uninstall
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
To check whether you have Rust installed correctly, open a shell and enter this command:
|
||||
|
||||
```shell
|
||||
rustc --version
|
||||
```
|
||||
|
||||
You should see the version number, commit hash, and commit date for the latest stable version that has been released in the following format:
|
||||
|
||||
```text
|
||||
rustc x.y.z (abcabcabc yyyy-mm-dd)
|
||||
```
|
||||
|
||||
If you don't see this information, your Rust installation might be broken. Please consult [Rust's Troubleshooting Section] on how to fix this. If your problems persist, you can get help from the official [Tauri Discord] and [GitHub Discussions].
|
||||
|
||||
[rust]: https://www.rust-lang.org
|
||||
[install rust]: https://www.rust-lang.org/tools/install
|
||||
[build tools for visual studio 2022]: https://visualstudio.microsoft.com/visual-cpp-build-tools/
|
||||
[`cargo-edit`]: https://github.com/killercup/cargo-edit
|
||||
[rust's troubleshooting section]: https://doc.rust-lang.org/book/ch01-01-installation.html#troubleshooting
|
||||
[tauri discord]: https://discord.com/invite/tauri
|
||||
[github discussions]: https://github.com/tauri-apps/tauri/discussions
|
||||
[download webview2]: https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download-section
|
||||
[rustup.sh]: https://sh.rustup.rs
|
||||
[nix flakes]: https://nixos.wiki/wiki/Flakes
|
||||
[direnv's flakes integration]: https://nixos.wiki/wiki/Flakes#Direnv_integration
|
||||
[nix shell]: https://nixos.wiki/wiki/Development_environment_with_nix-shell
|
||||
[direnv's shell integration]: https://nixos.wiki/wiki/Development_environment_with_nix-shell#direnv
|
||||
[direnv's Guix shell support]: https://github.com/direnv/direnv/pull/1045/files
|
||||
[Guix shell]: https://guix.gnu.org/manual/en/html_node/Invoking-guix-shell.html
|
||||
[`trunk`]: https://trunkrs.dev
|
||||
@@ -1,35 +0,0 @@
|
||||
---
|
||||
title: setup
|
||||
---
|
||||
|
||||
import DocCardList from "@theme/DocCardList";
|
||||
import { useCurrentSidebarCategory } from "@docusaurus/theme-common";
|
||||
import { CreateTauriApp } from "@theme/Command";
|
||||
|
||||
# Quick Start
|
||||
|
||||
Tauri is compatible with **almost every frontend stack**. Select yours and get started!
|
||||
|
||||
:::tip `create-tauri-app`
|
||||
|
||||
The easiest way to scaffold a new project is the [`create-tauri-app`] utility. It provides opinionated templates for vanilla HTML/CSS/JavaScript and many frontend frameworks like React, Svelte, and Yew.
|
||||
|
||||
<CreateTauriApp />
|
||||
|
||||
Note that you do not need to follow the below guides if you use `create-tauri-app`, but we still recommend reading one (such as the [HTML/CSS/JavaScript] guide) to understand the setup.
|
||||
|
||||
:::
|
||||
|
||||
If you're unfamiliar with web development or have no favorite frontend stack you might find the [HTML/CSS/JavaScript] guide the most helpful. It guides you through getting started with the most minimal frontend setup possible using either Node or Cargo.
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items} />
|
||||
|
||||
:::info Missing your favorite framework?
|
||||
|
||||
If you miss your favorite frontend framework or build tool, we're always looking for Getting Started guides! Read our [contributing] guidelines and help us out!
|
||||
|
||||
:::
|
||||
|
||||
[html/css/javascript]: ./html-css-js.mdx
|
||||
[contributing]: https://github.com/tauri-apps/tauri/blob/dev/.github/CONTRIBUTING.md
|
||||
[`create-tauri-app`]: https://github.com/tauri-apps/create-tauri-app
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
title: TODO
|
||||
---
|
||||
|
||||
Tauri lets you enhance your frontend with native capabilities. We call these [Commands][command], essentially Rust functions that you can call from your frontend JavaScript. This enables you to handle heavy processing or calls to the OS in much more performant Rust code.
|
||||
|
||||
Let's make a simple example:
|
||||
|
||||
```rust title=src-tauri/src/main.rs
|
||||
#[tauri::command]
|
||||
fn greet(name: &str) -> String {
|
||||
format!("Hello, {}!", name)
|
||||
}
|
||||
```
|
||||
|
||||
A Command is just like any regular Rust function, with the addition of the `#[tauri::command]` attribute macro that allows your function to communicate with the JavaScript context.
|
||||
|
||||
Lastly, we also need to tell Tauri about our newly created command so that it can route calls accordingly. This is done with the combination of the `.invoke_handler()` function and the `generate_handler![]` macro you can see below:
|
||||
|
||||
```rust title=src-tauri/src/main.rs
|
||||
fn main() {
|
||||
tauri::Builder::default()
|
||||
// highlight-next-line
|
||||
.invoke_handler(tauri::generate_handler![greet])
|
||||
.run(tauri::generate_context!())
|
||||
.expect("error while running tauri application");
|
||||
}
|
||||
```
|
||||
|
||||
Now you're ready to call your Command from the frontend!
|
||||
|
||||
[command]: ../../../features/command.md
|
||||
@@ -1,17 +0,0 @@
|
||||
---
|
||||
title: TODO
|
||||
---
|
||||
|
||||
import { CreateTauriApp } from "@theme/Command";
|
||||
|
||||
:::tip `create-tauri-app`
|
||||
|
||||
The easiest way to scaffold a new project is the [`create-tauri-app`] utility. It provides opinionated templates for vanilla HTML/CSS/JavaScript and many frontend frameworks like React, Svelte and Yew.
|
||||
|
||||
<CreateTauriApp />
|
||||
|
||||
Please note that you do not need to follow the rest of this guide if you use `create-tauri-app`, but we still recommend reading it to understand the setup.
|
||||
|
||||
:::
|
||||
|
||||
[`create-tauri-app`]: https://github.com/tauri-apps/create-tauri-app
|
||||
@@ -1,18 +0,0 @@
|
||||
---
|
||||
title: TODO
|
||||
---
|
||||
|
||||
:::info
|
||||
|
||||
Before we continue, make sure you have completed the [prerequisites] to have a working development environment.
|
||||
|
||||
:::
|
||||
|
||||
Tauri is a framework to build desktop applications with any frontend framework and a Rust core. Each app consists of two parts:
|
||||
|
||||
1. Rust binary that creates the windows and exposes native functionality to those windows
|
||||
2. Frontend of your choice that produces the user interface inside the window
|
||||
|
||||
In the following, we will first scaffold the frontend, set up the Rust project, and lastly show you how to communicate between the two.
|
||||
|
||||
[prerequisites]: ../../prerequisites.md
|
||||
@@ -1,155 +0,0 @@
|
||||
---
|
||||
title: TODO
|
||||
---
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
import Command, { InstallTauriCli } from "@theme/Command";
|
||||
|
||||
At the heart of every Tauri app is a Rust binary that manages windows, the webview, and calls to the operating system through a Rust crate called `tauri`. This project is managed by [Cargo], the official package manager and general-purpose build tool for Rust.
|
||||
|
||||
Our Tauri CLI uses Cargo under the hood so you rarely need to interact with it directly. Cargo has many more useful features that are not exposed through our CLI, such as testing, linting, and formatting, so please refer to their [official docs][cargo commands] for more.
|
||||
|
||||
:::info Install Tauri CLI
|
||||
|
||||
If you haven't installed the Tauri CLI yet you can do so with one of the below commands. Aren't sure which to use? Check out the [FAQ entry].
|
||||
|
||||
<InstallTauriCli />
|
||||
|
||||
:::
|
||||
|
||||
To scaffold a minimal Rust project that is pre-configured to use Tauri, open a terminal and run the following command:
|
||||
|
||||
<Tabs groupId="package-manager">
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm run tauri init
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Yarn">
|
||||
|
||||
```shell
|
||||
yarn tauri init
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="pnpm">
|
||||
|
||||
```shell
|
||||
pnpm tauri init
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Cargo">
|
||||
|
||||
```shell
|
||||
cargo tauri init
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
It will walk you through a series of questions:
|
||||
|
||||
<ol>
|
||||
<li>
|
||||
<i>What is your app name?</i>
|
||||
<br />
|
||||
This will be the name of your final bundle and what the OS will call your
|
||||
app. You can use any name you want here.
|
||||
</li>
|
||||
<br />
|
||||
<li>
|
||||
<i>What should the window title be?</i>
|
||||
<br />
|
||||
This will be the title of the default main window. You can use any title you
|
||||
want here.
|
||||
</li>
|
||||
<br />
|
||||
<li>
|
||||
<i>
|
||||
Where are your web assets (HTML/CSS/JS) located relative to the{" "}
|
||||
<code><current dir>/src-tauri/tauri.conf.json</code> file that will
|
||||
be created?
|
||||
</i>
|
||||
<br />
|
||||
This is the path that Tauri will load your frontend assets from when
|
||||
building for <b>production</b>.{" "}
|
||||
{props.destDirExplination && (
|
||||
<div dangerouslySetInnerHTML={props.destDirExplination} />
|
||||
)}
|
||||
</li>
|
||||
<br />
|
||||
<li>
|
||||
<i>What is the URL of your dev server?</i>
|
||||
<br />
|
||||
This can be either a URL or a file path that Tauri will load during{" "}
|
||||
<b>development</b>.{" "}
|
||||
{props.devPathExplination && (
|
||||
<div dangerouslySetInnerHTML={props.devPathExplination} />
|
||||
)}
|
||||
</li>
|
||||
<br />
|
||||
<li>
|
||||
<i>What is your frontend dev command?</i>
|
||||
<br />
|
||||
This is the command used to start your frontend dev server.{" "}
|
||||
{props.beforeDevCommandExplination && (
|
||||
<div dangerouslySetInnerHTML={props.beforeDevCommandExplination} />
|
||||
)}
|
||||
</li>
|
||||
<br />
|
||||
<li>
|
||||
<i>What is your frontend build command?</i>
|
||||
<br />
|
||||
This is the command to build your frontend files.{" "}
|
||||
{props.beforeBuildCommandExplination && (
|
||||
<div dangerouslySetInnerHTML={props.beforeBuildCommandExplination} />
|
||||
)}
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
:::info
|
||||
|
||||
If you're familiar with Rust, you will notice that `tauri init` looks and works a lot like `cargo init`. You can just use `cargo init` and add the necessary Tauri dependencies if you prefer a fully manual setup.
|
||||
|
||||
:::
|
||||
|
||||
The `tauri init` command generates a folder called `src-tauri`. It's a convention for Tauri apps to place all core-related files into this folder. Let's quickly run through the contents of this folder:
|
||||
|
||||
- **`Cargo.toml`**
|
||||
Cargo's manifest file. You can declare Rust crates your app depends on, metadata about your app, and much more. For the full reference see [Cargo's Manifest Format][manifest-format].
|
||||
|
||||
- **`tauri.conf.json`**
|
||||
This file lets you configure and customize aspects of your Tauri application from the name of your app to the list of allowed APIs. See [Tauri's API Configuration][api config] for the full list of supported options and in-depth explanations for each.
|
||||
|
||||
- **`src/main.rs`**
|
||||
This is the entry point to your Rust program and the place where we bootstrap into Tauri. You will find two sections in it:
|
||||
|
||||
```rust title=src/main.rs
|
||||
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
|
||||
|
||||
fn main() {
|
||||
tauri::Builder::default()
|
||||
.run(tauri::generate_context!())
|
||||
.expect("error while running tauri application");
|
||||
}
|
||||
```
|
||||
|
||||
The line beginning with the [`cfg! macro`][cfg macro] serves just one purpose: it disables the command prompt window that would normally pop up on Windows if you run a bundled app. If you're on Windows, try to comment it out and see what happens.
|
||||
|
||||
The `main` function is the entry point and the first function that gets invoked when your program runs.
|
||||
|
||||
- **`icons`**
|
||||
Chances are you want a snazzy icon for your app! To get you going quickly, we included a set of default icons. You should switch these out before publishing your application. Learn more about the various icon formats in Tauri's [icons feature guide][icons].
|
||||
|
||||
[manifest-format]: https://doc.rust-lang.org/cargo/reference/manifest.html
|
||||
[cfg macro]: https://doc.rust-lang.org/rust-by-example/attribute/cfg.html
|
||||
[api config]: ../../../../api/config.md
|
||||
[icons]: ../../../features/icons.md
|
||||
[prerequisites]: ../../prerequisites.md
|
||||
[cargo]: https://doc.rust-lang.org/cargo/
|
||||
[cargo commands]: https://doc.rust-lang.org/cargo/commands/index.html
|
||||
[faq entry]: ../../../faq.md#node-or-cargo
|
||||
@@ -1,136 +0,0 @@
|
||||
---
|
||||
title: html css and js
|
||||
---
|
||||
|
||||
import TauriInit from './\_fragments/\_tauri-init.mdx'
|
||||
import Commands from './\_fragments/\_commands.mdx'
|
||||
import Intro from './\_fragments/\_intro.mdx'
|
||||
import CreateTauriAppGuide from './\_fragments/\_create-tauri-app-guide.mdx'
|
||||
import Command from '@theme/Command'
|
||||
|
||||
# HTML, CSS, and JavaScript
|
||||
|
||||
This guide will walk you through creating your first Tauri app using just HTML, CSS, and JavaScript. This is probably the best place to start if you are new to web development.
|
||||
|
||||
<Intro />
|
||||
<CreateTauriAppGuide />
|
||||
|
||||
Here's a preview of what we will be building:
|
||||
|
||||
|
||||
|
||||
|
||||
## Create the Frontend
|
||||
|
||||
We will create a very minimal UI using an HTML file. To keep things tidy though, let's create a separate folder for it:
|
||||
|
||||
```shell
|
||||
mkdir ui
|
||||
```
|
||||
|
||||
Next, create an `index.html` file inside of that folder with the following contents:
|
||||
|
||||
```html title=index.html
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Document</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Welcome from Tauri!</h1>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
We will keep the UI minimal for this guide, but feel free to play around with more content or add styling through CSS.
|
||||
|
||||
## Create the Rust Project
|
||||
|
||||
<TauriInit
|
||||
destDirExplination={{
|
||||
__html: 'Use <code>../ui</code> for this value.',
|
||||
}}
|
||||
devPathExplination={{
|
||||
__html: 'Use <code>../ui</code> for this value.',
|
||||
}}
|
||||
beforeDevCommandExplination={{
|
||||
__html: 'You can leave this blank since nothing needs to be compiled.',
|
||||
}}
|
||||
beforeBuildCommandExplination={{
|
||||
__html: 'You can leave this blank since nothing needs to be compiled.',
|
||||
}}
|
||||
/>
|
||||
|
||||
And that's it! Now you can run the following command in your terminal to start a development build of your app:
|
||||
|
||||
<Command name="dev" />
|
||||
|
||||
Preview of Application
|
||||
|
||||
|
||||
|
||||
|
||||
## Invoke Commands
|
||||
|
||||
<Commands />
|
||||
|
||||
We would normally be recommending the [`@tauri-apps/api`] package here, but since we're not using a bundler for this guide, please enable [`withGlobalTauri`] in your `tauri.conf.json` file:
|
||||
|
||||
```json title=tauri.conf.json
|
||||
{
|
||||
"build": {
|
||||
"beforeBuildCommand": "",
|
||||
"beforeDevCommand": "",
|
||||
"devPath": "../ui",
|
||||
"distDir": "../ui",
|
||||
// highlight-next-line
|
||||
"withGlobalTauri": true
|
||||
},
|
||||
```
|
||||
|
||||
This will inject a pre-bundled version of the API functions into your frontend.
|
||||
|
||||
You can now modify your `index.html` file to call your Command:
|
||||
|
||||
```html title=index.html
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Document</title>
|
||||
</head>
|
||||
<body>
|
||||
// highlight-start
|
||||
<h1 id="header">Welcome from Tauri!</h1>
|
||||
<script>
|
||||
// access the pre-bundled global API functions
|
||||
const { invoke } = window.__TAURI__.tauri;
|
||||
|
||||
// now we can call our Command!
|
||||
// You will see "Welcome from Tauri" replaced
|
||||
// by "Hello, World!"!
|
||||
invoke("greet", { name: "World" })
|
||||
// `invoke` returns a Promise
|
||||
.then((response) => {
|
||||
window.header.innerHTML = response;
|
||||
});
|
||||
</script>
|
||||
// highlight-end
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
If you want to know more about the communication between Rust and JavaScript, please read the Tauri [Inter-Process Communication][inter-process-communication] guide.
|
||||
|
||||
:::
|
||||
|
||||
[inter-process-communication]: ../../../references/architecture/inter-process-communication/readme.md
|
||||
[cargo]: https://doc.rust-lang.org/cargo/
|
||||
[prerequisites]: ../prerequisites.md
|
||||
[`withglobaltauri`]: ../../../api/config.md#buildconfig.withglobaltauri
|
||||
[`@tauri-apps/api`]: ../../../api/js/
|
||||
@@ -1,176 +0,0 @@
|
||||
---
|
||||
title: existing project
|
||||
---
|
||||
|
||||
import Commands from './\_fragments/\_commands.mdx'
|
||||
import TauriInit from './\_fragments/\_tauri-init.mdx'
|
||||
import Command, { InstallTauriCli, InstallTauriApi } from '@theme/Command'
|
||||
|
||||
# Integrate into Existing Project
|
||||
|
||||
If you already have an existing web project, this guide will walk you through integrating Tauri into your project, whether it is Node.js-based (like [Svelte], [React], [Vue], or [Angular]) or Rust-based (like [Yew] or [Dominator]).
|
||||
|
||||
:::info
|
||||
|
||||
Before we continue, make sure you have completed the [prerequisites] to have a working development environment.
|
||||
|
||||
:::
|
||||
|
||||
Although Tauri is compatible with nearly any frontend framework, we'll use a [React] project throughout this guide created using [create-react-app]. We'll be assuming you're starting with a project structure similar to this:
|
||||
|
||||
```
|
||||
.
|
||||
│── package.json
|
||||
│── public
|
||||
│ ╰── index.html
|
||||
╰── src
|
||||
│── App.css
|
||||
│── App.jsx
|
||||
│── index.css
|
||||
╰── index.js
|
||||
```
|
||||
|
||||
## Create the Rust Project
|
||||
|
||||
<TauriInit
|
||||
destDirExplination={{
|
||||
__html:
|
||||
"For the project example in this guide, this is <code>../build</code>. Note that it may be something different like <code>../dist</code> if you're using a different framework.",
|
||||
}}
|
||||
devPathExplination={{
|
||||
__html:
|
||||
"For the project example in this guide, this is <code>http://localhost:3000</code>. Note that it may be something different (or even a directory) if you're using a different framework.",
|
||||
}}
|
||||
beforeDevCommandExplination={{
|
||||
__html:
|
||||
'For the project example in this guide, this is <code>npm run start</code> (make sure to adapt this to use the package manager of your choice).',
|
||||
}}
|
||||
beforeBuildCommandExplination={{
|
||||
__html:
|
||||
'For the project example in this guide, this is <code>npm run build</code> (make sure to adapt this to use the package manager of your choice).',
|
||||
}}
|
||||
/>
|
||||
|
||||
And that's it, you have now added Tauri to your existing project and you should see a `src-tauri` directory that looks something like this:
|
||||
|
||||
```diff {9-14}
|
||||
│── package.json
|
||||
│── public
|
||||
│ ╰── index.html
|
||||
│── src
|
||||
│ │── App.css
|
||||
│ │── App.jsx
|
||||
│ │── index.css
|
||||
│ ╰── index.js
|
||||
╰── src-tauri
|
||||
│── Cargo.toml
|
||||
│── build.rs
|
||||
│── icons
|
||||
│── src
|
||||
╰── tauri.conf.json
|
||||
```
|
||||
|
||||
## Invoke Commands
|
||||
|
||||
<Commands />
|
||||
|
||||
There are two different ways you can invoke commands from your frontend project:
|
||||
|
||||
1. Using the [`@tauri-apps/api`] JavaScript library (preferred)
|
||||
2. Using [`withGlobalTauri`] to use a pre-bundled version of the Tauri API
|
||||
|
||||
We'll go through both below.
|
||||
|
||||
### Using JavaScript Library
|
||||
|
||||
To call our newly created command we will use the [`@tauri-apps/api`] JavaScript library. It provides access to core functionality such as windows, the filesystem, and more through convenient JavaScript abstractions. You can install it using your favorite JavaScript package manager:
|
||||
|
||||
<InstallTauriApi />
|
||||
|
||||
You can now import the `invoke` function from the library and use it to call our command:
|
||||
|
||||
```jsx title=src/App.jsx {4,7-12}
|
||||
import logo from './logo.svg';
|
||||
import './App.css';
|
||||
|
||||
import { invoke } from '@tauri-apps/api'
|
||||
|
||||
function App() {
|
||||
// now we can call our Command!
|
||||
// Right-click the application background and open the developer tools.
|
||||
// You will see "Hello, World!" printed in the console!
|
||||
invoke('greet', { name: 'World' })
|
||||
// `invoke` returns a Promise
|
||||
.then((response) => console.log(response))
|
||||
|
||||
return (
|
||||
// -- snip --
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Using `withGlobalTauri`
|
||||
|
||||
To interact with Tauri from your frontend without using the `@tauri-apps/api` JavaScript package you will need to enable [`withGlobalTauri`] in your `tauri.conf.json` file:
|
||||
|
||||
```json title=tauri.conf.json
|
||||
{
|
||||
"build": {
|
||||
"beforeBuildCommand": "npm run build",
|
||||
"beforeDevCommand": "npm run dev",
|
||||
"devPath": "http://localhost:3000",
|
||||
"distDir": "../build",
|
||||
// highlight-next-line
|
||||
"withGlobalTauri": true
|
||||
},
|
||||
```
|
||||
|
||||
This will inject a pre-bundled version of the API functions into your frontend.
|
||||
|
||||
You can now modify the `App.jsx` file to call your command:
|
||||
|
||||
```jsx title=src/App.js {4,7-12}
|
||||
import logo from './logo.svg';
|
||||
import './App.css';
|
||||
|
||||
// access the pre-bundled global API functions
|
||||
const { invoke } = window.__TAURI__.tauri
|
||||
|
||||
function App() {
|
||||
// now we can call our Command!
|
||||
// Right-click the application background and open the developer tools.
|
||||
// You will see "Hello, World!" printed in the console!
|
||||
invoke('greet', { name: 'World' })
|
||||
// `invoke` returns a Promise
|
||||
.then((response) => console.log(response))
|
||||
|
||||
return (
|
||||
// -- snip --
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Running Your App
|
||||
|
||||
You can now run the following command in your terminal to start a development build of your app:
|
||||
|
||||
<Command name="dev" />
|
||||
|
||||
:::tip
|
||||
|
||||
If you want to know more about the communication between Rust and JavaScript, please read the Tauri [Inter-Process Communication][inter-process-communication] guide.
|
||||
|
||||
:::
|
||||
|
||||
[prerequisites]: ../prerequisites.md
|
||||
[create-react-app]: https://reactjs.org/docs/create-a-new-react-app.html#create-react-app
|
||||
[svelte]: https://svelte.dev
|
||||
[react]: https://reactjs.org
|
||||
[vue]: https://vuejs.org
|
||||
[angular]: https://angular.io
|
||||
[yew]: https://yew.rs
|
||||
[dominator]: https://github.com/Pauan/rust-dominator
|
||||
[inter-process-communication]: ../../../references/architecture/inter-process-communication/readme.md
|
||||
[`withglobaltauri`]: ../../../api/config.md#buildconfig.withglobaltauri
|
||||
[invoke commands]: ./html-css-js.mdx#invoke-commands
|
||||
[`@tauri-apps/api`]: ../../../api/js/
|
||||
@@ -1,173 +0,0 @@
|
||||
---
|
||||
title: next js
|
||||
---
|
||||
|
||||
import TauriInit from './\_fragments/\_tauri-init.mdx'
|
||||
import Commands from './\_fragments/\_commands.mdx'
|
||||
import Intro from './\_fragments/\_intro.mdx'
|
||||
import Tabs from '@theme/Tabs'
|
||||
import TabItem from '@theme/TabItem'
|
||||
import Command, { InstallTauriApi } from '@theme/Command'
|
||||
|
||||
# Next.js
|
||||
|
||||
This guide will walk you through creating your first Tauri app using the React framework [Next.js].
|
||||
|
||||
<Intro />
|
||||
|
||||
Here's a preview of what we will be building:
|
||||
|
||||
|
||||
|
||||
|
||||
## Create the Frontend
|
||||
|
||||
[Next.js] is a React Framework that comes with both Server-Side Rendering (SSR) and Static-Site Generation (SSG) capabilities. To make Next.js work with Tauri we are going to use the SSG mode since it generates only static files that can be included in the final binary.
|
||||
|
||||
Next.js comes with a scaffolding utility similar to [`create-tauri-app`] that can quickly setup a new project from many pre-defined templates.
|
||||
For this guide, we will use the suggested default for all questions, including TypeScript support and the new `App Router` feature stabilized in v13.4. In case you use the the old `routes/` directory instead or on top of the `app/` directory, you still need to change the config as explained in the [Next.js Static Exports](#nextjs-static-exports) section but the way you use Tauri specific JS APIs will be different than described below.
|
||||
|
||||
<Tabs groupId="package-manager">
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npx create-next-app@latest --use-npm
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Yarn">
|
||||
|
||||
```shell
|
||||
yarn create next-app --use-yarn
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="pnpm">
|
||||
|
||||
```shell
|
||||
pnpm create next-app --use-pnpm
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
1. _Project name_
|
||||
This will be the name of your project. It corresponds to the name of the folder this utility will create but has otherwise no effect on your app. You can use any name you want here.
|
||||
|
||||
## Next.js Static Exports
|
||||
|
||||
Because Tauri does not have a Node.js runtime you must set Next.js to SSG/SPA mode. This will typically result in faster page loads but also has a few caveats to be aware of, therefore we recommend to carefully read through Next.js' official docs on [Static Exports].
|
||||
|
||||
These docs also show one required configuration change we will always have to change for a Tauri + Next.js app. To do this, edit the `next.config.js` file in the project's root directory and add the following:
|
||||
|
||||
```js title=next.config.js
|
||||
/** @type {import('next').NextConfig} */
|
||||
const nextConfig = {
|
||||
output: "export",
|
||||
};
|
||||
|
||||
module.exports = nextConfig;
|
||||
```
|
||||
|
||||
This will change the behavior of the `next build` to produce an `out/` folder containing the HTML/CSS/JS assets for your application instead of writing them to a `.next/` directory specific to Next.js' runtime.
|
||||
|
||||
There are a few more possible configuration options, so make sure to read through the [Static Exports] docs as mentioned above and adapt the configuration file according to the needs of your project.
|
||||
|
||||
## Create the Rust Project
|
||||
|
||||
<TauriInit
|
||||
destDirExplination={{ __html: 'Use <code>../out</code> for this value.' }}
|
||||
devPathExplination={{
|
||||
__html: 'Use <code>http://localhost:3000</code> for this value.',
|
||||
}}
|
||||
beforeBuildCommandExplination={{
|
||||
__html:
|
||||
'Use <code>npm run build</code> for this value (make sure to adapt this to use the package manager of your choice).',
|
||||
}}
|
||||
beforeDevCommandExplination={{
|
||||
__html:
|
||||
'Use <code>npm run dev</code> for this value (make sure to adapt this to use the package manager of your choice).',
|
||||
}}
|
||||
/>
|
||||
|
||||
Now that we have scaffolded our frontend and initialized the Rust project you're almost ready to run your app. Your `tauri.conf.json` file should look something like this:
|
||||
|
||||
```json title=src-tauri/tauri.conf.json
|
||||
{
|
||||
"build": {
|
||||
"beforeBuildCommand": "npm run build",
|
||||
"beforeDevCommand": "npm run dev",
|
||||
"devPath": "http://localhost:3000",
|
||||
"distDir": "../out"
|
||||
},
|
||||
```
|
||||
|
||||
And that's it! Now you can run the following command in your terminal to start a development build of your app:
|
||||
|
||||
<Command name="dev" />
|
||||
|
||||
|
||||
|
||||
|
||||
## Invoke Commands
|
||||
|
||||
<Commands />
|
||||
|
||||
To call our newly created command we will use the [`@tauri-apps/api`] JavaScript library. It provides access to core functionality such as window manipulation, the filesystem, and more through convenient JavaScript abstractions. You can install it using your favorite JavaScript package manager:
|
||||
|
||||
<InstallTauriApi />
|
||||
|
||||
One important thing to note is that all of Tauri's JS APIs require access to browser-only APIs which means they can only be used in [Client Components]. If you don't need Server Components you can add `'use client'` at the very top of the `app/page.tsx` file, in this guide however, we will create a separate component so that we don't have to convert the whole app.
|
||||
|
||||
```tsx title=app/greet.tsx
|
||||
"use client";
|
||||
|
||||
import { useEffect } from "react";
|
||||
import { invoke } from "@tauri-apps/api/tauri";
|
||||
|
||||
export default function Greet() {
|
||||
useEffect(() => {
|
||||
invoke<string>("greet", { name: "Next.js" })
|
||||
.then(console.log)
|
||||
.catch(console.error);
|
||||
}, []);
|
||||
|
||||
// Necessary because we will have to use Greet as a component later.
|
||||
return <></>;
|
||||
}
|
||||
```
|
||||
|
||||
Now we will use this component in the default `Home` component in `app/page.tsx`. Note that it must be in the actual component tree and can't be a simple function call as long as the parent (in this case the `Home` component) is a Server Component.
|
||||
|
||||
```tsx title=app/page.tsx
|
||||
// ...
|
||||
import Greet from "./greet";
|
||||
|
||||
export default function Home() {
|
||||
return (
|
||||
<main className="flex min-h-screen flex-col items-center justify-between p-24">
|
||||
// highlight-next-line
|
||||
<Greet />
|
||||
...
|
||||
</main>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
If you want to know more about the communication between Rust and JavaScript, please read the Tauri [Inter-Process Communication][inter-process-communication] guide.
|
||||
|
||||
:::
|
||||
|
||||
<!-- TODO: Show how you can add this and screenshots of what it looks like -->
|
||||
|
||||
[next.js]: https://nextjs.org
|
||||
[cargo]: https://doc.rust-lang.org/cargo/
|
||||
[typescript]: https://www.typescriptlang.org
|
||||
[prerequisites]: ../prerequisites.md
|
||||
[`@tauri-apps/api`]: ../../../api/js/
|
||||
[inter-process-communication]: ../../../references/architecture/inter-process-communication/readme.md
|
||||
[`create-tauri-app`]: https://github.com/tauri-apps/create-tauri-app
|
||||
[static exports]: https://nextjs.org/docs/app/building-your-application/deploying/static-exports
|
||||
[client components]: https://nextjs.org/docs/getting-started/react-essentials#client-components
|
||||
@@ -1,195 +0,0 @@
|
||||
---
|
||||
title: qwik
|
||||
---
|
||||
|
||||
import TauriInit from './\_fragments/\_tauri-init.mdx'
|
||||
import Commands from './\_fragments/\_commands.mdx'
|
||||
import Intro from './\_fragments/\_intro.mdx'
|
||||
import Tabs from '@theme/Tabs'
|
||||
import TabItem from '@theme/TabItem'
|
||||
import Command from '@theme/Command'
|
||||
|
||||
# Qwik
|
||||
|
||||
This guide will walk you through creating your first Tauri app using the [Qwik] web framework.
|
||||
|
||||
<Intro />
|
||||
|
||||
Here's a preview of what we will be building:
|
||||
|
||||
|
||||
|
||||
## Create the Frontend
|
||||
|
||||
[Qwik] is primarily designed for Server-Side Rendering (SSR). To make Qwik work with Tauri we are going to use a "Static Site" adapter to create a frontend based on Static-Site Generation (SSG).
|
||||
|
||||
Qwik comes with a scaffolding utility similar to [`create-tauri-app`] that can quickly set up a new project with many customization options. For this guide, we will select the [TypeScript] template.
|
||||
|
||||
<Tabs groupId="package-manager">
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm create qwik@latest
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Yarn">
|
||||
|
||||
```shell
|
||||
yarn create qwik@latest
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="pnpm">
|
||||
|
||||
```shell
|
||||
pnpm create qwik@latest
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
1. _Project name_
|
||||
This will be the name of your JavaScript project. Corresponds to the name of the folder this utility will create but has otherwise no effect on your app. You can use any name you want here.
|
||||
|
||||
2. _App starter_
|
||||
We will select the `Basic App (QwikCity)` option for an example template.
|
||||
|
||||
3. _Install dependencies_
|
||||
Yes, if you want it to install the dependencies automatically.
|
||||
|
||||
## Qwik in SSG mode
|
||||
|
||||
<Tabs groupId="package-manager">
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm run qwik add
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Yarn">
|
||||
|
||||
```shell
|
||||
yarn create qwik add
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="pnpm">
|
||||
|
||||
```shell
|
||||
pnpm qwik add
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
Select `Static site (.html files)` adapter. Then you can build static pages via:
|
||||
|
||||
<Tabs groupId="package-manager">
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm run build
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="Yarn">
|
||||
|
||||
```shell
|
||||
yarn build
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="pnpm">
|
||||
|
||||
```shell
|
||||
pnpm build
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Create the Rust Project
|
||||
|
||||
<TauriInit
|
||||
destDirExplination={{
|
||||
__html: 'Use <code>../dist</code> for this value.',
|
||||
}}
|
||||
devPathExplination={{
|
||||
__html: 'Use <code>http://localhost:5173</code> for this value.',
|
||||
}}
|
||||
beforeDevCommandExplination={{
|
||||
__html:
|
||||
'Use <code>npm run dev</code> (make sure to adapt this to use the package manager of your choice).',
|
||||
}}
|
||||
beforeBuildCommandExplination={{
|
||||
__html:
|
||||
'Use <code>npm run build</code> (make sure to adapt this to use the package manager of your choice).',
|
||||
}}
|
||||
/>
|
||||
|
||||
And that's it! Now you can run the following command in your terminal to start a development build of your app:
|
||||
|
||||
<Command name="dev" />
|
||||
|
||||
## Invoke Commands
|
||||
|
||||
<Commands />
|
||||
|
||||
To call our newly created command we will use the [`@tauri-apps/api`] JavaScript library. It provides access to core functionality such as windows, the filesystem, and more through convenient JavaScript abstractions. You can install it using your favorite JavaScript package manager:
|
||||
|
||||
<InstallTauriApi />
|
||||
|
||||
With the library installed, we can now create a new Qwik component. We'll create it in `src/components/greet/greet.tsx`:
|
||||
|
||||
```tsx title=src/components/greet/greet.tsx
|
||||
import { $, component$, useSignal } from "@builder.io/qwik";
|
||||
import { invoke } from "@tauri-apps/api/tauri";
|
||||
|
||||
export default component$(() => {
|
||||
const greetMsg = useSignal("");
|
||||
|
||||
const greet = $(async (name: string) => {
|
||||
greetMsg.value = await invoke("greet", { name });
|
||||
});
|
||||
|
||||
return (
|
||||
<div>
|
||||
<button onClick$={() => greet("Qwik")}>Greet</button>
|
||||
<p>{greetMsg.value}</p>
|
||||
</div>
|
||||
);
|
||||
});
|
||||
```
|
||||
|
||||
You can now add this component into `src/routes/index.tsx`:
|
||||
|
||||
```tsx title=src/routes/index.tsx
|
||||
// ...
|
||||
import Greet from "~/components/greet/greet";
|
||||
|
||||
export default component$(() => {
|
||||
return (
|
||||
<>
|
||||
<Greet />
|
||||
...
|
||||
</>
|
||||
);
|
||||
});
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
If you want to know more about the communication between Rust and JavaScript, please read the Tauri [Inter-Process Communication][inter-process-communication] guide.
|
||||
|
||||
:::
|
||||
|
||||
[cargo]: https://doc.rust-lang.org/cargo/
|
||||
[inter-process-communication]: ../../../references/architecture/inter-process-communication/readme.md
|
||||
[prerequisites]: ../prerequisites.md
|
||||
[qwik]: https://qwik.builder.io
|
||||
[typescript]: https://www.typescriptlang.org
|
||||
[`@tauri-apps/api`]: ../../../api/js/
|
||||
[`create-tauri-app`]: https://github.com/tauri-apps/create-tauri-app
|
||||
[`withglobaltauri`]: ../../../api/config.md#buildconfig.withglobaltauri
|
||||
@@ -1,230 +0,0 @@
|
||||
---
|
||||
title: svelte
|
||||
---
|
||||
|
||||
import TauriInit from './\_fragments/\_tauri-init.mdx'
|
||||
import Commands from './\_fragments/\_commands.mdx'
|
||||
import Intro from './\_fragments/\_intro.mdx'
|
||||
import Tabs from '@theme/Tabs'
|
||||
import TabItem from '@theme/TabItem'
|
||||
import Command, { InstallTauriApi } from '@theme/Command'
|
||||
|
||||
# SvelteKit
|
||||
|
||||
This guide will walk you through creating your first Tauri app using the [SvelteKit] frontend framework.
|
||||
|
||||
<Intro />
|
||||
|
||||
Here's a preview of what we will be building:
|
||||
|
||||
|
||||
|
||||
## Create the Frontend
|
||||
|
||||
[SvelteKit] is a Svelte Frontend that is primarily designed for Server-Side Rendering (SSR). To make SvelteKit work with Tauri we are going to disable SSR and use [`@sveltejs/adapter-static`] to create a frontend based on Static-Site Generation (SSG).
|
||||
|
||||
SvelteKit comes with a scaffolding utility similar to [`create-tauri-app`] that can quickly set up a new project with many customization options. For this guide, we will select the [TypeScript] template, with ESLint and Prettier enabled.
|
||||
|
||||
<Tabs groupId="package-manager">
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm create svelte@latest
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="Yarn">
|
||||
|
||||
```shell
|
||||
yarn create svelte
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="pnpm">
|
||||
|
||||
```shell
|
||||
pnpm create svelte
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
1. _Project name_
|
||||
This will be the name of your JavaScript project. Corresponds to the name of the folder this utility will create but has otherwise no effect on your app. You can use any name you want here.
|
||||
|
||||
2. _App template_
|
||||
We will select the `Skeleton project` for a barebones template. If you want to play around with a more complete SvelteKit example you can select `SvelteKit demo app`.
|
||||
|
||||
3. _Type checking_
|
||||
Whether you want type checking via JSDoc or TypeScript in your project. For this guide, we assume you choose TypeScript.
|
||||
|
||||
4. _Code linting and formatting_
|
||||
Whether you want to start your project with ESLint for code linting and Prettier for code formatting. There won't be other mentions about this in this guide, but we recommend enabling these 2 options.
|
||||
|
||||
5. _Browser testing_
|
||||
SvelteKit offers built-in Playwright support for browser testing. Since Tauri APIs don't work in Playwright, we recommend not adding it. Check out our [WebDriver documentation] for alternatives using Selenium or WebdriverIO instead of Playwright.
|
||||
|
||||
## SvelteKit in SSG mode
|
||||
|
||||
<!-- TODO: section intro -->
|
||||
|
||||
First, we need to install [`@sveltejs/adapter-static`]:
|
||||
|
||||
<Tabs groupId="package-manager">
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm install --save-dev @sveltejs/adapter-static@next
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="Yarn">
|
||||
|
||||
```shell
|
||||
yarn add -D @sveltejs/adapter-static@next
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="pnpm">
|
||||
|
||||
```shell
|
||||
pnpm add -D @sveltejs/adapter-static@next
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
Then update the `adapter` import in the `svelte.config.js` file:
|
||||
|
||||
```javascript title=svelte.config.js
|
||||
// highlight-next-line
|
||||
import adapter from "@sveltejs/adapter-static"; // This was changed from adapter-auto
|
||||
import { vitePreprocess } from "@sveltejs/kit/vite";
|
||||
|
||||
/** @type {import('@sveltejs/kit').Config} */
|
||||
const config = {
|
||||
// Consult https://kit.svelte.dev/docs/integrations#preprocessors
|
||||
// for more information about preprocessors
|
||||
preprocess: vitePreprocess(),
|
||||
|
||||
kit: {
|
||||
adapter: adapter(),
|
||||
},
|
||||
};
|
||||
|
||||
export default config;
|
||||
```
|
||||
|
||||
Lastly, we need to disable SSR and enable prerendering by adding a root `+layout.ts` file (or `+layout.js` if you are not using TypeScript) with these contents:
|
||||
|
||||
```typescript title=src/routes/+layout.ts
|
||||
export const prerender = true;
|
||||
export const ssr = false;
|
||||
```
|
||||
|
||||
Note that static-adapter doesn't require you to disable SSR for the whole app but it makes it possible to use APIs that depend on the global `window` object (like Tauri's API) without [Client-side checks].
|
||||
|
||||
Furthermore, if you prefer a Single-Page Application (SPA) mode over SSG, you can change the adapter configurations and `+layout.ts` according to the [adapter docs].
|
||||
|
||||
## Create the Rust Project
|
||||
|
||||
<TauriInit
|
||||
destDirExplination={{
|
||||
__html: 'Use <code>../build</code> for this value.',
|
||||
}}
|
||||
devPathExplination={{
|
||||
__html: 'Use <code>http://localhost:5173</code> for this value.',
|
||||
}}
|
||||
beforeDevCommandExplination={{
|
||||
__html:
|
||||
'Use <code>npm run dev</code> (make sure to adapt this to use the package manager of your choice).',
|
||||
}}
|
||||
beforeBuildCommandExplination={{
|
||||
__html:
|
||||
'Use <code>npm run build</code> (make sure to adapt this to use the package manager of your choice).',
|
||||
}}
|
||||
/>
|
||||
|
||||
Now that we have scaffolded our frontend and initialized the Rust project the created `tauri.conf.json` file should look like this:
|
||||
|
||||
```json title=src-tauri/tauri.conf.json
|
||||
{
|
||||
"build": {
|
||||
// This command will execute when you run `tauri build`.
|
||||
"beforeBuildCommand": "npm run build",
|
||||
// This command will execute when you run `tauri dev`
|
||||
"beforeDevCommand": "npm run dev",
|
||||
"devPath": "http://localhost:5173",
|
||||
"distDir": "../build"
|
||||
},
|
||||
```
|
||||
|
||||
And that's it! Now you can run the following command in your terminal to start a development build of your app:
|
||||
|
||||
<Command name="dev" />
|
||||
|
||||
|
||||
|
||||
## Invoke Commands
|
||||
|
||||
<Commands />
|
||||
|
||||
To call our newly created command we will use the [`@tauri-apps/api`] JavaScript library. It provides access to core functionality such as windows, the filesystem, and more through convenient JavaScript abstractions. You can install it using your favorite JavaScript package manager:
|
||||
|
||||
<InstallTauriApi />
|
||||
|
||||
With the library installed, we can now create a new Svelte component. We'll create it in `src/lib/Greet.svelte`:
|
||||
|
||||
```html title=src/lib/Greet.svelte
|
||||
<script>
|
||||
import { invoke } from "@tauri-apps/api/tauri";
|
||||
|
||||
let name = "";
|
||||
let greetMsg = "";
|
||||
|
||||
async function greet() {
|
||||
greetMsg = await invoke("greet", { name });
|
||||
}
|
||||
</script>
|
||||
|
||||
<div>
|
||||
<input id="greet-input" placeholder="Enter a name..." bind:value="{name}" />
|
||||
<button on:click="{greet}">Greet</button>
|
||||
<p>{greetMsg}</p>
|
||||
</div>
|
||||
```
|
||||
|
||||
You can now add this component into `src/routes/+page.svelte`:
|
||||
|
||||
```html title=src/routes/+page.svelte
|
||||
<script>
|
||||
import Greet from "../lib/Greet.svelte";
|
||||
</script>
|
||||
|
||||
<h1>Welcome to SvelteKit</h1>
|
||||
<Greet />
|
||||
```
|
||||
|
||||
You can now run this with `npm run tauri dev` and see the result:
|
||||
|
||||
|
||||
|
||||
:::tip
|
||||
|
||||
If you want to know more about the communication between Rust and JavaScript, please read the Tauri [Inter-Process Communication][inter-process-communication] guide.
|
||||
|
||||
:::
|
||||
|
||||
[sveltekit]: https://kit.svelte.dev
|
||||
[`@sveltejs/adapter-static`]: https://github.com/sveltejs/kit/tree/master/packages/adapter-static
|
||||
[`create-tauri-app`]: https://github.com/tauri-apps/create-tauri-app
|
||||
[webdriver documentation]: ../../testing/webdriver/introduction.md
|
||||
[client-side checks]: https://kit.svelte.dev/faq#integrations-how-do-i-use-a-client-side-only-library-that-depends-on-document-or-window
|
||||
[adapter docs]: https://github.com/sveltejs/kit/tree/master/packages/adapter-static#spa-mode
|
||||
[typescript]: https://www.typescriptlang.org
|
||||
[`@tauri-apps/api`]: ../../../api/js/
|
||||
[inter-process-communication]: ../../../references/architecture/inter-process-communication/readme.md
|
||||
@@ -1,174 +0,0 @@
|
||||
---
|
||||
title: vite
|
||||
---
|
||||
|
||||
import TauriInit from './\_fragments/\_tauri-init.mdx'
|
||||
import Commands from './\_fragments/\_commands.mdx'
|
||||
import Intro from './\_fragments/\_intro.mdx'
|
||||
import CreateTauriAppGuide from './\_fragments/\_create-tauri-app-guide.mdx'
|
||||
import Tabs from '@theme/Tabs'
|
||||
import TabItem from '@theme/TabItem'
|
||||
import Command, { InstallTauriApi } from '@theme/Command'
|
||||
|
||||
# Vite
|
||||
|
||||
This guide will walk you through creating your first Tauri app using the frontend build tool [Vite].
|
||||
|
||||
<Intro />
|
||||
<CreateTauriAppGuide />
|
||||
|
||||
Here's a preview of what we will be building:
|
||||
|
||||
|
||||
|
||||
|
||||
## Create the Frontend
|
||||
|
||||
[Vite] is a frontend bundler and build tool meaning it provides various quality-of-life features such as _Hot Module Reloading_ (HMR) during development, but it also converts your source code into optimized HTML, CSS and JavaScript when building for production. We recommend Vite for its speed, easy configurability and [large ecosystem of plugins][awesome-vite].
|
||||
|
||||
Vite comes with a scaffolding utility similar to `create-tauri-app` that can quickly set up a new project from many pre-defined templates. You can choose from many frontend frameworks like React, Svelte or Vue. For this guide, we will select the `vanilla-ts` template to create a simple project _without_ any frontend framework.
|
||||
|
||||
<Tabs groupId="package-manager">
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm create vite@latest
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="Yarn">
|
||||
|
||||
```shell
|
||||
yarn create vite
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="pnpm">
|
||||
|
||||
```shell
|
||||
pnpm create vite
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
1. _Project name_
|
||||
This will be the name of your JavaScript project. Corresponds to the name of the folder this utility will create but has otherwise no effect on your app. You can use any name you want here.
|
||||
|
||||
2. _Select a framework_
|
||||
If you plan on using a frontend framework later, this is where you can select it. For this guide, we assume you choose `vanilla`.
|
||||
|
||||
3. _Select a variant_
|
||||
Vite offers [TypeScript] and vanilla JavaScript variants for all templates, and you can select the variant here. We **strongly** recommend TypeScript as it helps you write more secure, maintainable code faster and more efficiently. For this guide, we assume you choose `vanilla-ts`.
|
||||
|
||||
When starting the frontend via the `vite` command, Vite will look for a config file named `vite.config.ts` inside the project root. We want to customize this file to get the best compatibility with Tauri. If it is not created by the scaffolding above (such as if you're using vanilla JavaScript), you may need to create the `vite.config.ts` file in the root directory of the project.
|
||||
|
||||
Update the file with the following content:
|
||||
|
||||
```typescript title=vite.config.ts
|
||||
import { defineConfig } from "vite";
|
||||
|
||||
export default defineConfig({
|
||||
// prevent vite from obscuring rust errors
|
||||
clearScreen: false,
|
||||
// Tauri expects a fixed port, fail if that port is not available
|
||||
server: {
|
||||
strictPort: true,
|
||||
},
|
||||
// to make use of `TAURI_PLATFORM`, `TAURI_ARCH`, `TAURI_FAMILY`,
|
||||
// `TAURI_PLATFORM_VERSION`, `TAURI_PLATFORM_TYPE` and `TAURI_DEBUG`
|
||||
// env variables
|
||||
envPrefix: ["VITE_", "TAURI_"],
|
||||
build: {
|
||||
// Tauri uses Chromium on Windows and WebKit on macOS and Linux
|
||||
target: process.env.TAURI_PLATFORM == "windows" ? "chrome105" : "safari13",
|
||||
// don't minify for debug builds
|
||||
minify: !process.env.TAURI_DEBUG ? "esbuild" : false,
|
||||
// produce sourcemaps for debug builds
|
||||
sourcemap: !!process.env.TAURI_DEBUG,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
:::info
|
||||
|
||||
Note that if you are not using vanilla JavaScript, you must keep the framework-specific plugins that were already in this file.
|
||||
|
||||
:::
|
||||
|
||||
## Create the Rust Project
|
||||
|
||||
<TauriInit
|
||||
destDirExplination={{
|
||||
__html: 'Use <code>../dist</code> for this value.',
|
||||
}}
|
||||
devPathExplination={{
|
||||
__html: 'Use <code>http://localhost:5173</code> for this value.',
|
||||
}}
|
||||
beforeDevCommandExplination={{
|
||||
__html:
|
||||
'Use <code>npm run dev</code> (make sure to adapt this to use the package manager of your choice).',
|
||||
}}
|
||||
beforeBuildCommandExplination={{
|
||||
__html:
|
||||
'Use <code>npm run build</code> (make sure to adapt this to use the package manager of your choice).',
|
||||
}}
|
||||
/>
|
||||
|
||||
Now that we have scaffolded our frontend and initialized the Rust project the created `tauri.conf.json` file should look like this:
|
||||
|
||||
```json title=src-tauri/tauri.conf.json
|
||||
{
|
||||
"build": {
|
||||
// This command will execute when you run `tauri build`.
|
||||
"beforeBuildCommand": "npm run build",
|
||||
// This command will execute when you run `tauri dev`
|
||||
"beforeDevCommand": "npm run dev",
|
||||
"devPath": "http://localhost:5173",
|
||||
"distDir": "../dist"
|
||||
},
|
||||
```
|
||||
|
||||
And that's it! Now you can run the following command in your terminal to start a development build of your app:
|
||||
|
||||
<Command name="dev" />
|
||||
|
||||
|
||||
|
||||
|
||||
## Invoke Commands
|
||||
|
||||
<Commands />
|
||||
|
||||
To call our newly created command we will use the [`@tauri-apps/api`] JavaScript library. It provides access to core functionality such as windows, the filesystem, and more through convenient JavaScript abstractions. You can install it using your favorite JavaScript package manager:
|
||||
|
||||
<InstallTauriApi />
|
||||
|
||||
With the library installed, you can modify your `main.ts` file to call the Command:
|
||||
|
||||
```typescript title=src/main.ts
|
||||
import { invoke } from "@tauri-apps/api";
|
||||
|
||||
// now we can call our Command!
|
||||
// Right-click the application background and open the developer tools.
|
||||
// You will see "Hello, World!" printed in the console!
|
||||
invoke("greet", { name: "World" })
|
||||
// `invoke` returns a Promise
|
||||
.then((response) => console.log(response));
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
If you want to know more about the communication between Rust and JavaScript, please read the Tauri [Inter-Process Communication][inter-process-communication] guide.
|
||||
|
||||
:::
|
||||
|
||||
[vite]: https://vitejs.dev
|
||||
[cargo]: https://doc.rust-lang.org/cargo/
|
||||
[typescript]: https://www.typescriptlang.org
|
||||
[prerequisites]: ../prerequisites.md
|
||||
[awesome-vite]: https://github.com/vitejs/awesome-vite#plugins
|
||||
[`@tauri-apps/api`]: ../../../api/js/
|
||||
[inter-process-communication]: ../../../references/architecture/inter-process-communication/readme.md
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 116 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 116 KiB |
@@ -1,16 +0,0 @@
|
||||
---
|
||||
title: guides
|
||||
---
|
||||
|
||||
import DocCardList from '@theme/DocCardList'
|
||||
import { useCurrentSidebarCategory } from '@docusaurus/theme-common'
|
||||
|
||||
# Guides
|
||||
|
||||
Tauri is an app construction toolkit that lets you build software for all major desktop operating systems using web technologies.
|
||||
|
||||
Whether you're new to Tauri development, want to integrate Tauri into an existing project, are ready to get your app into the hands of users, or want to learn how to use a common Tauri feature, we have the help for you.
|
||||
|
||||
If you can't find what you're looking for or have a suggestion to improve our guides, reach out to our community on [Discord](https://discord.com/invite/tauri).
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items} />
|
||||
@@ -1,167 +0,0 @@
|
||||
---
|
||||
title: mocking
|
||||
---
|
||||
|
||||
# Mocking Tauri APIs
|
||||
|
||||
When writing your frontend tests, having a "fake" Tauri environment to simulate windows or intercept IPC calls is common, so-called _mocking_.
|
||||
The [`@tauri-apps/api/mocks`] module provides some helpful tools to make this easier for you:
|
||||
|
||||
:::caution
|
||||
|
||||
Remember to clear mocks after each test run to undo mock state changes between runs! See [`clearMocks()`] docs for more info.
|
||||
|
||||
:::
|
||||
|
||||
## IPC Requests
|
||||
|
||||
Most commonly, you want to intercept IPC requests; this can be helpful in a variety of situations:
|
||||
|
||||
- Ensure the correct backend calls are made
|
||||
- Simulate different results from backend functions
|
||||
|
||||
Tauri provides the mockIPC function to intercept IPC requests. You can find more about the specific API in detail [here][`mockipc()`].
|
||||
|
||||
:::note
|
||||
The following examples use [Vitest], but you can use any other frontend testing library such as jest.
|
||||
:::
|
||||
|
||||
```js
|
||||
import { beforeAll, expect, test } from "vitest";
|
||||
import { randomFillSync } from "crypto";
|
||||
|
||||
import { mockIPC } from "@tauri-apps/api/mocks";
|
||||
import { invoke } from "@tauri-apps/api/tauri";
|
||||
|
||||
// jsdom doesn't come with a WebCrypto implementation
|
||||
beforeAll(() => {
|
||||
Object.defineProperty(window, 'crypto', {
|
||||
value: {
|
||||
// @ts-ignore
|
||||
getRandomValues: (buffer) => {
|
||||
return randomFillSync(buffer);
|
||||
},
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
test("invoke simple", async () => {
|
||||
mockIPC((cmd, args) => {
|
||||
// simulated rust command called "add" that just adds two numbers
|
||||
if(cmd === "add") {
|
||||
return (args.a as number) + (args.b as number);
|
||||
}
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
Sometimes you want to track more information about an IPC call; how many times was the command invoked? Was it invoked at all?
|
||||
You can use [`mockIPC()`] with other spying and mocking tools to test this:
|
||||
|
||||
```js
|
||||
import { beforeAll, expect, test, vi } from "vitest";
|
||||
import { randomFillSync } from "crypto";
|
||||
|
||||
import { mockIPC } from "@tauri-apps/api/mocks";
|
||||
import { invoke } from "@tauri-apps/api/tauri";
|
||||
|
||||
// jsdom doesn't come with a WebCrypto implementation
|
||||
beforeAll(() => {
|
||||
Object.defineProperty(window, 'crypto', {
|
||||
value: {
|
||||
// @ts-ignore
|
||||
getRandomValues: (buffer) => {
|
||||
return randomFillSync(buffer);
|
||||
},
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
test("invoke", async () => {
|
||||
mockIPC((cmd, args) => {
|
||||
// simulated rust command called "add" that just adds two numbers
|
||||
if(cmd === "add") {
|
||||
return (args.a as number) + (args.b as number);
|
||||
}
|
||||
});
|
||||
|
||||
// we can use the spying tools provided by vitest to track the mocked function
|
||||
const spy = vi.spyOn(window, "__TAURI_IPC__");
|
||||
|
||||
expect(invoke("add", { a: 12, b: 15 })).resolves.toBe(27);
|
||||
expect(spy).toHaveBeenCalled();
|
||||
});
|
||||
```
|
||||
|
||||
To mock IPC requests to a sidecar or shell command you need to grab the ID of the event handler when `spawn()` or `execute()` is called and use this ID to emit events the backend would send back:
|
||||
|
||||
```js
|
||||
mockIPC(async (cmd, args) => {
|
||||
if (args.message.cmd === "execute") {
|
||||
const eventCallbackId = `_${args.message.onEventFn}`;
|
||||
const eventEmitter = window[eventCallbackId];
|
||||
|
||||
// 'Stdout' event can be called multiple times
|
||||
eventEmitter({
|
||||
event: "Stdout",
|
||||
payload: "some data sent from the process",
|
||||
});
|
||||
|
||||
// 'Terminated' event must be called at the end to resolve the promise
|
||||
eventEmitter({
|
||||
event: "Terminated",
|
||||
payload: {
|
||||
code: 0,
|
||||
signal: "kill",
|
||||
},
|
||||
});
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## Windows
|
||||
|
||||
Sometimes you have window-specific code (a splash screen window, for example), so you need to simulate different windows.
|
||||
You can use the [`mockWindows()`] method to create fake window labels. The first string identifies the "current" window (i.e., the window your JavaScript believes itself in), and all other strings are treated as additional windows.
|
||||
|
||||
:::note
|
||||
|
||||
[`mockWindows()`] only fakes the existence of windows but no window properties. To simulate window properties, you need to intercept the correct calls using [`mockIPC()`]
|
||||
|
||||
:::
|
||||
|
||||
```js
|
||||
import { beforeAll, expect, test } from "vitest";
|
||||
import { randomFillSync } from "crypto";
|
||||
|
||||
import { mockWindows } from "@tauri-apps/api/mocks";
|
||||
|
||||
// jsdom doesn't come with a WebCrypto implementation
|
||||
beforeAll(() => {
|
||||
Object.defineProperty(window, "crypto", {
|
||||
value: {
|
||||
// @ts-ignore
|
||||
getRandomValues: (buffer) => {
|
||||
return randomFillSync(buffer);
|
||||
},
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
test("invoke", async () => {
|
||||
mockWindows("main", "second", "third");
|
||||
|
||||
const { getCurrent, getAll } = await import("@tauri-apps/api/window");
|
||||
|
||||
expect(getCurrent()).toHaveProperty("label", "main");
|
||||
expect(getAll().map((w) => w.label)).toEqual(["main", "second", "third"]);
|
||||
});
|
||||
```
|
||||
|
||||
[`@tauri-apps/api/mocks`]: ../../api/js/mocks.md
|
||||
[`mockipc()`]: ../../api/js/mocks.md#mockipc
|
||||
[`mockwindows()`]: ../../api/js/mocks.md#mockwindows
|
||||
[`clearmocks()`]: ../../api/js/mocks.md#clearmocks
|
||||
[vitest]: https://vitest.dev
|
||||
@@ -1,101 +0,0 @@
|
||||
---
|
||||
title: ci
|
||||
---
|
||||
|
||||
# Continuous Integration
|
||||
|
||||
Utilizing Linux and some programs to create a fake display, it is possible to run [WebDriver] tests with
|
||||
[`tauri-driver`] on your CI. The following example uses the [WebdriverIO] example we [previously built together] and
|
||||
GitHub Actions.
|
||||
|
||||
This means the following assumptions:
|
||||
|
||||
1. The Tauri application is in the repository root and the binary builds when running `cargo build --release`.
|
||||
2. The [WebDriverIO] test runner is in the `webdriver/webdriverio` directory and runs when `yarn test` is used in that
|
||||
directory.
|
||||
|
||||
The following is a commented GitHub Actions workflow file at `.github/workflows/webdriver.yml`
|
||||
|
||||
```yaml
|
||||
# run this action when the repository is pushed to
|
||||
on: [push]
|
||||
|
||||
# the name of our workflow
|
||||
name: WebDriver
|
||||
|
||||
jobs:
|
||||
# a single job named test
|
||||
test:
|
||||
# the display name of the test job
|
||||
name: WebDriverIO Test Runner
|
||||
|
||||
# we want to run on the latest linux environment
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
# the steps our job runs **in order**
|
||||
steps:
|
||||
# checkout the code on the workflow runner
|
||||
- uses: actions/checkout@v2
|
||||
|
||||
# install system dependencies that Tauri needs to compile on Linux.
|
||||
# note the extra dependencies for `tauri-driver` to run which are: `webkit2gtk-driver` and `xvfb`
|
||||
- name: Tauri dependencies
|
||||
run: >-
|
||||
sudo apt-get update &&
|
||||
sudo apt-get install -y
|
||||
libgtk-3-dev
|
||||
libayatana-appindicator3-dev
|
||||
libwebkit2gtk-4.0-dev
|
||||
webkit2gtk-driver
|
||||
xvfb
|
||||
|
||||
# install the latest Rust stable
|
||||
- name: Rust stable
|
||||
uses: actions-rs/toolchain@v1
|
||||
with:
|
||||
toolchain: stable
|
||||
|
||||
# we run our rust tests before the webdriver tests to avoid testing a broken application
|
||||
- name: Cargo test
|
||||
uses: actions-rs/cargo@v1
|
||||
with:
|
||||
command: test
|
||||
|
||||
# build a release build of our application to be used during our WebdriverIO tests
|
||||
- name: Cargo build
|
||||
uses: actions-rs/cargo@v1
|
||||
with:
|
||||
command: build
|
||||
args: --release
|
||||
|
||||
# install the latest stable node version at the time of writing
|
||||
- name: Node v16
|
||||
uses: actions/setup-node@v2
|
||||
with:
|
||||
node-version: 16.x
|
||||
|
||||
# install our Node.js dependencies with Yarn
|
||||
- name: Yarn install
|
||||
run: yarn install
|
||||
working-directory: webdriver/webdriverio
|
||||
|
||||
# install the latest version of `tauri-driver`.
|
||||
# note: the tauri-driver version is independent of any other Tauri versions
|
||||
- name: Install tauri-driver
|
||||
uses: actions-rs/cargo@v1
|
||||
with:
|
||||
command: install
|
||||
args: tauri-driver
|
||||
|
||||
# run the WebdriverIO test suite.
|
||||
# we run it through `xvfb-run` (the dependency we installed earlier) to have a fake
|
||||
# display server which allows our application to run headless without any changes to the code
|
||||
- name: WebdriverIO
|
||||
run: xvfb-run yarn test
|
||||
working-directory: webdriver/webdriverio
|
||||
```
|
||||
|
||||
[webdriver]: https://www.w3.org/TR/webdriver/
|
||||
[`tauri-driver`]: https://crates.io/crates/tauri-driver
|
||||
[webdriverio]: https://webdriver.io/
|
||||
[previously built together]: ./example/webdriverio.md
|
||||
@@ -1,259 +0,0 @@
|
||||
---
|
||||
title: selenium
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs'
|
||||
import TabItem from '@theme/TabItem'
|
||||
|
||||
# Selenium
|
||||
|
||||
:::info Example Application
|
||||
This [Selenium] guide expects you to have already gone through the [example Application setup] to follow
|
||||
step-by-step. The general information may still be helpful otherwise.
|
||||
:::
|
||||
|
||||
This WebDriver testing example will use [Selenium] and a popular Node.js testing suite. You are expected to already have
|
||||
Node.js installed, along with `npm` or `yarn` although the [finished example project] uses `yarn`.
|
||||
|
||||
## Create a Directory for the Tests
|
||||
|
||||
Let's create a space to write these tests in our project. We will be using a nested directory for
|
||||
this example project as we will later also go over other frameworks, but typically you will only need to use one. Create
|
||||
the directory we will use with `mkdir -p webdriver/selenium`. The rest of this guide will assume you are inside the
|
||||
`webdriver/selenium` directory.
|
||||
|
||||
## Initializing a Selenium Project
|
||||
|
||||
We will be using a pre-existing `package.json` to bootstrap this test suite because we have already chosen specific
|
||||
dependencies to use and want to showcase a simple working solution. The bottom of this section has a collapsed
|
||||
guide on how to set it up from scratch.
|
||||
|
||||
`package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "selenium",
|
||||
"version": "1.0.0",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"test": "mocha"
|
||||
},
|
||||
"dependencies": {
|
||||
"chai": "^4.3.4",
|
||||
"mocha": "^9.0.3",
|
||||
"selenium-webdriver": "^4.0.0-beta.4"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
We have a script that runs [Mocha] as a test framework exposed as the `test` command. We also have various dependencies
|
||||
that we will be using to run the tests. [Mocha] as the testing framework, [Chai] as the assertion library, and
|
||||
[`selenium-webdriver`] which is the Node.js [Selenium] package.
|
||||
|
||||
<details><summary>Click me if you want to see how to set a project up from scratch</summary>
|
||||
|
||||
If you want to install the dependencies from scratch, just run the following command.
|
||||
|
||||
<Tabs groupId="package-manager"
|
||||
defaultValue="yarn"
|
||||
values={[
|
||||
{label: 'npm', value: 'npm'}, {label: 'Yarn', value: 'yarn'},
|
||||
]}>
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm install mocha chai selenium-webdriver
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="yarn">
|
||||
|
||||
```shell
|
||||
yarn add mocha chai selenium-webdriver
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
I suggest also adding a `"test": "mocha"` item in the `package.json` `"scripts"` key so that running Mocha can be called
|
||||
simply with
|
||||
|
||||
<Tabs groupId="package-manager"
|
||||
defaultValue="yarn"
|
||||
values={[
|
||||
{label: 'npm', value: 'npm'}, {label: 'Yarn', value: 'yarn'},
|
||||
]}>
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm test
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="yarn">
|
||||
|
||||
```shell
|
||||
yarn test
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
</details>
|
||||
|
||||
## Testing
|
||||
|
||||
Unlike the [WebdriverIO Test Suite](webdriverio#config), Selenium does not come out of the box with a Test Suite and
|
||||
leaves it up to the developer to build those out. We chose [Mocha], which is pretty neutral and not related to WebDrivers, so our script will need to do a bit of work to set up everything for us in the correct order. [Mocha] expects a
|
||||
testing file at `test/test.js` by default, so let's create that file now.
|
||||
|
||||
`test/test.js`:
|
||||
|
||||
```js
|
||||
const os = require("os");
|
||||
const path = require("path");
|
||||
const { expect } = require("chai");
|
||||
const { spawn, spawnSync } = require("child_process");
|
||||
const { Builder, By, Capabilities } = require("selenium-webdriver");
|
||||
|
||||
// create the path to the expected application binary
|
||||
const application = path.resolve(
|
||||
__dirname,
|
||||
"..",
|
||||
"..",
|
||||
"..",
|
||||
"target",
|
||||
"release",
|
||||
"hello-tauri-webdriver"
|
||||
);
|
||||
|
||||
// keep track of the webdriver instance we create
|
||||
let driver;
|
||||
|
||||
// keep track of the tauri-driver process we start
|
||||
let tauriDriver;
|
||||
|
||||
before(async function () {
|
||||
// set timeout to 2 minutes to allow the program to build if it needs to
|
||||
this.timeout(120000);
|
||||
|
||||
// ensure the program has been built
|
||||
spawnSync("cargo", ["build", "--release"]);
|
||||
|
||||
// start tauri-driver
|
||||
tauriDriver = spawn(
|
||||
path.resolve(os.homedir(), ".cargo", "bin", "tauri-driver"),
|
||||
[],
|
||||
{ stdio: [null, process.stdout, process.stderr] }
|
||||
);
|
||||
|
||||
const capabilities = new Capabilities();
|
||||
capabilities.set("tauri:options", { application });
|
||||
capabilities.setBrowserName("wry");
|
||||
|
||||
// start the webdriver client
|
||||
driver = await new Builder()
|
||||
.withCapabilities(capabilities)
|
||||
.usingServer("http://127.0.0.1:4444/")
|
||||
.build();
|
||||
});
|
||||
|
||||
after(async function () {
|
||||
// stop the webdriver session
|
||||
await driver.quit();
|
||||
|
||||
// kill the tauri-driver process
|
||||
tauriDriver.kill();
|
||||
});
|
||||
|
||||
describe("Hello Tauri", () => {
|
||||
it("should be cordial", async () => {
|
||||
const text = await driver.findElement(By.css("body > h1")).getText();
|
||||
expect(text).to.match(/^[hH]ello/);
|
||||
});
|
||||
|
||||
it("should be excited", async () => {
|
||||
const text = await driver.findElement(By.css("body > h1")).getText();
|
||||
expect(text).to.match(/!$/);
|
||||
});
|
||||
|
||||
it("should be easy on the eyes", async () => {
|
||||
// selenium returns color css values as rgb(r, g, b)
|
||||
const text = await driver
|
||||
.findElement(By.css("body"))
|
||||
.getCssValue("background-color");
|
||||
|
||||
const rgb = text.match(/^rgb\((?<r>\d+), (?<g>\d+), (?<b>\d+)\)$/).groups;
|
||||
expect(rgb).to.have.all.keys("r", "g", "b");
|
||||
|
||||
const luma = 0.2126 * rgb.r + 0.7152 * rgb.g + 0.0722 * rgb.b;
|
||||
expect(luma).to.be.lessThan(100);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
If you are familiar with JS testing frameworks, `describe`, `it`, and `expect` should look familiar. We also have
|
||||
semi-complex `before()` and `after()` callbacks to set up and teardown mocha. Lines that are not the tests themselves
|
||||
have comments explaining the setup and teardown code. If you were familiar with the Spec file from the
|
||||
[WebdriverIO example](webdriverio#spec), you notice a lot more code that isn't tests, as we have to set up a few
|
||||
more WebDriver related items.
|
||||
|
||||
## Running the Test Suite
|
||||
|
||||
Now that we are all set up with our dependencies and our test script, let's run it!
|
||||
|
||||
<Tabs groupId="package-manager"
|
||||
defaultValue="yarn"
|
||||
values={[
|
||||
{label: 'npm', value: 'npm'}, {label: 'Yarn', value: 'yarn'},
|
||||
]}>
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm test
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="yarn">
|
||||
|
||||
```shell
|
||||
yarn test
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
We should see output the following output:
|
||||
|
||||
```text
|
||||
➜ selenium git:(main) ✗ yarn test
|
||||
yarn run v1.22.11
|
||||
$ Mocha
|
||||
|
||||
|
||||
Hello Tauri
|
||||
✔ should be cordial (120ms)
|
||||
✔ should be excited
|
||||
✔ should be easy on the eyes
|
||||
|
||||
|
||||
3 passing (588ms)
|
||||
|
||||
Done in 0.93s.
|
||||
```
|
||||
|
||||
We can see that our `Hello Tauri` test suite we created with `describe` had all 3 items we created with `it` pass their
|
||||
tests!
|
||||
|
||||
With [Selenium] and some hooking up to a test suite, we just enabled e2e testing without modifying our Tauri
|
||||
application at all!
|
||||
|
||||
[selenium]: https://selenium.dev/
|
||||
[finished example project]: https://github.com/chippers/hello_tauri
|
||||
[example application setup]: ./setup.md
|
||||
[mocha]: https://mochajs.org/
|
||||
[chai]: https://www.chaijs.com/
|
||||
[`selenium-webdriver`]: https://www.npmjs.com/package/selenium-webdriver
|
||||
@@ -1,191 +0,0 @@
|
||||
---
|
||||
title: setup
|
||||
---
|
||||
|
||||
import HelloTauriWebdriver from '@site/static/img/webdriver/hello-tauri-webdriver.png'
|
||||
|
||||
# Setup Example
|
||||
|
||||
This example application solely focuses on adding WebDriver testing to an already existing project. To have a
|
||||
project to test in the following two sections, we will set up an extremely minimal Tauri application for use in
|
||||
our testing. We will not use the Tauri CLI, any frontend dependencies or build steps, and not be bundling the
|
||||
application afterward. This is to showcase exactly a minimal suite to show off adding WebDriver testing to an existing
|
||||
application.
|
||||
|
||||
If you just want to see the finished example project that utilizes what will be shown in this example guide, then you
|
||||
can see https://github.com/chippers/hello_tauri.
|
||||
|
||||
## Initializing a Cargo Project
|
||||
|
||||
We want to create a new binary Cargo project to house this example application. We can easily do this from the command
|
||||
line with `cargo new hello-tauri-webdriver --bin`, which will scaffold a minimal binary Cargo project for us. This
|
||||
directory will serve as the working directory for the rest of this guide, so make sure the commands you run are inside
|
||||
this new `hello-tauri-webdriver/` directory.
|
||||
|
||||
## Creating a Minimal Frontend
|
||||
|
||||
We will create a minimal HTML file to act as our example application's front end. We will also be using a few things
|
||||
from this frontend later during our WebDriver tests.
|
||||
|
||||
First, let's create our Tauri `distDir` that we know we will need once building the Tauri portion of the application.
|
||||
`mkdir dist` should create a new directory called `dist/` in which we will be placing the following `index.html` file.
|
||||
|
||||
`dist/index.html`:
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<title>Hello Tauri!</title>
|
||||
<style>
|
||||
body {
|
||||
/* Add a nice colorscheme */
|
||||
background-color: #222831;
|
||||
color: #ececec;
|
||||
|
||||
/* Make the body the exact size of the window */
|
||||
margin: 0;
|
||||
height: 100vh;
|
||||
width: 100vw;
|
||||
|
||||
/* Vertically and horizontally center children of the body tag */
|
||||
display: flex;
|
||||
justify-content: center;
|
||||
align-items: center;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Hello, Tauri!</h1>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
## Adding Tauri to the Cargo Project
|
||||
|
||||
Next, we will add the necessary items to turn our Cargo project into a Tauri project. First, is adding the dependencies
|
||||
to the Cargo Manifest (`Cargo.toml`) so that Cargo knows to pull in our dependencies while building.
|
||||
|
||||
`Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[package]
|
||||
name = "hello-tauri-webdriver"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
rust-version = "1.56"
|
||||
|
||||
# Needed to set up some things for Tauri at build time
|
||||
[build-dependencies]
|
||||
tauri-build = "1"
|
||||
|
||||
# The actual Tauri dependency, along with `custom-protocol` to serve the pages.
|
||||
[dependencies]
|
||||
tauri = { version = "1", features = ["custom-protocol"] }
|
||||
|
||||
# Make --release build a binary that is small (opt-level = "s") and fast (lto = true).
|
||||
# This is completely optional, but shows that testing the application as close to the
|
||||
# typical release settings is possible. Note: this will slow down compilation.
|
||||
[profile.release]
|
||||
incremental = false
|
||||
codegen-units = 1
|
||||
panic = "abort"
|
||||
opt-level = "s"
|
||||
lto = true
|
||||
```
|
||||
|
||||
We added a `[build-dependency]` as you may have noticed. To use the build dependency, we must use it from a build
|
||||
script. We will create one now at `build.rs`.
|
||||
|
||||
`build.rs`:
|
||||
|
||||
```rust
|
||||
fn main() {
|
||||
// Only watch the `dist/` directory for recompiling, preventing unnecessary
|
||||
// changes when we change files in other project subdirectories.
|
||||
println!("cargo:rerun-if-changed=dist");
|
||||
|
||||
// Run the Tauri build-time helpers
|
||||
tauri_build::build()
|
||||
}
|
||||
```
|
||||
|
||||
Our Cargo Project now knows how to pull in and build our Tauri dependencies with all that setup. Let's finish making
|
||||
this minimal example a Tauri application by setting up Tauri in the actual project code. We will be editing
|
||||
the `src/main.rs`
|
||||
file to add this Tauri functionality.
|
||||
|
||||
`src/main.rs`:
|
||||
|
||||
```rust
|
||||
fn main() {
|
||||
tauri::Builder::default()
|
||||
.run(tauri::generate_context!())
|
||||
.expect("unable to run Tauri application");
|
||||
}
|
||||
```
|
||||
|
||||
Pretty simple, right?
|
||||
|
||||
## Tauri Configuration
|
||||
|
||||
We are going to need 2 things to successfully build the application. First, we need an icon file. You can use any PNG
|
||||
for this next part and copy it into `icon.png`. Typically, this will be provided as part of the scaffolding when you use
|
||||
the Tauri CLI to create a project. To get the default Tauri icon, we can download the icon used by the Hello Tauri
|
||||
example repository with the
|
||||
command `curl -L "https://github.com/chippers/hello_tauri/raw/main/icon.png" --output icon.png`.
|
||||
|
||||
We will need a `tauri.conf.json` to set some important configuration values for Tauri. Again,
|
||||
this would typically come from the `tauri init` scaffolding command, but we will be creating our own minimal config
|
||||
here.
|
||||
|
||||
`tauri.conf.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"build": {
|
||||
"distDir": "dist"
|
||||
},
|
||||
"tauri": {
|
||||
"bundle": {
|
||||
"identifier": "studio.tauri.hello_tauri_webdriver",
|
||||
"icon": ["icon.png"]
|
||||
},
|
||||
"allowlist": {
|
||||
"all": false
|
||||
},
|
||||
"windows": [
|
||||
{
|
||||
"width": 800,
|
||||
"height": 600,
|
||||
"resizable": true,
|
||||
"fullscreen": false
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
I'll go over some of these. You can see the `dist/` directory we created earlier specified as the `distDir` property. We
|
||||
set a bundle identifier so that the built application has a unique id and set the `icon.png` as the only
|
||||
icon. We aren't using any Tauri APIs or features, so we disable them in `allowlist` by setting `"all": false`.
|
||||
The window values just set a single window to be created with some reasonable default values.
|
||||
|
||||
At this point, we have a basic Hello World application that should display a simple greeting when run.
|
||||
|
||||
## Running the Example Application
|
||||
|
||||
To make sure we did it right, let's build this application! We will run this as a `--release` application because we
|
||||
will also run our WebDriver tests with a release profile. Run `cargo run --release`, and after some compiling, we should
|
||||
see the following application pop up.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src={HelloTauriWebdriver}/>
|
||||
</div>
|
||||
|
||||
_Note: If you are modifying the application and want to use the Devtools, then run it without `--release` and "Inspect
|
||||
Element" should be available in the right-click menu._
|
||||
|
||||
We should now be ready to start testing this application with some WebDriver frameworks. This guide will go over both
|
||||
[WebdriverIO](webdriverio) and [Selenium](selenium) in that order.
|
||||
@@ -1,279 +0,0 @@
|
||||
---
|
||||
title: webdriverIO
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs'
|
||||
import TabItem from '@theme/TabItem'
|
||||
|
||||
# WebdriverIO
|
||||
|
||||
:::info Example Application
|
||||
This [WebdriverIO] guide expects you to have already gone through the [example Application setup] to follow
|
||||
step-by-step. The general information may still be helpful otherwise.
|
||||
:::
|
||||
|
||||
This WebDriver testing example will use [WebdriverIO], and its testing suite. It is expected to have Node.js already
|
||||
installed, along with `npm` or `yarn` although the [finished example project] uses `yarn`.
|
||||
|
||||
## Create a Directory for the Tests
|
||||
|
||||
Let's create a space to write these tests in our project. We will be using a nested directory for
|
||||
this example project as we will later also go over other frameworks, but typically you only need to use one. Create
|
||||
the directory we will use with `mkdir -p webdriver/webdriverio`. The rest of this guide assumes you are inside the
|
||||
`webdriver/webdriverio` directory.
|
||||
|
||||
## Initializing a WebdriverIO Project
|
||||
|
||||
We will be using a pre-existing `package.json` to bootstrap this test suite because we have already chosen specific
|
||||
[WebdriverIO] config options and want to showcase a simple working solution. The bottom of this section has a collapsed
|
||||
guide on setting it up from scratch.
|
||||
|
||||
`package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "webdriverio",
|
||||
"version": "1.0.0",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"test": "wdio run wdio.conf.js"
|
||||
},
|
||||
"dependencies": {
|
||||
"@wdio/cli": "^7.9.1"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@wdio/local-runner": "^7.9.1",
|
||||
"@wdio/mocha-framework": "^7.9.1",
|
||||
"@wdio/spec-reporter": "^7.9.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
We have a script that runs a [WebdriverIO] config as a test suite exposed as the `test` command. We also have various
|
||||
dependencies added by the `@wdio/cli` command when we first set it up. In short, these dependencies are for
|
||||
the most simple setup using a local WebDriver runner, [Mocha] as the test framework, and a simple Spec Reporter.
|
||||
|
||||
<details><summary>Click me if you want to see how to set a project up from scratch</summary>
|
||||
|
||||
The CLI is interactive, and you may choose the tools to work with yourself. Note that you will likely diverge from
|
||||
the rest of the guide, and you need to set up the differences yourself.
|
||||
|
||||
Let's add the [WebdriverIO] CLI to this npm project.
|
||||
|
||||
<Tabs groupId="package-manager"
|
||||
defaultValue="yarn"
|
||||
values={[
|
||||
{label: 'npm', value: 'npm'}, {label: 'Yarn', value: 'yarn'},
|
||||
]}>
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm install @wdio/cli
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="yarn">
|
||||
|
||||
```shell
|
||||
yarn add @wdio/cli
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
To then run the interactive config command to set up a [WebdriverIO] test suite, you can then run:
|
||||
|
||||
<Tabs groupId="package-manager"
|
||||
defaultValue="yarn"
|
||||
values={[
|
||||
{label: 'npm', value: 'npm'}, {label: 'Yarn', value: 'yarn'},
|
||||
]}>
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npx wdio config
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="yarn">
|
||||
|
||||
```shell
|
||||
yarn wdio config
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
</details>
|
||||
|
||||
## Config
|
||||
|
||||
You may have noticed that the `test` script in our `package.json` mentions a file `wdio.conf.js`. That's the [WebdriverIO]
|
||||
config file which controls most aspects of our testing suite.
|
||||
|
||||
`wdio.conf.js`:
|
||||
|
||||
```js
|
||||
const os = require("os");
|
||||
const path = require("path");
|
||||
const { spawn, spawnSync } = require("child_process");
|
||||
|
||||
// keep track of the `tauri-driver` child process
|
||||
let tauriDriver;
|
||||
|
||||
exports.config = {
|
||||
specs: ["./test/specs/**/*.js"],
|
||||
maxInstances: 1,
|
||||
capabilities: [
|
||||
{
|
||||
maxInstances: 1,
|
||||
"tauri:options": {
|
||||
application: "../../target/release/hello-tauri-webdriver",
|
||||
},
|
||||
},
|
||||
],
|
||||
reporters: ["spec"],
|
||||
framework: "mocha",
|
||||
mochaOpts: {
|
||||
ui: "bdd",
|
||||
timeout: 60000,
|
||||
},
|
||||
|
||||
// ensure the rust project is built since we expect this binary to exist for the webdriver sessions
|
||||
onPrepare: () => spawnSync("cargo", ["build", "--release"]),
|
||||
|
||||
// ensure we are running `tauri-driver` before the session starts so that we can proxy the webdriver requests
|
||||
beforeSession: () =>
|
||||
(tauriDriver = spawn(
|
||||
path.resolve(os.homedir(), ".cargo", "bin", "tauri-driver"),
|
||||
[],
|
||||
{ stdio: [null, process.stdout, process.stderr] }
|
||||
)),
|
||||
|
||||
// clean up the `tauri-driver` process we spawned at the start of the session
|
||||
afterSession: () => tauriDriver.kill(),
|
||||
};
|
||||
```
|
||||
|
||||
If you are interested in the properties on the `exports.config` object, I [suggest reading the documentation][webdriver documentation].
|
||||
For non-WDIO specific items, there are comments explaining why we are running commands in `onPrepare`, `beforeSession`,
|
||||
and `afterSession`. We also have our specs set to `"./test/specs/**/*.js"`, so let's create a spec now.
|
||||
|
||||
## Spec
|
||||
|
||||
A spec contains the code that is testing your actual application. The test runner will load these specs and automatically
|
||||
run them as it sees fit. Let's create our spec now in the directory we specified.
|
||||
|
||||
`test/specs/example.e2e.js`:
|
||||
|
||||
```js
|
||||
// calculates the luma from a hex color `#abcdef`
|
||||
function luma(hex) {
|
||||
if (hex.startsWith("#")) {
|
||||
hex = hex.substring(1);
|
||||
}
|
||||
|
||||
const rgb = parseInt(hex, 16);
|
||||
const r = (rgb >> 16) & 0xff;
|
||||
const g = (rgb >> 8) & 0xff;
|
||||
const b = (rgb >> 0) & 0xff;
|
||||
return 0.2126 * r + 0.7152 * g + 0.0722 * b;
|
||||
}
|
||||
|
||||
describe("Hello Tauri", () => {
|
||||
it("should be cordial", async () => {
|
||||
const header = await $("body > h1");
|
||||
const text = await header.getText();
|
||||
expect(text).toMatch(/^[hH]ello/);
|
||||
});
|
||||
|
||||
it("should be excited", async () => {
|
||||
const header = await $("body > h1");
|
||||
const text = await header.getText();
|
||||
expect(text).toMatch(/!$/);
|
||||
});
|
||||
|
||||
it("should be easy on the eyes", async () => {
|
||||
const body = await $("body");
|
||||
const backgroundColor = await body.getCSSProperty("background-color");
|
||||
expect(luma(backgroundColor.parsed.hex)).toBeLessThan(100);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
The `luma` function on top is just a helper function for one of our tests and is not related to the actual testing of
|
||||
the application. If you are familiar with other testing frameworks, you may notice similar functions being exposed that
|
||||
are used, such as `describe`, `it`, and `expect`. The other APIs, such as items like `$` and its exposed methods, are
|
||||
covered by the [WebdriverIO API docs].
|
||||
|
||||
## Running the Test Suite
|
||||
|
||||
Now that we are all set up with config and a spec let's run it!
|
||||
|
||||
<Tabs groupId="package-manager"
|
||||
defaultValue="yarn"
|
||||
values={[
|
||||
{label: 'npm', value: 'npm'}, {label: 'Yarn', value: 'yarn'},
|
||||
]}>
|
||||
<TabItem value="npm">
|
||||
|
||||
```shell
|
||||
npm test
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="yarn">
|
||||
|
||||
```shell
|
||||
yarn test
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
We should see output the following output:
|
||||
|
||||
```text
|
||||
➜ webdriverio git:(main) ✗ yarn test
|
||||
yarn run v1.22.11
|
||||
$ wdio run wdio.conf.js
|
||||
|
||||
Execution of 1 workers started at 2021-08-17T08:06:10.279Z
|
||||
|
||||
[0-0] RUNNING in undefined - /test/specs/example.e2e.js
|
||||
[0-0] PASSED in undefined - /test/specs/example.e2e.js
|
||||
|
||||
"spec" Reporter:
|
||||
------------------------------------------------------------------
|
||||
[wry 0.12.1 linux #0-0] Running: wry (v0.12.1) on linux
|
||||
[wry 0.12.1 linux #0-0] Session ID: 81e0107b-4d38-4eed-9b10-ee80ca47bb83
|
||||
[wry 0.12.1 linux #0-0]
|
||||
[wry 0.12.1 linux #0-0] » /test/specs/example.e2e.js
|
||||
[wry 0.12.1 linux #0-0] Hello Tauri
|
||||
[wry 0.12.1 linux #0-0] ✓ should be cordial
|
||||
[wry 0.12.1 linux #0-0] ✓ should be excited
|
||||
[wry 0.12.1 linux #0-0] ✓ should be easy on the eyes
|
||||
[wry 0.12.1 linux #0-0]
|
||||
[wry 0.12.1 linux #0-0] 3 passing (244ms)
|
||||
|
||||
|
||||
Spec Files: 1 passed, 1 total (100% completed) in 00:00:01
|
||||
|
||||
Done in 1.98s.
|
||||
```
|
||||
|
||||
We see the Spec Reporter tell us that all 3 tests from the `test/specs/example.e2e.js` file, along with the final report
|
||||
`Spec Files: 1 passed, 1 total (100% completed) in 00:00:01`.
|
||||
|
||||
Using the [WebdriverIO] test suite, we just easily enabled e2e testing for our Tauri application from just a few lines
|
||||
of configuration and a single command to run it! Even better, we didn't have to modify the application at all.
|
||||
|
||||
[webdriverio]: https://webdriver.io/
|
||||
[finished example project]: https://github.com/chippers/hello_tauri
|
||||
[example application setup]: ./setup.md
|
||||
[mocha]: https://mochajs.org/
|
||||
[webdriver documentation]: https://webdriver.io/docs/configurationfile
|
||||
[webdriverio api docs]: https://webdriver.io/docs/api
|
||||
@@ -1,54 +0,0 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: introduction
|
||||
---
|
||||
|
||||
:::caution Currently in pre-alpha
|
||||
Webdriver support for Tauri is still in pre-alpha. Tooling that is dedicated to it, such as [tauri-driver], is still in
|
||||
active development and may change as necessary over time. Additionally, only Windows and Linux are currently supported.
|
||||
:::
|
||||
|
||||
[WebDriver] is a standardized interface to interact with web documents primarily intended for automated testing.
|
||||
Tauri supports the [WebDriver] interface by leveraging the native platform's [WebDriver] server underneath a
|
||||
cross-platform wrapper [`tauri-driver`].
|
||||
|
||||
## System Dependencies
|
||||
|
||||
Install the latest [`tauri-driver`] or update an existing installation by running:
|
||||
|
||||
```shell
|
||||
cargo install tauri-driver
|
||||
```
|
||||
|
||||
Because we currently utilize the platform's native [WebDriver] server, there are some requirements for running
|
||||
[`tauri-driver`] on supported platforms. Platform support is currently limited to Linux and Windows.
|
||||
|
||||
### Linux
|
||||
|
||||
We use `WebKitWebDriver` on Linux platforms. Check if this binary exists already (command `which WebKitWebDriver`) as
|
||||
some distributions bundle it with the regular WebKit package. Other platforms may have a separate package for them, such
|
||||
as `webkit2gtk-driver` on Debian-based distributions.
|
||||
|
||||
### Windows
|
||||
|
||||
Make sure to grab the version of [Microsoft Edge Driver] that matches your Windows Edge version that the application is
|
||||
being built and tested on. This should almost always be the latest stable version on up-to-date Windows installs. If the
|
||||
two versions do not match, you may experience your WebDriver testing suite hanging while trying to connect.
|
||||
|
||||
The download contains a binary called `msedgedriver.exe`. [`tauri-driver`] looks for that binary in the `$PATH` so make
|
||||
sure it's either available on the path or use the `--native-driver` option on [`tauri-driver`]. You may want to download this automatically as part of the CI setup process to ensure the Edge, and Edge Driver versions
|
||||
stay in sync on Windows CI machines. A guide on how to do this may be added at a later date.
|
||||
|
||||
## Example Application
|
||||
|
||||
The [next section](example/setup) of the guide shows step-by-step how to create a minimal example application that
|
||||
is tested with WebDriver.
|
||||
|
||||
If you prefer to see the result of the guide and look over a finished minimal codebase that utilizes it, you
|
||||
can look at https://github.com/chippers/hello_tauri. That example also comes with a CI script to test with GitHub
|
||||
actions, but you may still be interested in the [WebDriver CI](ci) guide as it explains the concept a bit more.
|
||||
|
||||
[webdriver]: https://www.w3.org/TR/webdriver/
|
||||
[`tauri-driver`]: https://crates.io/crates/tauri-driver
|
||||
[tauri-driver]: https://crates.io/crates/tauri-driver
|
||||
[microsoft edge driver]: https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/
|
||||
@@ -1,48 +0,0 @@
|
||||
---
|
||||
title: brownfield
|
||||
---
|
||||
|
||||
# Brownfield Pattern
|
||||
|
||||
_**This is the default pattern.**_
|
||||
|
||||
This is the simplest and most straightforward pattern to use Tauri with, because it tries to be as compatible as possible with
|
||||
existing frontend projects. In short, it tries to require nothing additional to what an existing web
|
||||
frontend might use inside a browser. Not _**everything**_ that works in existing browser applications will work out-of-the-box; see the [Incompatibility section](#incompatibilities) for more details.
|
||||
|
||||
If you are unfamiliar with Brownfield software development in general, the [Brownfield Wikipedia article]
|
||||
provides a nice summary. For Tauri, the existing software is current browser support and behavior, instead of
|
||||
legacy systems.
|
||||
|
||||
## Incompatibilities
|
||||
|
||||
The first incompatibility category is simple: any browser-specific APIs will not work properly inside Tauri (even while
|
||||
using the Brownfield pattern). If the API is not widely supported across browsers, it probably won't be supported
|
||||
across all platforms while using Tauri.
|
||||
|
||||
The second incompatibility category is features that are planned for Tauri, but are currently not fully implemented. Here
|
||||
is a list of examples:
|
||||
|
||||
- [WebRTC support on Linux](https://github.com/tauri-apps/wry/issues/85)
|
||||
- [Some permissions APIs](https://github.com/tauri-apps/wry/issues/81)
|
||||
- [Download Links/Blob as URL](https://github.com/tauri-apps/wry/issues/349)
|
||||
- [Better i18n](https://github.com/tauri-apps/wry/issues/442)
|
||||
|
||||
## Configuration
|
||||
|
||||
Because the Brownfield pattern is the default pattern, it doesn't require a configuration option to be set. To explicitly set
|
||||
it, you can use the `tauri > pattern` object in the `tauri.conf.json` configuration file.
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"pattern": {
|
||||
"use": "brownfield"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
_**There are no additional configuration options for the brownfield pattern.**_
|
||||
|
||||
[brownfield wikipedia article]: https://en.wikipedia.org/wiki/Brownfield_(software_development)
|
||||
@@ -1,114 +0,0 @@
|
||||
---
|
||||
title: isolation
|
||||
---
|
||||
|
||||
# Isolation Pattern
|
||||
|
||||
The Isolation pattern is a way to intercept and modify Tauri API messages sent by the frontend before they get to Tauri Core, all with JavaScript. The secure JavaScript code that is injected by the Isolation pattern is referred to as the Isolation application.
|
||||
|
||||
## Why
|
||||
|
||||
The Isolation pattern's purpose is to provide a mechanism for developers to help protect their application from unwanted or malicious frontend calls to Tauri Core. The need for the Isolation pattern rose out of threats coming from untrusted content running on the frontend, a common case for applications with many dependencies. See [Security: Threat Models] for a list of many sources of threats that an application may see.
|
||||
|
||||
The largest threat model described above that the Isolation pattern was designed in mind was Development Threats. Not only do many frontend build-time tools consist of many dozen (or hundreds) of often deeply-nested dependencies, but a complex application may also have a large amount of (also often deeply-nested) dependencies that are bundled into the final output.
|
||||
|
||||
## When
|
||||
|
||||
Tauri highly recommends using the isolation pattern whenever it can be used. Because the Isolation application intercepts _**all**_ messages from the frontend, it can _always_ be used.
|
||||
|
||||
Tauri also strongly suggests locking down your application whenever you use external Tauri APIs. As the developer, you can utilize the secure Isolation application to try and verify IPC inputs, to make sure they are within some expected parameters. For example, you may want to check that a call to read or write a file is not trying to access a path outside your application's expected locations. Another example is making sure that a Tauri API HTTP fetch call is only setting the Origin header to what your application expects it to be.
|
||||
|
||||
That said, it intercepts _**all**_ messages from the frontend, so it will even work with always-on APIs such as [Events]. Since some events may cause your own rust code to perform actions, the same sort of validation techniques can be used with them.
|
||||
|
||||
## How
|
||||
|
||||
The Isolation pattern is all about injecting a secure application in between your frontend and Tauri Core to intercept and modify incoming IPC messages. It does this by using the sandboxing feature of `<iframe>`s to run the JavaScript securely alongside the main frontend application. Tauri enforces the Isolation pattern while loading the page, forcing all IPC calls to Tauri Core to instead be routed through the sandboxed Isolation application first. Once the message is ready to be passed to Tauri Core, it is encrypted using the browser's [SubtleCrypto] implementation and passed back to the main frontend application. Once there, it is directly passed to Tauri Core, where it is then decrypted and read like normal.
|
||||
|
||||
To ensure that someone cannot manually read the keys for a specific version of your application and use that to modify the messages after being encrypted, new keys are generated each time your application is run.
|
||||
|
||||
### Approximate Steps of an IPC Message
|
||||
|
||||
To make it easier to follow, here's an ordered list with the approximate steps an IPC message will go through when being sent to Tauri Core with the Isolation pattern:
|
||||
|
||||
1. Tauri's IPC handler receives a message
|
||||
2. IPC handler -> Isolation application
|
||||
3. `[sandbox]` Isolation application hook runs and potentially modifies the message
|
||||
4. `[sandbox]` Message is encrypted with AES-GCM using a runtime-generated key
|
||||
5. `[encrypted]` Isolation application -> IPC handler
|
||||
6. `[encrypted]` IPC handler -> Tauri Core
|
||||
|
||||
_Note: Arrows (->) indicate message passing._
|
||||
|
||||
### Performance Implications
|
||||
|
||||
Because encryption of the message does occur, there are additional overhead costs compared to the [Brownfield pattern], even if the secure Isolation application doesn't do anything. Aside from performance-sensitive applications (who likely have a carefully-maintained and small set of dependencies, to keep the performance adequate), most applications should not notice the runtime costs of encrypting/decrypting the IPC messages, as they are relatively small and AES-GCM is relatively fast. If you are unfamiliar with AES-GCM, all that is relevant in this context is that it's the only authenticated mode algorithm included in [SubtleCrypto] and that you probably already use it every day under the hood with [TLS][transport_layer_security].
|
||||
|
||||
There is also a cryptographically secure key generated once each time the Tauri application is started. It is not generally noticeable if the system already has enough entropy to immediately return enough random numbers, which is extremely common for desktop environments. If running in a headless environment to perform some [integration testing with WebDriver] then you may want to install some sort of entropy-generating service such as `haveged` if your operating system does not have one included. <sup>Linux 5.6 (March 2020) now includes entropy generation using speculative execution.</sup>
|
||||
|
||||
### Limitations
|
||||
|
||||
There are a few limitations in the Isolation pattern that arose out of platform inconsistencies. The most significant limitation is due to external files not loading correctly inside sandboxed `<iframes>` on Windows. Because of this, we have implemented a simple script inlining step during build time that takes the content of scripts relative to the Isolation application and injects them inline. This means that typical bundling or simple including of files like `<script src="index.js"></script>` still works properly, but newer mechanisms such as ES Modules will _not_ successfully load.
|
||||
|
||||
## Recommendations
|
||||
|
||||
Because the point of the Isolation application is to protect against Development Threats, we highly recommend keeping your Isolation application as simple as possible. Not only should you strive to keep dependencies minimal, but you should also consider keeping required build steps minimal. This would allow you to not need to worry about supply chain attacks against your Isolation application on top of your frontend application.
|
||||
|
||||
## Creating the Isolation Application
|
||||
|
||||
In this example, we will make a small hello-world style Isolation application and hook it up to an imaginary existing Tauri application. It will do no verification of the messages passing through it, only print the contents to the WebView console.
|
||||
|
||||
For the purposes of this example, let's imagine we are in the same directory as `tauri.conf.json`. The existing Tauri application has it's `distDir` set to `../dist`.
|
||||
|
||||
`../dist-isolation/index.html`:
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<title>Isolation Secure Script</title>
|
||||
</head>
|
||||
<body>
|
||||
<script src="index.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
`../dist-isolation/index.js`:
|
||||
|
||||
```js
|
||||
window.__TAURI_ISOLATION_HOOK__ = (payload) => {
|
||||
// let's not verify or modify anything, just print the content from the hook
|
||||
console.log("hook", payload);
|
||||
return payload;
|
||||
};
|
||||
```
|
||||
|
||||
Now, all we need to do is set up our `tauri.conf.json` [configuration](#configuration) to use the Isolation pattern, and have just bootstrapped to the Isolation pattern from the [Brownfield pattern].
|
||||
|
||||
## Configuration
|
||||
|
||||
Let's assume that our main frontend `distDir` is set to `../dist`. We also output our Isolation application to `../dist-isolation`.
|
||||
|
||||
```json
|
||||
{
|
||||
"build": {
|
||||
"distDir": "../dist"
|
||||
},
|
||||
"tauri": {
|
||||
"pattern": {
|
||||
"use": "isolation",
|
||||
"options": {
|
||||
"dir": "../dist-isolation"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[transport_layer_security]: https://en.wikipedia.org/wiki/Transport_Layer_Security
|
||||
[security: threat models]: ../../security.md#threat-models
|
||||
[events]: ../../../guides/features/events.md
|
||||
[subtlecrypto]: https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto
|
||||
[brownfield pattern]: ./brownfield.md
|
||||
[integration testing with webdriver]: ../../../guides/testing/webdriver/introduction.md
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
title: IPC
|
||||
---
|
||||
|
||||
# Inter-Process Communication
|
||||
|
||||
Inter-Process Communication (IPC) allows isolated processes to communicate securely and is key to building more complex applications.
|
||||
|
||||
Tauri uses a particular style of Inter-Process Communication called [Asynchronous Message Passing], where processes exchange _requests_ and _responses_ serialized using some simple data representation. Message Passing should sound familiar to anyone with web development experience, as this paradigm is used for client-server communication on the internet.
|
||||
|
||||
Message passing is a safer technique than shared memory or direct function access because the recipient is free to reject or discard requests as it sees fit. For example, if the Tauri Core process determines a request to be malicious, it simply discards the requests and never executes the corresponding function.
|
||||
|
||||
In the following, we explain Tauri's two IPC primitives - `Events` and `Commands` - in more detail.
|
||||
|
||||
## Events
|
||||
|
||||
Events are fire-and-forget, one-way IPC messages that are best suited to communicate lifecycle events and state changes. Unlike [Commands](#commands), Events can be emitted by both the Frontend _and_ the Tauri Core.
|
||||
|
||||
<figure>
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant F as Frontend
|
||||
participant C as Tauri Core
|
||||
|
||||
C-)F: Event
|
||||
```
|
||||
|
||||
<figcaption>Figure 1-2: An event sent from the Core to the Frontend.</figcaption>
|
||||
</figure>
|
||||
|
||||
## Commands
|
||||
|
||||
Tauri also provides a [foreign function interface]-like abstraction on top of IPC messages[^1]. The primary API, `invoke`, is similar to the browser's `fetch` API and allows the Frontend to invoke Rust functions, pass arguments, and receive data.
|
||||
|
||||
Because this mechanism uses a [JSON-RPC] like protocol under the hood to serialize requests and responses, all arguments and return data must be serializable to JSON.
|
||||
|
||||
<figure>
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant F as Frontend
|
||||
participant C as Tauri Core
|
||||
|
||||
F-)+C: IPC request
|
||||
note over C: Perform computation, write to file system, etc.
|
||||
C-)-F: Response
|
||||
```
|
||||
|
||||
<figcaption>Figure 1-3: IPC messages involved in a command invocation.</figcaption>
|
||||
</figure>
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
[^1]: Because Commands still use message passing under the hood, they do not share the same security pitfalls as real FFI interfaces do.
|
||||
|
||||
[asynchronous message passing]: https://en.wikipedia.org/wiki/Message_passing#Asynchronous_message_passing
|
||||
[json-rpc]: https://www.jsonrpc.org
|
||||
[foreign function interface]: https://en.wikipedia.org/wiki/Foreign_function_interface
|
||||
@@ -1,66 +0,0 @@
|
||||
---
|
||||
title: process model
|
||||
---
|
||||
|
||||
# Process Model
|
||||
|
||||
Tauri employs a multi-process architecture similar to Electron or many modern web browsers. This guide explores the reasons behind the design choice and why it is key to writing secure applications.
|
||||
|
||||
## Why Multiple Processes?
|
||||
|
||||
In the early days of GUI applications, it was common to use a single process to perform computation, draw the interface and react to user input. As you can probably guess, this meant that a long-running, expensive computation would leave the user interface unresponsive, or worse, a failure in one app component would bring the whole app crashing down.
|
||||
|
||||
It became clear that a more resilient architecture was needed, and applications began running different components in different processes. This makes much better use of modern multi-core CPUs and creates far safer applications. A crash in one component doesn't affect the whole system anymore, as components are isolated on different processes. If a process gets into an invalid state, we can easily restart it.
|
||||
|
||||
We can also limit the blast radius of potential exploits by handing out only the minimum amount of permissions to each process, just enough so they can get their job done. This pattern is known as the [Principle of Least Privilege], and you see it in the real world all the time. If you have a gardener coming over to trim your hedge, you give them the key to your garden. You would **not** give them the keys to your house; why would they need access to that? The same concept applies to computer programs. The less access we give them, the less harm they can do if they get compromised.
|
||||
|
||||
## The Core Process
|
||||
|
||||
Each Tauri application has a core process, which acts as the application's entry point and which is the only component with full access to the operating system.
|
||||
|
||||
The Core's primary responsibility is to use that access to create and orchestrate application windows, system-tray menus, or notifications. Tauri implements the necessary cross-platform abstractions to make this easy. It also routes all [Inter-Process Communication] through the Core process, allowing you to intercept, filter, and manipulate IPC messages in one central place.
|
||||
|
||||
The Core process should also be responsible for managing global state, such as settings or database connections. This allows you to easily synchronize state between windows and protect your business-sensitive data from prying eyes in the Frontend.
|
||||
|
||||
We chose Rust to implement Tauri because of its concept of [Ownership]
|
||||
guarantees memory safety while retaining excellent performance.
|
||||
|
||||
<figure>
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
C{Core}
|
||||
W1[WebView]
|
||||
W2[WebView]
|
||||
W3[WebView]
|
||||
|
||||
C <-->|Events & Commands| W1
|
||||
C <-->|Events & Commands| W2
|
||||
C <-->|Events & Commands| W3
|
||||
```
|
||||
|
||||
<figcaption>Figure 1-1: Simplified representation of the Tauri process model. A single Core process manages one or more WebView processes.</figcaption>
|
||||
</figure>
|
||||
|
||||
## The WebView Process
|
||||
|
||||
The Core process doesn't render the actual user interface (UI) itself; it spins up WebView processes that leverage WebView libraries provided by the operating system. A WebView is a browser-like environment that executes your HTML, CSS, and JavaScript.
|
||||
|
||||
This means that most of your techniques and tools used in traditional web development can be used to create Tauri applications. For example, many Tauri examples are written using the [Svelte] frontend framework and the [Vite] bundler.
|
||||
|
||||
Security best practices apply as well; for example, you must always sanitize user input, never handle secrets in the Frontend, and ideally defer as much business logic as possible to the Core process to keep your attack surface small.
|
||||
|
||||
Unlike other similar solutions, the WebView libraries are **not** included in your final executable but dynamically linked at runtime[^1]. This makes your application _significantly_ smaller, but it also means that you need to keep platform differences in mind, just like traditional web development.
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
[^1]: Currently, Tauri uses [Microsoft Edge WebView2] on Windows, [WKWebView] on
|
||||
macOS and [webkitgtk] on Linux.
|
||||
|
||||
[principle of least privilege]: https://en.wikipedia.org/wiki/Principle_of_least_privilege
|
||||
[inter-process communication]: ./inter-process-communication/readme.md
|
||||
[ownership]: https://doc.rust-lang.org/book/ch04-01-what-is-ownership.html
|
||||
[microsoft edge webview2]: https://docs.microsoft.com/en-us/microsoft-edge/webview2/
|
||||
[wkwebview]: https://developer.apple.com/documentation/webkit/wkwebview
|
||||
[webkitgtk]: https://webkitgtk.org
|
||||
[svelte]: https://svelte.dev/
|
||||
[vite]: https://vitejs.dev/
|
||||
@@ -1,161 +0,0 @@
|
||||
---
|
||||
title: tauri architecture
|
||||
---
|
||||
|
||||
import { colors } from '@theme/Mermaid'
|
||||
import { Mermaid } from 'mdx-mermaid/Mermaid';
|
||||
|
||||
# Tauri Architecture
|
||||
|
||||
## Introduction
|
||||
|
||||
Tauri is a polyglot and generic toolkit that is very composable and allows engineers to make a wide variety of applications. It is used for building applications for desktop computers using a combination of Rust tools and HTML rendered in a Webview. Apps built with Tauri can ship with any number of pieces of an optional JS API and Rust API so that webviews can control the system via message passing. Developers can extend the default API with their own functionality and bridge the Webview and Rust-based backend easily.
|
||||
|
||||
Tauri apps can have [custom menus](../../guides/features/menu.md) and [tray-type interfaces](../../guides/features/system-tray.md). They can be [updated](../../guides/distribution/updater.md) and are managed by the user's operating system as expected. They are [very small](../benchmarks.md) because they use the OS's webview. They do not ship a runtime since the final binary is compiled from Rust. This makes the [reversing of Tauri apps not a trivial task](./security.md).
|
||||
|
||||
### What Tauri is Not
|
||||
|
||||
Tauri is not a lightweight kernel wrapper. Instead, it directly uses [WRY](#wry) and [TAO](#tao) to do the heavy lifting in making system calls to the OS.
|
||||
|
||||
Tauri is not a VM or virtualized environment. Instead, it is an application toolkit that allows making Webview OS applications.
|
||||
|
||||
## Core Ecosystem
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<Mermaid chart={`graph TB;
|
||||
subgraph Core
|
||||
direction LR
|
||||
subgraph tauri
|
||||
direction TB
|
||||
tauri-runtime
|
||||
tauri-macros
|
||||
tauri-utils
|
||||
end
|
||||
%% This section should be organized from top to bottom
|
||||
tauri-build
|
||||
tauri-codegen
|
||||
tauri-runtime-wry
|
||||
end
|
||||
tauri-runtime-wry -.-> WRY
|
||||
subgraph Upstream
|
||||
direction LR
|
||||
WRY
|
||||
TAO
|
||||
WRY -.-> TAO
|
||||
end
|
||||
style Core fill:${colors.blue.light},stroke:${colors.blue.dark},stroke-width:4px
|
||||
style Upstream fill:${colors.blue.light},stroke:${colors.blue.dark},stroke-width:4px
|
||||
style tauri fill:${colors.orange.light},stroke:${colors.orange.dark},stroke-width:4px
|
||||
`} />
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### [tauri](https://github.com/tauri-apps/tauri/tree/dev/core/tauri)
|
||||
|
||||
This is the major crate that holds everything together. It brings the runtimes, macros, utilities and API into one final product. It reads the [`tauri.conf.json`](../../api/config.md) file at compile time to bring in features and undertake the actual configuration of the app (and even the `Cargo.toml` file in the project's folder). It handles script injection (for polyfills / prototype revision) at runtime, hosts the API for systems interaction, and even manages the updating process.
|
||||
|
||||
### [tauri-runtime](https://github.com/tauri-apps/tauri/tree/dev/core/tauri-runtime)
|
||||
|
||||
The glue layer between Tauri itself and lower-level webview libraries.
|
||||
|
||||
### [tauri-macros](https://github.com/tauri-apps/tauri/tree/dev/core/tauri-macros)
|
||||
|
||||
Creates macros for the context, handler, and commands by leveraging the [`tauri-codegen`](https://github.com/tauri-apps/tauri/tree/dev/core/tauri-codegen) crate.
|
||||
|
||||
### [tauri-utils](https://github.com/tauri-apps/tauri/tree/dev/core/tauri-utils)
|
||||
|
||||
Common code that is reused in many places and offers useful utilities like parsing configuration files, detecting platform triples, injecting the CSP, and managing assets.
|
||||
|
||||
### [tauri-build](https://github.com/tauri-apps/tauri/tree/dev/core/tauri-build)
|
||||
|
||||
Applies the macros at build-time to rig some special features needed by `cargo`.
|
||||
|
||||
### [tauri-codegen](https://github.com/tauri-apps/tauri/tree/dev/core/tauri-codegen)
|
||||
|
||||
Embeds, hashes, and compresses assets, including icons for the app as well as the system tray. Parses [`tauri.conf.json`](../../api/config.md) at compile time and generates the Config struct.
|
||||
|
||||
### [tauri-runtime-wry](https://github.com/tauri-apps/tauri/tree/dev/core/tauri-runtime-wry)
|
||||
|
||||
This crate opens up direct systems-level interactions specifically for WRY, such as printing, monitor detection, and other windowing-related tasks.
|
||||
|
||||
## Tauri Tooling
|
||||
|
||||
### [API](https://github.com/tauri-apps/tauri/tree/dev/tooling/api) (JavaScript / TypeScript)
|
||||
|
||||
A typescript library that creates `cjs` and `esm` JavaScript endpoints for you to import into your frontend framework so that the Webview can call and listen to backend activity. Also ships in pure typescript, because for some frameworks this is more optimal. It uses the message passing of webviews to their hosts.
|
||||
|
||||
### [Bundler](https://github.com/tauri-apps/tauri/tree/dev/tooling/bundler) (Rust / Shell)
|
||||
|
||||
A library that builds a Tauri app for the platform it detects or is told. Currently supports macOS, Windows and Linux - but in the near future will support mobile platforms as well. May be used outside of Tauri projects.
|
||||
|
||||
### [cli.rs](https://github.com/tauri-apps/tauri/tree/dev/tooling/cli) (Rust)
|
||||
|
||||
This Rust executable provides the full interface to all of the required activities for which the CLI is required. It runs on macOS, Windows, and Linux.
|
||||
|
||||
### [cli.js](https://github.com/tauri-apps/tauri/tree/dev/tooling/cli/node) (JavaScript)
|
||||
|
||||
Wrapper around [`cli.rs`](https://github.com/tauri-apps/tauri/blob/dev/tooling/cli) using [`napi-rs`](https://github.com/napi-rs/napi-rs) to produce npm packages for each platform.
|
||||
|
||||
### [create-tauri-app](https://github.com/tauri-apps/create-tauri-app) (JavaScript)
|
||||
|
||||
A toolkit that will enable engineering teams to rapidly scaffold out a new `tauri-apps` project using the frontend framework of their choice (as long as it has been configured).
|
||||
|
||||
## Upstream Crates
|
||||
|
||||
The Tauri-Apps organisation maintains two "upstream" crates from Tauri, namely TAO for creating and managing application windows, and WRY for interfacing with the Webview that lives within the window.
|
||||
|
||||
### [TAO](https://github.com/tauri-apps/tao)
|
||||
|
||||
Cross-platform application window creation library in Rust that supports all major platforms like Windows, macOS, Linux, iOS and Android. Written in Rust, it is a fork of [winit](https://github.com/rust-windowing/winit) that we have extended for our own needs - like menu bar and system tray.
|
||||
|
||||
### [WRY](https://github.com/tauri-apps/wry)
|
||||
|
||||
WRY is a cross-platform WebView rendering library in Rust that supports all major desktop platforms like Windows, macOS, and Linux.
|
||||
Tauri uses WRY as the abstract layer responsible to determine which webview is used (and how interactions are made).
|
||||
|
||||
## Additional Tooling
|
||||
|
||||
### [tauri-action](https://github.com/tauri-apps/tauri-action)
|
||||
|
||||
GitHub workflow that builds Tauri binaries for all platforms. Even allows creating a (very basic) Tauri app even if Tauri is not set up.
|
||||
|
||||
### [tauri-vscode](https://github.com/tauri-apps/tauri-vscode)
|
||||
|
||||
This project enhances the Visual Studio Code interface with several nice-to-have features.
|
||||
|
||||
### [vue-cli-plugin-tauri](https://github.com/tauri-apps/vue-cli-plugin-tauri)
|
||||
|
||||
Allows you to very quickly install Tauri in a vue-cli project.
|
||||
|
||||
## Plugins
|
||||
|
||||
[Tauri Plugin Guide](../../guides/features/plugin.md)
|
||||
|
||||
Generally speaking, plugins are authored by third parties (even though there may be official, supported plugins). A plugin generally does 3 things:
|
||||
|
||||
1. Enables Rust code to do "something".
|
||||
2. Provides interface glue to make it easy to integrate into an app.
|
||||
3. Provides a JavaScript API for interfacing with the Rust code.
|
||||
|
||||
Here are some examples of Tauri Plugins:
|
||||
|
||||
- [tauri-plugin-sql](https://github.com/tauri-apps/tauri-plugin-sql)
|
||||
- [tauri-plugin-stronghold](https://github.com/tauri-apps/tauri-plugin-stronghold)
|
||||
- [tauri-plugin-authenticator](https://github.com/tauri-apps/tauri-plugin-authenticator)
|
||||
|
||||
## License
|
||||
|
||||
Tauri itself is licensed under MIT or Apache-2.0. If you repackage it and modify any source code, it is your responsibility to verify that you are complying with all upstream licenses. Tauri is provided AS-IS with no explicit claim for suitability for any purpose.
|
||||
|
||||
Here you may peruse our [Software Bill of Materials](https://app.fossa.com/projects/git%2Bgithub.com%2Ftauri-apps%2Ftauri).
|
||||
|
||||
## Next Steps
|
||||
|
||||
[Your First Tauri App](../../guides/getting-started/setup/README.mdx)
|
||||
|
||||
[Development Cycle](../../guides/development/development-cycle.md)
|
||||
|
||||
[Publishing](../../guides/distribution/publishing.md)
|
||||
|
||||
[Updating](../../guides/distribution/updater.md)
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
id: about-recipes
|
||||
title: 'A word on recipes'
|
||||
sidebar_label: A word on recipes
|
||||
draft: true
|
||||
---
|
||||
|
||||
Tauri recipes are descriptions of use cases that are entirely configurable within the `src-tauri/tauri.conf.json` file. These are not the limits of what Tauri can do, and there are probably more out there. If you discover one, please get in touch and help us update this collection!
|
||||
|
||||
If you haven't read about the general design of Tauri, then it would make the most sense for you to visit the [Quick Start] guide and become familiar with the basic architecture and terminology used in these recipes.
|
||||
|
||||
[quick start]: ../../../guides/getting-started/setup/README.mdx
|
||||
@@ -1,181 +0,0 @@
|
||||
---
|
||||
title: Bridge
|
||||
draft: true
|
||||
---
|
||||
|
||||
import Rater from '@theme/Rater'
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl'
|
||||
|
||||
<div className="row">
|
||||
<div className="col col--4">
|
||||
<table>
|
||||
<tr>
|
||||
<td>Ease of Use</td>
|
||||
<td><Rater value="3"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Extensibility</td>
|
||||
<td><Rater value="5"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Performance</td>
|
||||
<td><Rater value="4"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Security</td>
|
||||
<td><Rater value="4"/></td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
<div className="col col--4 pattern-logo">
|
||||
<img src={useBaseUrl('img/recipes/Bridge.svg')} alt="Bridge" />
|
||||
</div>
|
||||
<div className="col col--4">
|
||||
Pros:
|
||||
<ul>
|
||||
<li>Highly configurable</li>
|
||||
<li>No Rust skills required</li>
|
||||
</ul>
|
||||
Cons:
|
||||
<ul>
|
||||
<li>Some WebAPIs unavailable</li>
|
||||
<li>Challenge to implement</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
## Description
|
||||
|
||||
The Bridge recipe is a secure pattern where messages are passed between brokers via an implicit bridge using the API. It isolates functionality to the specific scope and passes messages instead of functionality.
|
||||
|
||||
## Diagram
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
H==>F
|
||||
subgraph WEBVIEW
|
||||
F-.-E
|
||||
end
|
||||
D-->E
|
||||
E-->D
|
||||
B-->D
|
||||
D-->B
|
||||
subgraph RUST
|
||||
A==>H
|
||||
A-->B
|
||||
B-.-C
|
||||
B-.-G
|
||||
end
|
||||
A[Binary]
|
||||
B{Rust Broker}
|
||||
C[Subprocess 2]
|
||||
G[Subprocess 1]
|
||||
D(( API BRIDGE ))
|
||||
E{JS Broker}
|
||||
F[Window]
|
||||
H{Bootstrap}
|
||||
class D apibridge
|
||||
class RUST rust
|
||||
class WEBVIEW webview
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Here's what you need to add to your tauri.conf.json file:
|
||||
|
||||
```json
|
||||
{
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"all": false,
|
||||
"clipboard": {
|
||||
"all": false,
|
||||
"readText": false,
|
||||
"writeText": false
|
||||
},
|
||||
"dialog": {
|
||||
"all": false,
|
||||
"ask": false,
|
||||
"confirm": false,
|
||||
"message": false,
|
||||
"open": false,
|
||||
"save": false
|
||||
},
|
||||
"fs": {
|
||||
"all": false,
|
||||
"copyFile": false,
|
||||
"createDir": false,
|
||||
"readDir": false,
|
||||
"readFile": false,
|
||||
"removeDir": false,
|
||||
"removeFile": false,
|
||||
"renameFile": false,
|
||||
"scope": [],
|
||||
"writeFile": false
|
||||
},
|
||||
"globalShortcut": {
|
||||
"all": false
|
||||
},
|
||||
"http": {
|
||||
"all": false,
|
||||
"request": false,
|
||||
"scope": []
|
||||
},
|
||||
"notification": {
|
||||
"all": false
|
||||
},
|
||||
"os": {
|
||||
"all": false
|
||||
},
|
||||
"path": {
|
||||
"all": false
|
||||
},
|
||||
"process": {
|
||||
"all": false,
|
||||
"exit": false,
|
||||
"relaunch": false,
|
||||
"relaunchDangerousAllowSymlinkMacos": false
|
||||
},
|
||||
"protocol": {
|
||||
"all": false,
|
||||
"asset": false,
|
||||
"assetScope": []
|
||||
},
|
||||
"shell": {
|
||||
"all": false,
|
||||
"execute": false,
|
||||
"open": false,
|
||||
"scope": [],
|
||||
"sidecar": false
|
||||
},
|
||||
"window": {
|
||||
"all": false,
|
||||
"center": false,
|
||||
"close": false,
|
||||
"create": false,
|
||||
"hide": false,
|
||||
"maximize": false,
|
||||
"minimize": false,
|
||||
"print": false,
|
||||
"requestUserAttention": false,
|
||||
"setAlwaysOnTop": false,
|
||||
"setDecorations": false,
|
||||
"setFocus": false,
|
||||
"setFullscreen": false,
|
||||
"setIcon": false,
|
||||
"setMaxSize": false,
|
||||
"setMinSize": false,
|
||||
"setPosition": false,
|
||||
"setResizable": false,
|
||||
"setSize": false,
|
||||
"setSkipTaskbar": false,
|
||||
"setTitle": false,
|
||||
"show": false,
|
||||
"startDragging": false,
|
||||
"unmaximize": false,
|
||||
"unminimize": false
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,102 +0,0 @@
|
||||
---
|
||||
title: Cloudbridge
|
||||
draft: true
|
||||
---
|
||||
|
||||
import Rater from '@theme/Rater'
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl'
|
||||
|
||||
<div className="row">
|
||||
<div className="col col--4">
|
||||
<table>
|
||||
<tr>
|
||||
<td>Ease of Use</td>
|
||||
<td><Rater value="1"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Extensibility</td>
|
||||
<td><Rater value="5"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Performance</td>
|
||||
<td><Rater value="3"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Security</td>
|
||||
<td><Rater value="2"/></td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
<div className="col col--4 pattern-logo">
|
||||
<img src={useBaseUrl('img/recipes/Cloudbridge.svg')} alt="Cloudbridge" />
|
||||
</div>
|
||||
<div className="col col--4">
|
||||
Pros:
|
||||
<ul>
|
||||
<li>All available features</li>
|
||||
<li>No Rust skills required</li>
|
||||
</ul>
|
||||
Cons:
|
||||
<ul>
|
||||
<li>Largest bundle size</li>
|
||||
<li>Hard to separate concerns</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
## Description
|
||||
|
||||
The Cloudbridge recipe combines the flexibility of a localhost and the security of the bridge. With so many features, it can be easy to get lost.
|
||||
|
||||
## Diagram
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
H==>F2
|
||||
H==>D2
|
||||
D2-->F2
|
||||
F2-->D2
|
||||
B-->D
|
||||
D-->B
|
||||
E2-->D
|
||||
D-->E2
|
||||
subgraph WEBVIEW
|
||||
F2
|
||||
E2
|
||||
end
|
||||
subgraph SERVER
|
||||
D2
|
||||
E-->D2
|
||||
end
|
||||
subgraph RUST
|
||||
A==>H
|
||||
A-->B
|
||||
B-.-C
|
||||
end
|
||||
A[Binary]
|
||||
B{Rust Broker}
|
||||
C[Subprocess]
|
||||
D(( API BRIDGE ))
|
||||
E{JS Broker}
|
||||
D2(( localhost ))
|
||||
E[bundled resources]
|
||||
E2{JS Broker}
|
||||
F2[Window]
|
||||
H{Bootstrap}
|
||||
class D apibridge
|
||||
class RUST rust
|
||||
class WEBVIEW webview
|
||||
class SERVER server
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Here's what you need to add to your tauri.conf.json file:
|
||||
|
||||
```json
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"all": true // enable entire API
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,90 +0,0 @@
|
||||
---
|
||||
title: Cloudish
|
||||
draft: true
|
||||
---
|
||||
|
||||
import Rater from '@theme/Rater'
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl'
|
||||
|
||||
<div className="row">
|
||||
<div className="col col--4">
|
||||
<table>
|
||||
<tr>
|
||||
<td>Ease of Use</td>
|
||||
<td><Rater value="5"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Extensibility</td>
|
||||
<td><Rater value="3"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Performance</td>
|
||||
<td><Rater value="3"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Security</td>
|
||||
<td><Rater value="2"/></td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
<div className="col col--4 pattern-logo">
|
||||
<img src={useBaseUrl('img/recipes/Cloudish.svg')} alt="Cloudish" />
|
||||
</div>
|
||||
<div className="col col--4">
|
||||
Pros:
|
||||
<ul>
|
||||
<li>Similar to a SPA web-app</li>
|
||||
<li>No Rust skills required</li>
|
||||
</ul>
|
||||
Cons:
|
||||
<ul>
|
||||
<li>No access to Rust API</li>
|
||||
<li>Uses a localhost server</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
## Description
|
||||
|
||||
The Cloudish recipe is a pattern for maximum flexibility and app performance. It uses a localhost server, which means that your app will technically be available to other processes, like browsers and potentially other devices on the network. All of your assets are baked into the binary but served as if they were distinct files.
|
||||
|
||||
## Diagram
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
H==>F
|
||||
H==>D
|
||||
D-->F
|
||||
F-->D
|
||||
subgraph RUST
|
||||
A==>H
|
||||
end
|
||||
subgraph WEBVIEW
|
||||
F
|
||||
end
|
||||
subgraph SERVER
|
||||
D
|
||||
E-->D
|
||||
end
|
||||
A[Binary]
|
||||
D(( localhost ))
|
||||
E[bundled resources]
|
||||
F[Window]
|
||||
H{Bootstrap}
|
||||
class RUST rust
|
||||
class WEBVIEW webview
|
||||
class SERVER server
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Here's what you need to add to your tauri.conf.json file:
|
||||
|
||||
```json
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"all": false // disable entire API
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
@@ -1,91 +0,0 @@
|
||||
---
|
||||
title: GLUI
|
||||
draft: true
|
||||
---
|
||||
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl'
|
||||
|
||||
:::warning
|
||||
This pattern is not available for now.
|
||||
:::
|
||||
|
||||
import Rater from '@theme/Rater'
|
||||
|
||||
<div className="row">
|
||||
<div className="col col--4">
|
||||
<table>
|
||||
<tr>
|
||||
<td>Ease of Use</td>
|
||||
<td><Rater value="0"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Extensibility</td>
|
||||
<td><Rater value="0"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Performance</td>
|
||||
<td><Rater value="5"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Security</td>
|
||||
<td><Rater value="0"/></td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
<div className="col col--4 pattern-logo">
|
||||
<img src={useBaseUrl('img/recipes/GLUI.svg')} alt="GLUI" />
|
||||
</div>
|
||||
<div className="col col--4">
|
||||
Pros:
|
||||
<ul>
|
||||
<li>Framebuffer FTW</li>
|
||||
<li>Window events rigged</li>
|
||||
</ul>
|
||||
Cons:
|
||||
<ul>
|
||||
<li>Broken on your machine</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
## Description
|
||||
|
||||
The GLUI is a research pattern that we will use internally to test approaches using a GLUTIN window. We’re not sure yet if it will make the final cut as a bona fide alternative to WebView, although early tests with transparent and multiwindow are exciting.
|
||||
|
||||
## Diagram
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A==>H
|
||||
H==>G
|
||||
A-->D
|
||||
D-->G
|
||||
subgraph GLUTIN
|
||||
G
|
||||
end
|
||||
subgraph RUST
|
||||
A
|
||||
end
|
||||
A[Binary]
|
||||
D(Framebuffer)
|
||||
G[GL Window]
|
||||
H{Bootstrap}
|
||||
class GLUTIN other
|
||||
class RUST rust
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Here's what you need to add to your tauri.conf.json file:
|
||||
|
||||
```json
|
||||
"tauri": {
|
||||
"allowlist": { // all API endpoints are default false
|
||||
"all": false, // disable the api
|
||||
},
|
||||
"window": { // not yet normative
|
||||
"glutin": true,
|
||||
"webview": false
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,80 +0,0 @@
|
||||
---
|
||||
title: Hermit
|
||||
draft: true
|
||||
---
|
||||
|
||||
import Rater from '@theme/Rater'
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl'
|
||||
|
||||
<div className="row">
|
||||
<div className="col col--4">
|
||||
<table>
|
||||
<tr>
|
||||
<td>Ease of Use</td>
|
||||
<td><Rater value="5"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Extensibility</td>
|
||||
<td><Rater value="0"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Performance</td>
|
||||
<td><Rater value="5"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Security</td>
|
||||
<td><Rater value="5"/></td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
<div className="col col--4 pattern-logo">
|
||||
<img src={useBaseUrl('img/recipes/Hermit.svg')} alt="Hermit" />
|
||||
</div>
|
||||
<div className="col col--4">
|
||||
Pros:
|
||||
<ul>
|
||||
<li>Quick to make</li>
|
||||
<li>Smallest size</li>
|
||||
</ul>
|
||||
Cons:
|
||||
<ul>
|
||||
<li>No remote resources</li>
|
||||
<li>No access to API</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
## Description
|
||||
|
||||
The Hermit recipe is a pattern for ultimate application isolation where all logic is self-contained in the Window and the binary exists merely to bootstrap the Window. There is no communication back to Rust from the Window, there is no localhost server, and the Window has no access to any remote resources. The Hermit is great for interactive Kiosk Mode and standalone HTML-based games.
|
||||
|
||||
## Diagram
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A==>H
|
||||
H==>F
|
||||
subgraph WEBVIEW
|
||||
F
|
||||
end
|
||||
subgraph RUST
|
||||
A
|
||||
end
|
||||
A[fa:fa-cog Binary ]
|
||||
F[fa:fa-window-maximize Window]
|
||||
H{Bootstrap}
|
||||
class RUST rust
|
||||
class WEBVIEW webview
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Here's what you need to add to your tauri.conf.json file:
|
||||
|
||||
```json
|
||||
"tauri": {
|
||||
"allowlist": {
|
||||
"all": false, // disable and tree-shake all api functions
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,82 +0,0 @@
|
||||
---
|
||||
title: Lockdown
|
||||
draft: true
|
||||
---
|
||||
|
||||
import Rater from '@theme/Rater'
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl'
|
||||
|
||||
<div className="row">
|
||||
<div className="col col--4">
|
||||
<table>
|
||||
<tr>
|
||||
<td>Ease of Use</td>
|
||||
<td><Rater value="2"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Extensibility</td>
|
||||
<td><Rater value="4"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Performance</td>
|
||||
<td><Rater value="5"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Security</td>
|
||||
<td><Rater value="5" /></td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
<div className="col col--4 pattern-logo">
|
||||
<img src={useBaseUrl('img/recipes/Lockdown.svg')} alt="Lockdown" />
|
||||
</div>
|
||||
<div className="col col--4">
|
||||
Pros:
|
||||
<ul>
|
||||
<li>Highest security rating</li>
|
||||
<li>Elegant and powerful</li>
|
||||
</ul>
|
||||
Cons:
|
||||
<ul>
|
||||
<li>Rust skills required</li>
|
||||
<li>No remote resources</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
## Description
|
||||
|
||||
The Lockdown recipe is a minimal usage of the [Bridge pattern](./bridge), which only allows interaction between Rust and the Window via expiring JS Promise Closures that are injected into the Window by Rust and nulled as part of the callback.
|
||||
|
||||
## Diagram
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
H==>F
|
||||
G-.->B
|
||||
B-->G
|
||||
subgraph WEBVIEW
|
||||
G-->F
|
||||
end
|
||||
subgraph RUST
|
||||
A-->B
|
||||
A==>H
|
||||
end
|
||||
A[Binary]
|
||||
B[API:Event]
|
||||
F[Window]
|
||||
G((Promise Closure))
|
||||
H{Bootstrap}
|
||||
class RUST rust
|
||||
class WEBVIEW webview
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Here's what you need to add to your tauri.conf.json file:
|
||||
|
||||
```json
|
||||
"tauri": {
|
||||
"allowlist": {} // all API endpoints are default false
|
||||
}
|
||||
```
|
||||
@@ -1,91 +0,0 @@
|
||||
---
|
||||
title: Multiwin
|
||||
draft: true
|
||||
---
|
||||
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl'
|
||||
import Rater from '@theme/Rater'
|
||||
|
||||
<div className="row">
|
||||
<div className="col col--4">
|
||||
<table>
|
||||
<tr>
|
||||
<td>Ease of Use</td>
|
||||
<td><Rater value="4"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Extensibility</td>
|
||||
<td><Rater value="4"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Performance</td>
|
||||
<td><Rater value="3"/></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Security</td>
|
||||
<td><Rater value="5"/></td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
<div className="col col--4 pattern-logo">
|
||||
<img src={useBaseUrl('img/recipes/Multiwin.svg')} alt="Multiwin" />
|
||||
</div>
|
||||
<div className="col col--4">
|
||||
Pros:
|
||||
<ul>
|
||||
<li>Windows can be spawned or destroyed at runtime</li>
|
||||
<li>Separation of concerns</li>
|
||||
</ul>
|
||||
Cons:
|
||||
<ul>
|
||||
<li>Somewhat complex</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
## Description
|
||||
|
||||
The Multiwin recipe will allow you to have multiple windows.
|
||||
|
||||
## Diagram
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A==>H
|
||||
H==>F
|
||||
H==>G
|
||||
subgraph WEBVIEW
|
||||
F
|
||||
end
|
||||
subgraph WINIT
|
||||
G
|
||||
end
|
||||
subgraph RUST
|
||||
A
|
||||
end
|
||||
A[Binary]
|
||||
F[Window]
|
||||
G[Window]
|
||||
H{Bootstrap}
|
||||
class WINIT other
|
||||
class RUST rust
|
||||
class WEBVIEW webview
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Here's what you need to add to your tauri.conf.json file:
|
||||
|
||||
```json
|
||||
"tauri": {
|
||||
"allowlist": {}, // all API endpoints are default false
|
||||
"windows": [{
|
||||
"title": "Window1",
|
||||
"label": "main",
|
||||
}, {
|
||||
"title": "Splash",
|
||||
"label": "splashscreen"
|
||||
}]
|
||||
}
|
||||
|
||||
```
|
||||
@@ -1,105 +0,0 @@
|
||||
---
|
||||
title: security
|
||||
---
|
||||
|
||||
# Security
|
||||
|
||||
This guide seeks to explain the high-level concepts and security features at the core of Tauri's design that make you, your apps, and your users safer by default.
|
||||
|
||||
:::info Note
|
||||
While we take every opportunity to help you harden your application - there are always underlying threats like BIOS attacks, memory rowhammering and other operating system vulnerabilities that are constantly being discovered and (in the best cases) responsibly disclosed.
|
||||
|
||||
Furthermore, there are many ways that development teams can cut corners and either leak sensitive information or leave doors wide open to any of a range of attacks. Security is a never-ending quest, and your users count on you to keep them safe.
|
||||
|
||||
Therefore, we highly recommend that you take some time to consider the security ramifications of everything that your application does, especially in the context of running on the semi-hostile platform of end-user devices.
|
||||
|
||||
If you need help or want a review, you are welcome to contact the Tauri team for security consultation.
|
||||
:::
|
||||
|
||||
## Security Researchers
|
||||
|
||||
If you feel that there is a security concern or issue with anything in Tauri, please do not publicly comment on your findings. Instead, reach out directly to our security team: security@tauri.app
|
||||
|
||||
Although we do not currently have a budget for Security Bounties, in some cases, we will consider rewarding responsible disclosure with our limited resources.
|
||||
|
||||
## No Server Required
|
||||
|
||||
Tauri enables you to construct an application that uses web technology for the user interface without requiring you to use a server to communicate with the backend. Even if you used advanced techniques of dynamic imports and offload work to the backend, no traffic can be sniffed on TCP ports or external processes - because they aren't there. This reduces not only the physical and virtual footprint of your final binary by a good deal, but it also reduces the surface area of potential attack vectors by removing them from the equation.
|
||||
|
||||
## Language Features of Rust
|
||||
|
||||
By turning to the programming language renowned for its memory safety and speed, Tauri simply erases whole classes of conventional attacks. "Use after free" just isn't something that can happen with Tauri.
|
||||
|
||||
## Dynamic Ahead of Time Compilation (AOT)
|
||||
|
||||
This compilation process happens several times during the bootstrapping phase of a Tauri app. Using our default dynamic Ahead of Time compiler, you can generate code references that are unique for every session and are still technically static code units.
|
||||
|
||||
## Function Hardening
|
||||
|
||||
### Functional ASLR
|
||||
|
||||
Functional address Space Layout Randomization techniques randomize function names at runtime and can implement OTP hashing, so no two sessions are ever the same. We propose a novel type of function naming at boot time and optionally after every execution. Using a UID for each function pointer prevents static attacks.
|
||||
|
||||
### Kamikaze Function Injection
|
||||
|
||||
This advanced type of fASLR using the `EVENT` API endpoint is a promise wrapped in a closure (with randomized handle) that Rust inserts at runtime into the WebView, where its interface is locked within the promise resolution handler and is nulled after execution.
|
||||
|
||||
### Bridge, don't serve
|
||||
|
||||
Instead of passing potentially unsafe functions, an event bridge can be used to pass messages and commands to named brokers at each respective side of the application.
|
||||
|
||||
### One Time Pad Tokenization and Hashing
|
||||
|
||||
Hashing important messages with an OTP salt, you are able to encrypt messages between the user interface and the Rust backend. We are currently investigating the use of additional sources of entropy, such as the amazing [Infinite Noise TRNG](https://13-37.org/en/shop/infinite-noise-trng/).
|
||||
|
||||
## System Features
|
||||
|
||||
### Allowing API
|
||||
|
||||
You have the ability to pick and choose which API functions are available to the UI and to Rust. If they are not enabled, the code will not be shipped with your app, which reduces binary size and attack surface. They are opt-in, so you have to consciously choose to progressively enhance your application.
|
||||
|
||||
### Content Security Policy Management
|
||||
|
||||
Preventing unauthorized code execution for websites has long since been "resolved" by using CSPs. Tauri can inject CSPs into the `index.html` of the user interface, and when using a localhost server, it will also send these headers to the UI or any other clients that connect with it.
|
||||
|
||||
### Decompilation is Difficult
|
||||
|
||||
This means that your apps cannot be easily decompiled, as is the case with Electron ASAR files, which makes the process of reverse engineering your project much more time-intensive and requires specialist training.
|
||||
|
||||
## Ecosystem
|
||||
|
||||
### Build Pipelines and Artifact Authenticity
|
||||
|
||||
The process of releasing our source-code artifacts is highly automated yet mandates kickoff and review from real humans. Our current release strategy uses a combination of GitHub Actions and IOTA Tangle publication
|
||||
|
||||
### Resilient PR and Approval Processes
|
||||
|
||||
Our WG-TECH reviews code changes, tags PRs with scope, and makes sure that everything stays up to date. And when its time to publish a new version, one of the maintainers tags a new release on dev, which:
|
||||
|
||||
- Validates core
|
||||
- Runs smoke tests
|
||||
- Audits security for crates and npm
|
||||
- Generates changelogs
|
||||
- Creates artifacts
|
||||
- Publishes checksums to IOTA
|
||||
- Creates a draft release
|
||||
|
||||
Then the maintainer reviews the release notes, edits if necessary, and a new release is forged.
|
||||
|
||||
## Future Work
|
||||
|
||||
### Signed Binaries
|
||||
|
||||
Because the entire project is shipped within a monolithic binary, code can be signed for all distributables. (Currently using external tooling, but we are actively working on making the bundler a one-stop-shop.) This makes it virtually impossible for hackers to change an installed Application without the operating system noticing. [Reference](https://github.com/electron/asar/issues/123)
|
||||
|
||||
### Post-Binary Analysis
|
||||
|
||||
Use industrial-grade pentester-tooling (via our forthcoming Tauri-Frida GUI) to discover and fix security weaknesses in your final binaries.
|
||||
|
||||
### Post-Binary Enhancement
|
||||
|
||||
After the build is before the delivery and Tauri will provide you with tools never seen before. Stay tuned!
|
||||
|
||||
### Audits
|
||||
|
||||
We are currently in the process of our first external audit. When complete, we will publish the results here.
|
||||
@@ -1,67 +0,0 @@
|
||||
---
|
||||
title: benchmarks
|
||||
---
|
||||
|
||||
# Benchmarks
|
||||
|
||||
import Chart, { fetchData } from '@theme/BenchmarkChart'
|
||||
|
||||
<!-- Data is fetched here so that it is only fetched and processed once, then reused in each of the charts -->
|
||||
|
||||
export var data = fetchData()
|
||||
|
||||
All benchmarks run on GitHub Actions using the `ubuntu-latest` matrix. Various metrics are measured by the following applications:
|
||||
|
||||
| Tauri | Wry | Electron |
|
||||
| :-------------------- | :-------------------- | :----------------------- |
|
||||
| [tauri_cpu_intensive] | [wry_cpu_intensive] | [electron_cpu_intensive] |
|
||||
| [tauri_hello_world] | [wry_hello_world] | [electron_hello_world] |
|
||||
| [tauri_3mb_transfer] | [wry_custom_protocol] | [electron_3mb_transfer] |
|
||||
|
||||
[tauri_cpu_intensive]: https://github.com/tauri-apps/tauri/tree/dev/tooling/bench/tests/cpu_intensive
|
||||
[tauri_hello_world]: https://github.com/tauri-apps/tauri/tree/dev/tooling/bench/tests/helloworld
|
||||
[tauri_3mb_transfer]: https://github.com/tauri-apps/tauri/tree/dev/tooling/bench/tests/files_transfer
|
||||
[wry_cpu_intensive]: https://github.com/tauri-apps/wry/tree/dev/bench/tests/src/cpu_intensive.rs
|
||||
[wry_hello_world]: https://github.com/tauri-apps/wry/tree/dev/bench/tests/src/hello_world.rs
|
||||
[wry_custom_protocol]: https://github.com/tauri-apps/wry/tree/dev/bench/tests/src/custom_protocol.rs
|
||||
[electron_cpu_intensive]: https://github.com/tauri-apps/benchmark_electron/tree/dev/apps/cpu_intensive
|
||||
[electron_hello_world]: https://github.com/tauri-apps/benchmark_electron/tree/dev/apps/hello_world
|
||||
[electron_3mb_transfer]: https://github.com/tauri-apps/benchmark_electron/tree/dev/apps/file_transfer
|
||||
|
||||
:::note
|
||||
The CPU intensive benchmark measures how much time it takes to calculate all the prime numbers under a certain value without blocking the UI and reporting how many have been found so far using web workers.
|
||||
:::
|
||||
|
||||
## Execution Time
|
||||
|
||||
How much time in total it takes to initialize the application and wait for the `DOMContentLoaded` event. This uses [hyperfine](https://github.com/sharkdp/hyperfine) under the hood and runs 3 warm-up sequence first, then 10 sequences to calculate the average execution time.
|
||||
|
||||
<Chart data={data} column="exec_time" />
|
||||
|
||||
## Binary Size
|
||||
|
||||
All binaries are compiled in release mode.
|
||||
|
||||
<Chart data={data} column="binary_size" />
|
||||
|
||||
## Memory Usage
|
||||
|
||||
Uses [mprof](https://pypi.org/project/memory-profiler/) to get the max memory usage during execution. Smaller is better.
|
||||
|
||||
<Chart data={data} column="max_memory" />
|
||||
|
||||
## Thread Count
|
||||
|
||||
How many threads the application uses. Smaller is better.
|
||||
|
||||
<Chart data={data} column="thread_count" />
|
||||
|
||||
## Syscall Count
|
||||
|
||||
How many total syscalls are performed when executing a given application. Smaller is better.
|
||||
|
||||
<Chart data={data} column="syscall_count" />
|
||||
|
||||
## Dependencies
|
||||
|
||||
<Chart data={data} column="cargo_deps" />
|
||||
@@ -1,120 +0,0 @@
|
||||
---
|
||||
title: configuration files
|
||||
---
|
||||
|
||||
# Configuration Files
|
||||
|
||||
Since Tauri is a toolkit for building applications there can be many files to configure project settings. Some common files that you may run across are `tauri.conf.json`, `package.json` and `Cargo.toml`. We briefly explain each on this page to help point you in the right direction for which file to modify.
|
||||
|
||||
## Tauri Config
|
||||
|
||||
The file can be either `tauri.conf.json`, `tauri.conf.json5`, or `Tauri.toml`. The default is `tauri.conf.json`. See the note below for more information.
|
||||
|
||||
This is the file used by the Tauri process. You can define build settings (such as the [command run before `tauri build`][before-build-command] or [`tauri dev`][before-dev-command]), set the [name and version of your app][package-config], [control the Tauri process][tauri-config], and configure any plugin settings. You can find all of the options in the [`tauri.conf.json` API reference].
|
||||
|
||||
:::note
|
||||
|
||||
The default Tauri config format is `.json`. The `.json5` or `.toml` format can be enabled by adding the `config-json5` or `config-toml` feature flag (respectively) to the `tauri` and `tauri-build` dependencies in `Cargo.toml`. Note that the `.toml` format is only available from Tauri 1.1 and above.
|
||||
|
||||
```toml title=Cargo.toml
|
||||
[build-dependencies]
|
||||
// highlight-next-line
|
||||
tauri-build = { version = "1.0.0", features = [ "config-json5" ] }
|
||||
|
||||
[dependencies]
|
||||
serde_json = "1.0"
|
||||
serde = { version = "1.0", features = ["derive"] }
|
||||
// highlight-next-line
|
||||
tauri = { version = "1.0.0", features = [ "api-all", "config-json5" ] }
|
||||
```
|
||||
|
||||
The structure and values are the same across all formats, however, the formatting should be consistent with the respective file's format.
|
||||
|
||||
:::
|
||||
|
||||
## `Cargo.toml`
|
||||
|
||||
Cargo's manifest file is used to declare Rust crates your app depends on, metadata about your app, and other Rust-related features. If you do not intend to do backend development using Rust for your app then you may not be modifying it much, but it's important to know that it exists and what it does.
|
||||
|
||||
Below is an example of a barebones `Cargo.toml` file for a Tauri project:
|
||||
|
||||
```toml title=Cargo.toml
|
||||
[package]
|
||||
name = "app"
|
||||
version = "0.1.0"
|
||||
description = "A Tauri App"
|
||||
authors = ["you"]
|
||||
license = ""
|
||||
repository = ""
|
||||
default-run = "app"
|
||||
edition = "2021"
|
||||
rust-version = "1.57"
|
||||
|
||||
[build-dependencies]
|
||||
tauri-build = { version = "1.0.0" }
|
||||
|
||||
[dependencies]
|
||||
serde_json = "1.0"
|
||||
serde = { version = "1.0", features = ["derive"] }
|
||||
tauri = { version = "1.0.0", features = [ "api-all" ] }
|
||||
|
||||
[features]
|
||||
# by default Tauri runs in production mode
|
||||
# when `tauri dev` runs it is executed with `cargo run --no-default-features` if `devPath` is an URL
|
||||
default = [ "custom-protocol" ]
|
||||
# this feature is used for production builds where `devPath` points to the filesystem
|
||||
# DO NOT remove this
|
||||
custom-protocol = [ "tauri/custom-protocol" ]
|
||||
```
|
||||
|
||||
The most important parts to take note of are the `tauri-build` and `tauri` dependencies. Generally, they must both be on the latest minor versions as the Tauri CLI, but this is not strictly required. If you encounter issues while trying to run your app you should check that any Tauri versions (`tauri` and `tauri-cli`) are on the latest versions for their respective minor releases.
|
||||
|
||||
Cargo version numbers use [Semantic Versioning]. Running `cargo update` will pull the latest available Semver-compatible versions of all dependencies. For example, if you specify `1.0.0` as the version for `tauri-build`, Cargo will detect and download version `1.0.4` because it is the latest Semver-compatible version available. Tauri will update the major version number whenever a breaking change is introduced, meaning you should always be capable of safely upgrading to the latest minor and patch versions without fear of your code breaking.
|
||||
|
||||
If you want to use a specific crate version you can use exact versions instead by prepending `=` to the version number of the dependency:
|
||||
|
||||
```
|
||||
tauri-build = { version = "=1.0.0" }
|
||||
```
|
||||
|
||||
An additional thing to take note of is the `features=[]` portion of the `tauri` dependency. Running `tauri dev` and `tauri build` will automatically manage which features need to be enabled in your project based on the `"allowlist"` properties you set in `tauri.conf.json`.
|
||||
|
||||
When you build your application a `Cargo.lock` file is produced. This file is used primarily for ensuring that the same dependencies are used across machines during development (similar to `yarn.lock` or `package-lock.json` in Node.js). Since you are developing a Tauri app, this file should be committed to your source repository (only Rust libraries should omit committing this file).
|
||||
|
||||
To learn more about `Cargo.toml` you can read more in the [official documentation][cargo-manifest].
|
||||
|
||||
## `package.json`
|
||||
|
||||
This is the package file used by Node.js. If the frontend of a Tauri app is developed using Node.js-based technologies (such as `npm`, `yarn`, or `pnpm`) this file is used to configure the frontend dependencies and scripts.
|
||||
|
||||
An example of a barebones `package.json` file for a Tauri project might look a little something like this:
|
||||
|
||||
```json title=package.json
|
||||
{
|
||||
"scripts": {
|
||||
"dev": "command-for-your-framework",
|
||||
"tauri": "tauri"
|
||||
},
|
||||
"dependencies": {
|
||||
"@tauri-apps/api": "^1.0",
|
||||
"@tauri-apps/cli": "^1.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
It's common to use the `"scripts"` section to store the command used to launch the frontend used by your Tauri application. The above file specifies the `dev` command that you can run using `yarn dev` or `npm run dev` to start the frontend framework.
|
||||
|
||||
The dependencies object specifies which dependencies Node.js should download when you run either `yarn` or `npm install` (in this case the Tauri CLI and API).
|
||||
|
||||
In addition to the `package.json` file you may see either a `yarn.lock` file or a `package-lock.json` file. These files assist in ensuring that when you download the dependencies later you'll get the exact same versions that you have used during development (similar to `Cargo.lock` in Rust).
|
||||
|
||||
To learn more about `package.json` you can read more in the [official documentation][npm-package].
|
||||
|
||||
[`tauri.conf.json` api reference]: ../api/config.md
|
||||
[before-build-command]: ../api/config.md#buildconfig.beforebuildcommand
|
||||
[semantic versioning]: https://semver.org
|
||||
[cargo-manifest]: https://doc.rust-lang.org/cargo/reference/manifest.html
|
||||
[npm-package]: https://docs.npmjs.com/cli/v8/configuring-npm/package-json
|
||||
[before-dev-command]: ../api/config.md#buildconfig.beforedevcommand
|
||||
[package-config]: ../api/config#packageconfig
|
||||
[tauri-config]: ../api/config#tauriconfig
|
||||
@@ -1,14 +0,0 @@
|
||||
---
|
||||
title: architecture
|
||||
---
|
||||
|
||||
import DocCardList from "@theme/DocCardList";
|
||||
import { useCurrentSidebarCategory } from "@docusaurus/theme-common";
|
||||
|
||||
# Architecture
|
||||
|
||||
Now that you have completed the Quick Start and have a basic Tauri application at hand, it is tempting to jump right in. We invite you, however, to resist this temptation for a couple more pages and learn more about the concepts and ideas behind Tauri. You will find developing an app is much like creating a traditional client-server application on the web, with a couple of subtle but important differences.
|
||||
|
||||
This section will cover Tauri's multi-process architecture, windows, and webviews and our design decisions to make your application more secure and resource-efficient.
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items} />
|
||||
@@ -1,81 +0,0 @@
|
||||
---
|
||||
title: security
|
||||
---
|
||||
|
||||
# Development Security
|
||||
|
||||
Whether you like it or not, today's applications live in operating systems that can be (and regularly are) compromised by any number of attacks. When your insecure application is a gateway for such lateral movement into the operating system, you are contributing to the tools that professional hackers have at their disposal. Don't be a tool.
|
||||
|
||||
This is why we have taken every opportunity to help you secure your application, prevent undesired access to system-level interfaces, and manufacture bullet-proof applications. Your users assume you are following best practices. We make that easy, but you should still be aware of the information below.
|
||||
|
||||
## Security Is A Community Responsibility
|
||||
|
||||
It is important to remember that the security of your Tauri application is the sum of the overall security of Tauri itself, all Rust and npm dependencies, your code, and the devices that run the final application. The Tauri Team does their best to do their part, the security community does its part, and you too should follow a few important best practices.
|
||||
|
||||
### Keep Your Application Up-To-Date
|
||||
|
||||
When releasing your app into the wild, you are also shipping a bundle that has Tauri in it. Vulnerabilities affecting Tauri may impact the security of your application. By updating Tauri to the latest version, you ensure that critical vulnerabilities are already patched and cannot be exploited in your application. Also be sure to keep your compiler (rustc) and transpilers (nodejs) up to date, because there are often security issues that are resolved.
|
||||
|
||||
### Evaluate Your Dependencies
|
||||
|
||||
While npm and Crates.io provide many convenient packages, it is your responsibility to choose trustworthy third-party libraries - or rewrite them in Rust. If you do use outdated libraries which are affected by known vulnerabilities or are unmaintained, your application security and good night's sleep could be in jeopardy. Use tooling like npm audit and cargo audit to automate this process, and lean on the security community's important work.
|
||||
|
||||
### Adopt More Secure Coding Practices
|
||||
|
||||
The first line of defense for your application is your own code. Although Tauri can protect you from common web vulnerabilities, such as Cross-Site Scripting based Remote Code Execution, improper configurations can have a security impact. Even if this were not the case, it is highly recommended to adopt secure software development best practices and perform security testing. We detail what this means in the next section.
|
||||
|
||||
### Educate Your Users
|
||||
|
||||
True security means that unexpected behaviour cannot happen. So in a sense, being more secure means having the peace of mind of knowing that ONLY those things that you want to happen can happen. In the real world, though, this is a utopian "dream". However, by removing as many vectors as possible and building on a solid foundation, your choice of Tauri is a signal to your users that you care about them, their safety, and their devices.
|
||||
|
||||
## Threat Models
|
||||
|
||||
Tauri applications are composed of many pieces at different points of the lifecycle. Here we describe classical threats and what you SHOULD do about them.
|
||||
|
||||
### Upstream Threats
|
||||
|
||||
Tauri is a direct dependency on your project, and we maintain strict authorial control of commits, reviews, pull requests, and releases. We do our best to maintain up-to-date dependencies and take action to either update or fork and fix. Other projects may not be so well maintained, and may not even have ever been audited. Please consider their health when integrating them, otherwise, you may have adopted architectural debt without even knowing it.
|
||||
|
||||
### Development Threats
|
||||
|
||||
We assume that you, the developer, care for your development environment. It is on you to make sure that your operating system, build toolchains, and associated dependencies are kept up to date.
|
||||
|
||||
A genuine risk all of us face is what is known as "supply-chain attacks", which are usually considered to be attacks on direct dependencies of your project. However, a growing class of attacks in the wild directly target development machines, and you would be well off to address this head-on.
|
||||
|
||||
One practice that we highly recommend, is to only ever consume critical dependencies from git using hash revisions at best or named tags as second best. This holds for Rust as well as the Node ecosystem. Also, consider requiring all contributors to sign their commits and protect Git branches and pipelines.
|
||||
|
||||
### Buildtime Threats
|
||||
|
||||
Modern organisations use CI/CD to manufacture binary artifacts. At Tauri, we even provide a GitHub Workflow for building on multiple platforms. If you create your own CI/CD and depend on third-party tooling, be wary of actions whose versions you have not explicitly pinned.
|
||||
|
||||
You should sign your binaries for the platform you are shipping to, and while this can be complicated and somewhat costly to set up, end users expect that your app is verifiably from you.
|
||||
|
||||
### Runtime Threats
|
||||
|
||||
We assume the webview is insecure, which has led Tauri to implement several protections regarding webview access to system APIs in the context of loading untrusted userland content.
|
||||
|
||||
You can read more in detail below, but using the CSP will lockdown types of communication that the Webview can undertake. Furthermore, [Context Isolation](#) prevents untrusted content or scripts from accessing the API within the Webview.
|
||||
|
||||
And please, whatever you do, **DO NOT** trust the results of cryptography using private keys in the Webview. Rust is there for a reason.
|
||||
|
||||
### Updater Threats
|
||||
|
||||
We have done our best to make shipping hot updates to the app as straightforward and secure as possible. However, all bets are off if you lose control of the manifest server, the build server, or the binary hosting service. If you build your own system, consult a professional OPS architect and build it properly.
|
||||
|
||||
## Secure Content Loading
|
||||
|
||||
Tauri restricts the [Content Security Policy] (CSP) of your HTML pages. Local scripts are hashed, styles and external scripts are referenced using a cryptographic nonce, which prevents unallowed content from being loaded.
|
||||
|
||||
:::warning
|
||||
Avoid loading remote content such as scripts served over a CDN as they introduce an attack vector. But any untrusted file can introduce new and subtle attack vectors.
|
||||
:::
|
||||
|
||||
The CSP protection is only enabled if `[tauri > security > csp]` is set on the Tauri configuration file. You should make it as restricted as possible, only allowing the webview to load assets from hosts you trust, and preferably own. At compile time, Tauri appends its nonces and hashes to the relevant CSP attributes automatically, so you only need to worry about what is unique to your application.
|
||||
|
||||
See [`script-src`], [`style-src`] and [CSP Sources] for more
|
||||
information about this protection.
|
||||
|
||||
[content security policy]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
|
||||
[`script-src`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src
|
||||
[`style-src`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src
|
||||
[csp sources]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#sources
|
||||
@@ -1,197 +0,0 @@
|
||||
---
|
||||
title: webview versions
|
||||
---
|
||||
|
||||
# Webview Versions
|
||||
|
||||
## WebView2 (Windows)
|
||||
|
||||
Tauri uses WebView2 which is based on Microsoft Edge and therefore Chromium. WebView2 can update itself, you are guaranteed a relatively recent chromium build on all Windows targets.
|
||||
|
||||
WebView2 is supported on Windows 7 and newer and comes preinstalled on Windows 11. On versions older than Windows 11 the installer generated by Tauri takes care of ensuring WebView2 is installed on the system.
|
||||
|
||||
## WebKit (macOS, iOS, & Linux)
|
||||
|
||||
Tauri uses WebKit on macOS (through [WKWebView](https://developer.apple.com/documentation/webkit/wkwebview?language=objc)) and Linux (through `webkit2gtk`).
|
||||
|
||||
### Interpreting WebKit Version Numbers
|
||||
|
||||
Webkit version numbers are quite complicated, so below is some helpful information to understand them.
|
||||
|
||||
WebKit version numbers are made up of 5 segments and a numeric prefix indicating which OS WebKit is built for:
|
||||
|
||||
> `$(SYSTEM_VERSION_PREFIX)$(MAJOR_VERSION).$(MINOR_VERSION).$(TINY_VERSION).$(MICRO_VERSION).$(NANO_VERSION)`
|
||||
|
||||
The numeric prefix is called the `SYSTEM_VERSION_PREFIX` and seems to be only present for macOS and iOS builds (not for Linux). Furthermore, if the last two segments are both `0` they can be omitted (so a version like `613.2.7.0.0` would be referred to as `613.2.7`).
|
||||
|
||||
As an example, the WebKit version shipped with Safari 15.5 on macOS Monterey (12.x) has the version number `17613.2.7.1.8`. You can interpret it like this:
|
||||
|
||||
- `SYSTEM_VERSION_PREFIX`: 17
|
||||
- `MAJOR_VERSION`: 613
|
||||
- `MINOR_VERSION`: 2
|
||||
- `TINY_VERSION`: 7
|
||||
- `MICRO_VERSION`: 1
|
||||
- `NANO_VERSION`: 8
|
||||
|
||||
Here is what the `SYSTEM_VERSION_PREFIX` values map to:
|
||||
|
||||
| macOS version | `SYSTEM_VERSION_PREFIX` |
|
||||
| ------------- | ----------------------- |
|
||||
| sdk=iphone\* | 8 |
|
||||
| 14.0 | 19 |
|
||||
| 13.0 | 18 |
|
||||
| 12.0 | 17 |
|
||||
| 11.0 | 16 |
|
||||
| 10.15 | 15 |
|
||||
| 10.14 | 14 |
|
||||
| 10.13 | 13 |
|
||||
| 10.12 | 12 |
|
||||
| 10.11 | 11 |
|
||||
|
||||
### macOS & iOS
|
||||
|
||||
On macOS, Tauri uses the webview that comes preinstalled with macOS since version 10.10 (Yosemite). It is considered a core component and is therefore updated with the regular OS updates. This means unsupported macOS versions **do not** receive WebKit updates.
|
||||
|
||||
To find the WebKit version used by `WKWebView` on your version of macOS you can use this command in the terminal:
|
||||
|
||||
```shell
|
||||
awk '/CFBundleVersion/{getline;gsub(/<[^>]*>/,"");print}' /System/Library/Frameworks/WebKit.framework/Resources/Info.plist
|
||||
```
|
||||
|
||||
#### WebKit Versions in Safari
|
||||
|
||||
The table below maps an OS version to the corresponding WebKit Safari versions so that you can use sites like [caniuse](https://caniuse.com) to figure out if a specific web platform feature is supported.
|
||||
|
||||
| OS Name | OS Version | WebKit Version | Safari Version | Notes |
|
||||
| ----------- | -------------------------------- | ---------------- | -------------- | ------------------------------------------------------------- |
|
||||
| Sonoma | 14.0 (Beta) | 616.1.14.11.11 | 17.0 | Verified on a 2023 M2 14" MacBook Pro |
|
||||
| Ventura | 13.4.1 | 615.2.9.11.7 | 16.5.1 | Verified on a 2023 M2 14" MacBook Pro |
|
||||
| | 13.3.1 | 615.1.26.11.23 | | Verified on a 2023 M2 14" MacBook Pro |
|
||||
| | 13.3 | 615.1.26.11.22 | 16.4 | Verified on a 2023 M2 14" MacBook Pro |
|
||||
| | 13.2.1 | 614.4.6.1.6 | | |
|
||||
| | 13.2 | ? | 16.3 | |
|
||||
| | 13.1 | 614.3.7.1.5 | 16.2 | Verified on a 2020 M1 13" MacBook Pro |
|
||||
| | 13.0.1 | | | Verified on a 2020 M1 13" MacBook Pro |
|
||||
| | 13.0 | 614.2.9.1.12 | 16.1 | Verified on a 2020 M1 13" MacBook Pro |
|
||||
| Monterey | 12.6 | | | Verified on a 2020 M1 13" MacBook Pro |
|
||||
| | 12.5.1 | 613.3.9.1.16 | 15.6.1 | Verified on a 2020 M1 13" MacBook Pro |
|
||||
| | 12.5 | [613.3.9.1.5] | 15.6 | Verified on a 2020 M1 13" MacBook Pro |
|
||||
| | 12.4 | [613.2.7.1.8] | 15.5 | Verified on a 2020 M1 13" MacBook Pro |
|
||||
| | 12.3.1 | [613.1.17.1.13] | | |
|
||||
| | 12.3 | [613.1.17.1.6] | 15.4 | |
|
||||
| | 12.2.1 | [612.4.9.1.8] | | |
|
||||
| | 12.2 | [612.4.9.1.5] | 15.3 | |
|
||||
| | 12.1.1 | | | |
|
||||
| | 12.1 | [612.3.6.1.6] | 15.2 | |
|
||||
| | 12.0.1 | [612.2.9.1.20] | 15.1 | |
|
||||
| | 12.0 | [612.1.29.41.4] | 15.0 | |
|
||||
| Big Sur | 11.6.7 | | | |
|
||||
| | 11.6.6 | | | |
|
||||
| | 11.6.5 | | | |
|
||||
| | 11.6.2 | | | |
|
||||
| | 11.6.1 | | | |
|
||||
| | 11.6 | | | |
|
||||
| | 11.5.2 | [611.3.10.1.6] | | |
|
||||
| | 11.5.1 | | | |
|
||||
| | 11.5 | [611.3.10.1.3] | 14.1.2 | |
|
||||
| | 11.4 | [611.2.7.1.4] | 14.1.1 | |
|
||||
| | 11.3.1 | | | |
|
||||
| | 11.3 | [611.1.21.161.3] | 14.1 | 24" M1 iMac received a special WebKit version [611.1.21.1.12] |
|
||||
| | 11.2.3 | [610.4.3.1.7] | | |
|
||||
| | 11.2.2 | | | |
|
||||
| | 11.2.1 | | | |
|
||||
| | 11.2 | [610.4.3.1.4] | 14.0.3 | |
|
||||
| | 11.1 | [610.3.7.1.9] | 14.0.2 | |
|
||||
| | 11.0.1 | [610.2.11.51.8] | | |
|
||||
| | 11.0 | [610.2.11.1.3] | 14.0.1 | Safari 14.0 was only ever available on iPhones |
|
||||
| Catalina | 10.15.7 Security Update 2022-004 | [609.4.1.1.1] | | |
|
||||
| | 10.15.7 | [609.4.1] | 13.1.3 | |
|
||||
| | 10.15.6 | [609.3.5.1.3] | 13.1.2 | |
|
||||
| | 10.15.5 | [609.2.9.1.2] | 13.1.1 | |
|
||||
| | 10.15.4 | [609.1.20.111.8] | 13.1 | |
|
||||
| | 10.15.3 | [608.5.11] | 13.0.5 | |
|
||||
| | 10.15.2 | [608.4.9.1.3] | 13.0.4 | |
|
||||
| | 10.15.1 | [608.3.10.1.4] | 13.0.3 | Verified on a 2014 15" MacBook Pro |
|
||||
| | 10.15 | [608.2.30.1.1] | 13.0.2 | |
|
||||
| Mojave | 10.14.6 | [608.1.49] | 13.0 | |
|
||||
| | 10.14.4 | [607.1.40.1.5] | 12.1 | |
|
||||
| | 10.14.3 | [606.4.5] | 12.0.3 | |
|
||||
| | 10.14.2 | [606.3.4] | 12.0.2 | |
|
||||
| | 10.14.1 | [606.2.104.1.1] | 12.0.1 | |
|
||||
| | 10.14 | [606.2.11] | 12.0 | |
|
||||
| High Sierra | 10.13.6 | [605.3.8] | 11.1.2 | |
|
||||
| | 10.13.5 | [605.2.8] | 11.1.1 | |
|
||||
| | 10.13.4 Security Update 2018-001 | [605.1.33.1.4] | 11.1 | |
|
||||
| | 10.13.4 | [605.1.33.1.2] | 11.1 | |
|
||||
| | 10.13.3 | [604.5.6] | 11.0.3 | |
|
||||
| | 10.13.2 Supplemental Update | [604.4.7.1.6] | 11.0.2 | 27" iMac Pro received a special WebKit version [604.4.7.10.6] |
|
||||
| | 10.13.2 | [604.4.7.1.3] | 11.0.2 | 27" iMac Pro received a special WebKit version [604.4.7.10.4] |
|
||||
| | 10.13.1 | [604.3.5] | 11.0.1 | |
|
||||
| | 10.13 | [604.1.38.1.6] | 11.0 | |
|
||||
|
||||
[613.3.9.1.5]: https://github.com/WebKit/WebKit/blob/7f88b99524540e94abcdef4d45c1c0324d63fb56/Source/WebKit/Configurations/Version.xcconfig
|
||||
[609.1.20.111.8]: https://github.com/WebKit/WebKit/blob/5c90480a38a86464b6b421c2fd28c744b43a4faa/Source/WebKit/Configurations/Version.xcconfig
|
||||
[609.2.9.1.2]: https://github.com/WebKit/WebKit/blob/ca54d252f3416c3ec64f80a084cb5c4ff7ba24f1/Source/WebKit/Configurations/Version.xcconfig
|
||||
[609.4.1]: https://github.com/WebKit/WebKit/blob/cb927e6151b5ef49c9ccfb13018f51471f8f1035/Source/WebKit/Configurations/Version.xcconfig
|
||||
[609.4.1.1.1]: https://github.com/WebKit/WebKit/blob/8df64286794c38efa4697b7c24658cb85204a070/Source/WebKit/Configurations/Version.xcconfig
|
||||
[609.3.5.1.3]: https://github.com/WebKit/WebKit/blob/30fc8a44f087596c60e98adb434c0b98eccb61bb/Source/WebKit/Configurations/Version.xcconfig
|
||||
[610.4.3.1.7]: https://github.com/WebKit/WebKit/blob/248c3283ebdec8bd8ae05d4d1d56390b0da28f27/Sour.3ce/WebKit/Configurations/Version.xcconfig
|
||||
[610.4.3.1.4]: https://github.com/WebKit/WebKit/blob/b152d7889c786689406f203cc4eefea509a90302/Source/WebKit/Configurations/Version.xcconfig
|
||||
[610.3.7.1.9]: https://github.com/WebKit/WebKit/blob/62e4387a5eab36ed075961d9ee9971f8c01a55bd/Source/WebKit/Configurations/Version.xcconfig
|
||||
[611.1.21.1.12]: https://github.com/WebKit/WebKit/blob/5aebddad42f6572ffb20d1cd1be8d22be9cf0101/Source/WebKit/Configurations/Version.xcconfig
|
||||
[610.2.11.51.8]: https://github.com/WebKit/WebKit/blob/388eae2d649eaecadaa11e1edc4248e54db583f7/Source/WebKit/Configurations/Version.xcconfig
|
||||
[610.2.11.1.3]: https://github.com/WebKit/WebKit/blob/f11e10bcbb474d8c65a870cc680b0964d6529748/Source/WebKit/Configurations/Version.xcconfig
|
||||
[611.1.21.161.3]: https://github.com/WebKit/WebKit/blob/7aaa117b91a6822c40761d6f4da2e3d27627602f/Source/WebKit/Configurations/Version.xcconfig
|
||||
[611.2.7.1.4]: https://github.com/WebKit/WebKit/blob/200180885a516f378d0253ffc7b950f98b3f9810/Source/WebKit/Configurations/Version.xcconfig
|
||||
[611.3.10.1.6]: https://github.com/WebKit/WebKit/blob/54099b931b220cf75dea154bb2e84a6a0582e87c/Source/WebKit/Configurations/Version.xcconfig
|
||||
[611.3.10.1.3]: https://github.com/WebKit/WebKit/blob/7253374f3302a64a15482d5303925d0cfa5eb610/Source/WebKit/Configurations/Version.xcconfig
|
||||
[612.1.29.41.4]: https://github.com/WebKit/WebKit/blob/983520ffb8f364ee765d081e0f51b6b66da3945b/Source/WebKit/Configurations/Version.xcconfig
|
||||
[612.2.9.1.20]: https://github.com/WebKit/WebKit/blob/0c76deb88d1c3b290ea6f8edf469929d08afe53c/Source/WebKit/Configurations/Version.xcconfig
|
||||
[612.3.6.1.6]: https://github.com/WebKit/WebKit/blob/2d561c2c5b8c1d12d85a6e52fe7e7e83ff179a15/Source/WebKit/Configurations/Version.xcconfig
|
||||
[612.4.9.1.8]: https://github.com/WebKit/WebKit/blob/cf0263b49d5753432d651e14537ed44e6185dc16/Source/WebKit/Configurations/Version.xcconfig
|
||||
[612.4.9.1.5]: https://github.com/WebKit/WebKit/blob/c4c7b01e26d3142b0e0d456381c6d313399c3269/Source/WebKit/Configurations/Version.xcconfig
|
||||
[613.2.7.1.8]: https://github.com/WebKit/WebKit/blob/b85867ab0dadcd371dd9859feff9033885748d47/Source/WebKit/Configurations/Version.xcconfig
|
||||
[613.1.17.1.13]: https://github.com/WebKit/WebKit/blob/8b92a7625ab76aed000ee5a3a1f6b68b20404449/Source/WebKit/Configurations/Version.xcconfig
|
||||
[613.1.17.1.6]: https://github.com/WebKit/WebKit/blob/151e184ecb1d669996ac6139f28640b1c71184e1/Source/WebKit/Configurations/Version.xcconfig
|
||||
[608.5.11]: https://github.com/WebKit/WebKit/blob/e0e5c8297429016745b55545b1454f02e40d83e1/Source/WebKit/Configurations/Version.xcconfig
|
||||
[608.4.9.1.3]: https://github.com/WebKit/WebKit/blob/37f92d461f8ff74ea5cbe8f0baac0b8c8f1f6e19/Source/WebKit/Configurations/Version.xcconfig
|
||||
[608.3.10.1.4]: https://github.com/WebKit/WebKit/blob/ba26f5d986fca25516e6e72bc35c89905b1ed39a/Source/WebKit/Configurations/Version.xcconfig
|
||||
[608.2.30.1.1]: https://github.com/WebKit/WebKit/blob/7b6a3e211037e2580cec885316f027a4b5b11b2d/Source/WebKit/Configurations/Version.xcconfig
|
||||
[608.1.49]: https://trac.webkit.org/browser/webkit/releases/Apple/Safari%2013.0/WebKit/Configurations/Version.xcconfig
|
||||
[607.1.40.1.5]: https://trac.webkit.org/browser/webkit/releases/Apple/Safari%2012.1/WebKit/Configurations/Version.xcconfig
|
||||
[606.4.5]: https://github.com/WebKit/WebKit/blob/a833f886f9bd68c279322104c27498245d5b8dfb/Source/WebKit/Configurations/Version.xcconfig
|
||||
[606.3.4]: https://github.com/WebKit/WebKit/blob/676f488e26ea1f872a9b69756c17d417b5317f52/Source/WebKit/Configurations/Version.xcconfig
|
||||
[606.2.104.1.1]: https://github.com/WebKit/WebKit/blob/244ed4eb99ff394551c3d38fec58c1848b0ecdc3/Source/WebKit/Configurations/Version.xcconfig
|
||||
[606.2.11]: https://trac.webkit.org/browser/webkit/releases/Apple/Safari%2012.0/WebKit/Configurations/Version.xcconfig
|
||||
[605.1.33.1.2]: https://github.com/WebKit/WebKit/blob/25c0a6e3ca8e4a2dd41d4dcf52d70f27a912fef4/Source/WebKit/Configurations/Version.xcconfig
|
||||
[604.3.5]: https://trac.webkit.org/browser/webkit/releases/Apple/Safari%2011.0.1/WebKit/Configurations/Version.xcconfig
|
||||
[604.1.38.1.6]: https://github.com/WebKit/WebKit/blob/62f5206fadd2fd99c6e3060df4f57a7b7ddbbd1e/Source/WebKit/Configurations/Version.xcconfig
|
||||
[604.4.7.1.3]: https://github.com/WebKit/WebKit/blob/abe6ee6ad0f8fe44bd9ba476c818e4905c921ad3/Source/WebKit/Configurations/Version.xcconfig
|
||||
[604.5.6]: https://github.com/WebKit/WebKit/blob/3f76b1214e0deb75a2f813be9bd96b56d9da84df/Source/WebKit/Configurations/Version.xcconfig
|
||||
[604.4.7.10.4]: https://github.com/WebKit/WebKit/blob/1122bda2378b8a88d24b01a585f17e4286f14752/Source/WebKit/Configurations/Version.xcconfig
|
||||
[604.4.7.10.6]: https://github.com/WebKit/WebKit/blob/00051d7d17eb097dd60908d93a94a072080dec08/Source/WebKit/Configurations/Version.xcconfig
|
||||
[604.4.7.1.6]: https://github.com/WebKit/WebKit/blob/68ee2c6176b6d03fbee855cd727c9cf9b09314b1/Source/WebKit/Configurations/Version.xcconfig
|
||||
[605.1.33.1.4]: https://github.com/WebKit/WebKit/blob/69c0509d70d600dedaf55f448db8d887908b218c/Source/WebKit/Configurations/Version.xcconfig
|
||||
[605.2.8]: https://github.com/WebKit/WebKit/blob/66a695280db148a4f8306c95c62e891b34ff3f86/Source/WebKit/Configurations/Version.xcconfig
|
||||
[605.3.8]: https://github.com/WebKit/WebKit/blob/266f0468e067e0c2c0e1209313a34bdf5926aa38/Source/WebKit/Configurations/Version.xcconfig
|
||||
|
||||
### Linux
|
||||
|
||||
The diverse nature of the Linux ecosystem means it is very hard to compile accurate information about WebKitGTK on the various distros. The table below is a very incomplete list of the most commonly used distributions and their WebKit versions. You should always check your distro's repositories for up-to-date information.
|
||||
|
||||
| Distro | `webkitgtk` Version | WebKit Version | Safari Equivalent |
|
||||
| ----------------------------------------------------------------- | ------------------- | -------------- | ----------------- |
|
||||
| Debian 11 (with update), Ubuntu 20.04 (with update), Ubuntu 22.04 | 2.36 | [614.1.6] | TP 140 (16.0) |
|
||||
| Debian 10 (with update) | 2.34 | [613.1.1] | 15.4 |
|
||||
| Debian 11, Ubuntu 18.04 (with update), centos 8 (non-stream) | 2.32 | [612.1.6] | 15.0 |
|
||||
| Ubuntu 20.04 | 2.28 | [610.1.1] | 14.0 |
|
||||
| Debian 9 (with backport), Debian 10 | 2.24 | [608.1.6] | 13.0 |
|
||||
| Ubuntu 18.04 | 2.20 | [606.1.4] | 12.0 |
|
||||
|
||||
[614.1.6]: https://trac.webkit.org/browser/webkit/releases/WebKitGTK/webkit-2.36/Source/WebKit/Configurations/Version.xcconfig
|
||||
[613.1.1]: https://trac.webkit.org/browser/webkit/releases/WebKitGTK/webkit-2.34/Source/WebKit/Configurations/Version.xcconfig
|
||||
[612.1.6]: https://trac.webkit.org/browser/webkit/releases/WebKitGTK/webkit-2.32/Source/WebKit/Configurations/Version.xcconfig
|
||||
[610.1.1]: https://trac.webkit.org/browser/webkit/releases/WebKitGTK/webkit-2.28/Source/WebKit/Configurations/Version.xcconfig
|
||||
[608.1.6]: https://trac.webkit.org/browser/webkit/releases/WebKitGTK/webkit-2.24/Source/WebKit/Configurations/Version.xcconfig
|
||||
[606.1.4]: https://trac.webkit.org/browser/webkit/releases/WebKitGTK/webkit-2.20/Source/WebKit/Configurations/Version.xcconfig
|
||||
[605.1.3]: https://trac.webkit.org/browser/webkit/releases/WebKitGTK/webkit-2.18/Source/WebKit/Configurations/Version.xcconfig
|
||||
@@ -1,3 +0,0 @@
|
||||
---
|
||||
title: Command Line Interface
|
||||
---
|
||||
@@ -1,3 +0,0 @@
|
||||
---
|
||||
title: Rust API
|
||||
---
|
||||
@@ -14,6 +14,7 @@ So, you want to write a doc? You've come to the right place!
|
||||
- [ ] Do we want to do a branding update?
|
||||
- [ ] Favicon
|
||||
- [ ] Do some testing around the dev & CI workflows with the JS API submodules
|
||||
- [ ] https://www.feelback.dev/blog/new-astro-starlight-integration/
|
||||
|
||||
## Types of Documentation
|
||||
|
||||
@@ -24,6 +25,15 @@ We have the following types of documents that roughly follow the types defined b
|
||||
- **[Reference](#recipe)**: Information-oriented
|
||||
- **[Blog Post](#blog-post)**: Understanding-oriented
|
||||
|
||||
Use this chart to help you figure out where the right place for your content is:
|
||||
|
||||
| If the content describes… | …and serves the user’s… | …then it must belong to… |
|
||||
| ------------------------- | ----------------------- | ------------------------- |
|
||||
| practical steps | study | [a guide](#guide) |
|
||||
| practical steps | work | [a recipe](#recipe) |
|
||||
| theoretical knowledge | work | [a reference](#reference) |
|
||||
| theoretical knowledge | study | [a blog post](#blog-post) |
|
||||
|
||||
:::tip[What is Diátaxis?]
|
||||
|
||||
[Diátaxis](https://diataxis.fr/index.html#) is a technical documentation system that helps with documentation quality and information hierarchy. Since Tauri is such a large project we do our best to organize information as best as possible.
|
||||
@@ -70,6 +80,11 @@ TODO:
|
||||
|
||||
We'd like to keep the sidebar flexible as we gather feedback from the community. Right now we prefer a minimal approach so that it isn't overwhelming to new readers but we understand there's also a balance to making information discoverable.
|
||||
|
||||
- Guides
|
||||
- Recipes
|
||||
- References
|
||||
- Max 7 entries each
|
||||
|
||||
## Translations (i18n)
|
||||
|
||||
While we plan to support translations in the future, we are not currently accepting them until Tauri 2.0 is a bit more stable.
|
||||
|
||||
Reference in New Issue
Block a user